◇ AGENTVIZ

See what your AI agents actually do.

Drop a Claude Code 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, 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 session store
• Get AI coaching on prompt engineering, skills, and MCP setup grounded in best practices

git clone https://github.com/jayparikh/agentviz.git
cd agentviz
npm install
npm run dev

Opens at localhost:3000. Drop a .jsonl session file or click load a demo session to try it instantly.

# Point at a specific session file
node bin/agentviz.js ~/.claude/projects/my-project/session.jsonl

# Or pass a directory -- opens the most recently modified .jsonl inside it
node bin/agentviz.js ~/.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

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 (checks ~/.claude/projects/ and ~/.copilot/session-state/)
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 sessions from ~/.copilot/session-state/ and lists them in an inbox sorted by review priority. Click any session to open it in the visualizer.

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.

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 (S) isolates one track. Mute (M) 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. Double-click a 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, tool usage 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.

More formats planned: LangSmith traces, OpenTelemetry spans.

src/
  App.jsx                # Main orchestrator: file loading, playback, view routing
  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
    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 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
    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
    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)
    theme.js             # Design tokens (true black base, blue/purple/green accents)
    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 and layout merger for Graph view
    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
    playbackUtils.js     # Playback state helpers
  components/
    InboxView.jsx        # Session inbox with auto-discovery, sorting, and review priority
    DebriefView.jsx      # AI Coach panel with cached analysis and one-click apply
    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
    StatsView.jsx        # Aggregate metrics and tool ranking
    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
    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             # SVG icon component
    app/                 # Shell components: AppHeader, AppLandingState, AppLoadingState
    ui/                  # Shared primitives: BrandWordmark, ShellFrame, ToolbarButton
    waterfall/           # Waterfall sub-components: WaterfallChart, WaterfallRow, TimeAxis
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: serves dist/ SPA + SSE /api/stream file tail

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 }

npm run dev             # Vite dev server on port 3000
node bin/agentviz.js    # API backend on port 4242
npm run build           # Production build to dist/
npm test                # Run all tests via Vitest
npm run test:watch      # Watch mode

Full dev setup requires both servers. npm run dev starts the Vite frontend; node bin/agentviz.js starts the API backend (Coach, session discovery, config, apply, live streaming). Vite proxies /api/* to the backend automatically.

True black base (#000000) with blue, purple, and green accents. Vivid semantic colors: green for success, muted red for warning, bright red for error. All colors are defined as design tokens in src/lib/theme.js. JetBrains Mono throughout. No CSS framework; all styles are inline.

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

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

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

• Token count tracking and cost estimation per turn
• Tool execution waterfall / Gantt chart view
• Inline diff viewer for file-editing tool calls
• Live streaming mode (tail a session file in real time)
• CLI launcher: node bin/agentviz.js session.jsonl
• MCP server for Claude Code integration (launch_agentviz tool)
• Session comparison (dual-trace scorecard + tool usage chart)
• HTML export (self-contained shareable file, single session or comparison)
• Conversation flow graph (directed graph of turns and decisions)
• Inbox auto-discovery (Copilot CLI sessions found and ranked automatically)
• AI Coach agent (session analysis with one-click config recommendations)
• Autonomy metrics (human response time, idle gaps, intervention frequency)
• Bookmarks and annotations (persisted to localStorage)
• Graph minimap and large-session clustering
• Multi-agent hierarchy (parent/child agents, nested tracks)
• Shareable session URLs
• Vim-style keyboard navigation
• npx agentviz (publish to npm)

MIT