◇ AGENTVIZ

See what your AI agents actually do.

Drop a Claude Code, VS Code Copilot Chat, or Copilot CLI session file and explore the agent's reasoning, tool calls, turn flow, and output through replay, tracks, waterfall, graph, and stats views. Or run it from the CLI for a live view that updates as your session unfolds.

Move between replay, tracks, waterfall, graph, and stats views to inspect the same session from different angles.

AI coding agents (Claude Code, VS Code Copilot Chat, Copilot CLI, etc.) generate dense session logs, but reading raw JSONL is painful. AGENTVIZ turns those logs into something you can actually explore:

• Replay sessions like a video, stepping through each tool call and reasoning step
• Trace decision flow in a graph view with expandable turn and tool-call structure
• Visualize timing and concurrency in tracks and waterfall timelines
• Analyze tool usage patterns, error rates, and model behavior at a glance
• Debug failures by jumping directly between errors with one keystroke
• Stream live as a session unfolds -- the view updates in real time
• Discover sessions automatically from the Copilot CLI and VS Code session stores
• Get AI coaching on prompt engineering, skills, and MCP setup grounded in best practices
• Switch themes between dark, light, and system-matched modes with one click

npx agentviz

Opens AGENTVIZ in your browser. Drop a .jsonl or .json session file or click load a demo session to try it instantly. Copilot CLI and VS Code Copilot Chat sessions are auto-discovered.

npx agentviz ~/.claude/projects/my-project/session.jsonl

# Or pass a directory -- opens the most recently modified .jsonl inside it
npx agentviz ~/.claude/projects/my-project/

The browser opens with a pulsing LIVE badge. As Claude Code writes new events to the session file, they stream into the view in real time via SSE, including records that are written incrementally before the trailing newline lands.

# Claude Code sessions
ls ~/.claude/projects/

# Copilot CLI sessions
ls ~/.copilot/session-state/
# Each subdirectory is a session UUID containing an events.jsonl file

VS Code Copilot Chat sessions live under your VS Code workspaceStorage/*/chatSessions/ directories. The exact parent path depends on your OS and whether you use the stable or Insiders build.

AGENTVIZ ships as an MCP server so you can open it directly from Claude Code or GitHub Copilot in VS Code without leaving your workflow. Both agents use the same launch_agentviz and close_agentviz tools.

Setup (one time):

claude mcp add --scope user agentviz node /path/to/agentviz/mcp/server.js

This registers the server globally across all projects. Restart Claude Code to pick it up.

Usage: In any session, just ask:

"Open agentviz" or "Show me the live view"

Setup: Add the server to your VS Code user settings (settings.json) for global access across all projects:

{
  "mcp": {
    "servers": {
      "agentviz": {
        "type": "stdio",
        "command": "node",
        "args": ["/path/to/agentviz/mcp/server.js"]
      }
    }
  }
}

Or scope it to a single project by creating .vscode/mcp.json in your workspace:

{
  "servers": {
    "agentviz": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/agentviz/mcp/server.js"]
    }
  }
}

Reload VS Code after adding the config. In Copilot Chat, use Agent mode and ask:

"Open agentviz" or "Launch the live view"

launch_agentviz will:

1. Auto-detect the most recently active session file from Claude Code, Copilot CLI, or VS Code Copilot Chat storage
2. Start a local HTTP server on a free port
3. Open the browser with live streaming enabled

To stop it, ask: "Close agentviz"

When running via the CLI, AGENTVIZ automatically discovers recent Claude Code, Copilot CLI, and VS Code Copilot Chat sessions and shows them on the landing screen in two interchangeable modes: a row-based inbox sorted by review priority and a dashboard card grid with aggregate stats, filters, refresh, and the same one-click open flow.

Each session also gets an AI Coach analysis powered by the @github/copilot-sdk (gpt-4o). The coach reads your actual project config (.github/copilot-instructions.md, skills, MCP servers) and produces actionable recommendations for prompts, skills, and tooling setup. Recommendations can be applied directly with one click.

Load two agent traces side by side to compare them head to head. Great for benchmarking Claude Code vs Copilot CLI on the same task, or comparing two different prompting strategies.

• Landing screen -- click "compare two sessions" below the drop zone
• Single-session header -- click Compare while viewing any session to add a second trace for comparison
• Compare landing -- drop Session A and Session B independently; the view opens once both are loaded

Side-by-side metrics with delta badges:

Horizontal bar chart showing tool call counts for both sessions on the same axis. Blue bars = Session A, purple bars = Session B.

Click Export in any header to download a single self-contained .html file. Share it with anyone -- no server required. Opening it reproduces the full session or comparison view exactly as you see it.

Export is available in two places:

• Single session header -- exports the current session
• Comparison header -- exports both sessions and the full comparison view

Export requires the production build (npm run build). It is not available in the Vite dev server.

Drop zone for session files, with a demo session available instantly. When running via the CLI, the landing screen becomes a session browser with a List or Dashboard toggle for auto-discovered Claude Code, Copilot CLI, and VS Code Copilot Chat sessions.

Chronological event stream with a resizable inspector sidebar. Click any event to see full details plus a payload inspector with readable JSON or text, top-level keys, line and character counts, copy support, and expand or collapse controls. The colorful timeline bar at top shows event density and error locations.

DAW-style multi-track lanes for Reasoning, Tool Calls, Context, and Output. Solo isolates one track. Mute hides it. See at a glance how your agent's time was spent.

Gantt-style timeline of every tool call, sorted by start time with nesting for overlapping calls. Hover any bar to see duration and timing. Click to open the full inspector, including inline diffs for file edits and readable input or result payload previews.

Interactive directed graph of session turns with expandable tool-call structure. When a turn spawns parallel subagents, the graph automatically forks into side-by-side agent branches and rejoins at a diamond join node, visualizing concurrency without any interaction. Double-click any turn to open its internal tool flow, pan and zoom around the graph, and follow playback as active nodes light up and future nodes fade back.

Aggregate metrics, event distribution bars, tools used ranking, and a per-turn summary. Includes token counts and estimated USD cost per turn for Claude models.

AI-powered session coaching available directly from any session. The coach reads your autonomy metrics, project config (.github/copilot-instructions.md, MCP servers, skills), and session patterns to produce evidence-backed recommendations for prompts, tooling, and workflow. Click Analyze to run, then accept or ignore each draft recommendation. Requires the CLI server -- run via node bin/agentviz.js or the MCP tool.

Open the drawer with Cmd+Shift+K (or via the command palette). Questions are routed through a two-tier system:

1. Instant answers -- a local classifier matches 9 common patterns and responds immediately from session data, with no API call:

   Pattern	Example question
   Tool count	"how many tool calls?"
   Errors	"were there any errors?"
   Duration	"how long did this take?"
   Models	"what model was used?"
   Turns	"how many turns?"
   Longest tool	"which tool took the longest?"
   Cost	"how much did this cost?"
   File edits	"what files were edited?"
   Summary	"summarize this session"

2. Model fallback -- anything the classifier can't match is sent to the Copilot SDK (configurable model, see Configuration) with full session context for an AI-generated answer.

Feature flag: Session Q&A is experimental. Enable it with localStorage.setItem('agentviz:flag:qa', 'true') in the browser console.

Modals, drawers, and overlay panels render keyboard hints with a shared <kbd> badge treatment so close, navigate, and select affordances read consistently across AGENTVIZ.

More formats planned -- see Roadmap.

src/
  App.jsx                # Routing shell: file loading, session switching, compare mode
  main.jsx               # React entry point
  contexts/
    PlaybackContext.jsx  # Playback, search, track filtering, and derived state provider
  hooks/
    usePlayback.js       # Play/pause, speed, seek state machine
    useSearch.js         # Debounced full-text search with match highlighting
    useKeyboardShortcuts.js  # Centralized keyboard handler
    useSessionLoader.js  # File parsing, live init from /api/file, session reset
    useQA.js             # Session Q&A state: messages, classifier, SSE streaming, abort
    useFeatureFlag.js    # localStorage-backed feature flag evaluation
    useLiveStream.js     # SSE EventSource hook with 500ms debounce for live mode
    usePersistentState.js    # localStorage-backed useState with debounced writes
    useDiscoveredSessions.js # Auto-discovery of Copilot CLI and VS Code sessions via /api/sessions
    useHashRouter.js     # Hash-based routing between inbox and session views
    useAsyncStatus.js    # Async operation state machine (idle/loading/success/error)
  lib/
    parseSession.ts      # Auto-detect format router
    parser.ts            # Claude Code JSONL parser
    copilotCliParser.ts  # Copilot CLI JSONL parser
    vscodeSessionParser.ts # VS Code Copilot Chat JSON parser
    dataInspector.js     # Payload summary and preview helpers for inspector panels
    session.ts           # Pure helpers: getSessionTotal, buildFilteredEventEntries
    sessionLibrary.js    # localStorage-backed session library with content persistence
    sessionParsing.ts    # Session parsing utilities and types
    sessionTypes.ts      # TypeScript type definitions for session data
    autonomyMetrics.js   # Human response time, idle gaps, intervention scoring
    projectConfig.js     # Project config surface detection (CLAUDE.md, .github/, etc.)
    aiCoachAgent.js      # AI Coach powered by @github/copilot-sdk (gpt-4o)
    qaClassifier.js      # Session Q&A instant answer engine (9 patterns + model context)
    qaAgent.js           # Q&A agent powered by @github/copilot-sdk for model fallback
    theme.js             # Design tokens (dark/light/system mode-aware palette)
    theme.d.ts           # TypeScript declarations for theme.js
    constants.js         # Sample events for demo mode
    replayLayout.js      # Virtualized windowing for large sessions
    commandPalette.js    # Precomputed fuzzy search index
    diffUtils.js         # Diff detection and Myers line diff algorithm
    waterfall.ts         # Waterfall view helpers: item building, stats, layout
    graphLayout.js       # ELKjs graph builder, fork/join DAG for parallel agents, layout merger
    pricing.js           # Claude model pricing table and cost estimation
    exportHtml.js        # Self-contained HTML export for single sessions and comparisons
    formatTime.js        # Duration and date formatting utilities
    landingSessions.js   # Shared landing browser labels, filters, and format options
    playbackUtils.js     # Playback state helpers
  components/
    InboxView.jsx        # Session inbox with auto-discovery, sorting, refresh, and review priority
    DashboardView.jsx    # Landing dashboard card grid with shared landing controls, aggregate stats, and quick open
    DebriefView.jsx      # AI Coach panel with cached analysis (lazy-loaded)
    ReplayView.jsx       # Windowed event stream + inspector sidebar
    TracksView.jsx       # DAW-style multi-track timeline
    WaterfallView.jsx    # Tool execution waterfall with nesting and inspector
    GraphView.jsx        # Interactive turn graph with expandable tool-call nodes (lazy-loaded)
    StatsView.jsx        # Aggregate metrics, tool ranking, turn summary
    CompareView.jsx      # Side-by-side session comparison (Scorecard + Tools tabs)
    CommandPalette.jsx   # Cmd+K fuzzy search overlay
    Timeline.jsx         # Scrubable playback bar with event markers
    DiffViewer.jsx       # Inline unified diff for file-editing tool calls
    DataInspector.jsx    # Readable payload inspector with summaries and copy support
    LiveIndicator.jsx    # Pulsing LIVE badge shown in CLI streaming mode
    ShortcutsModal.jsx   # Keyboard shortcuts overlay
    QADrawer.jsx         # Session Q&A slide-over drawer with instant answers
    RecentSessionsPicker.jsx # Recent sessions dropdown picker
    SyntaxHighlight.jsx  # Lightweight code syntax coloring for payload previews
    ResizablePanel.jsx   # Drag-to-resize split panel utility
    FileUploader.jsx     # Drag-and-drop file input with error handling
    ErrorBoundary.jsx    # React error boundary with resetKey for recovery
    Icon.jsx             # Lucide icon wrapper; all icons must be imported AND added to ICON_MAP
    app/                 # Shell: AppHeader, AppLandingState, AppLoadingState, CompareLandingState, CompareShell (lazy-loaded; AppLandingState switches between inbox and dashboard landing modes)
    ui/                  # Shared primitives: BrandWordmark, ShellFrame, ToolbarButton, ToolbarSelect, ExportStatusButton, KeyboardHint
    waterfall/           # Waterfall sub-components: WaterfallChart, WaterfallRow, WaterfallInspector, TimeAxis
routes/
  sessions.js            # Session discovery, file serving, SSE streaming
  ai.js                  # Coach analysis, Q&A, model info (SSE streaming)
  config.js              # Project config surface detection, file preview, apply
bin/
  agentviz.js            # CLI entry point: finds free port, starts server, opens browser
mcp/
  server.js              # MCP server: launch_agentviz and close_agentviz tools
server.js                # HTTP server shell: static serving, file watcher, route dispatch

parseSession(text) auto-detects the format and returns a normalized structure:

// Every event has the same shape regardless of source format
{ t, agent, track, text, duration, intensity, toolName?, toolInput?, raw, turnIndex, isError, model?, tokenUsage?, parentToolCallId? }

// Turns group events by conversation round
{ index, startTime, endTime, eventIndices, userMessage, toolCount, hasError }

// Session-level stats
{ totalEvents, totalTurns, totalToolCalls, errorCount, duration, models, primaryModel, tokenUsage }

npx agentviz                         # Run without installing
npx agentviz session.jsonl           # Open a specific session file
npm start                            # Build and launch (from cloned repo)

AGENTVIZ can also be launched from Claude Code, VS Code, or Copilot CLI via the MCP launch_agentviz tool.

npm run dev             # Vite dev server + API backend (auto-started)
npm run build           # Production build to dist/
npm test                # Run all tests via Vitest
npm run test:watch      # Watch mode
npm run typecheck       # Type-check with tsc --noEmit

npm run dev starts both the Vite frontend (port 3000) and the API backend (port 4242) automatically. Vite proxies /api/* to the backend.

AGENTVIZ ships with full dark and light themes plus a System mode that follows your OS preference. The theme switcher is in the top bar (sun/moon/monitor icons). Your choice persists in localStorage across sessions.

• Dark mode (default): True black base (#0f0f16) with blue, purple, and green accents
• Light mode: Clean white base (#f8f9fc) with deeper, higher-contrast accent colors
• System mode: Automatically matches prefers-color-scheme and updates live if you change your OS setting

All colors are defined as design tokens in src/lib/theme.js with dynamic getters that resolve to the active palette at render time. A visual reference of every token in both modes is available in docs/color-palette.html. JetBrains Mono throughout. No CSS framework; all styles are inline.

AI Model -- The Coach and Session Q&A features use the Copilot SDK. You can override the model:

The current model can be queried via GET /api/models.

Feature Flags -- Experimental features are gated behind localStorage flags:

Enable a flag in the browser console:

localStorage.setItem('agentviz:flag:qa', 'true')

Contributions are welcome! Here are some areas where help is appreciated:

• New parsers: LangSmith, OpenTelemetry, custom agent frameworks
• Visualizations: Graph minimap, large-session clustering
• Features: Bookmarks/annotations, shareable URLs

Please open an issue to discuss larger changes before submitting a PR.

• Bookmarks and annotations (persisted to localStorage)
• Graph minimap and large-session clustering
• Shareable session URLs
• Vim-style keyboard navigation
• Parsers for LangSmith traces and OpenTelemetry spans

MIT