Agent Flight Recorder

Real-time dashboard for monitoring Claude Code subagent dispatch events.

Traditional Chinese (繁體中文)

What it does

Claude Code's subagent architecture is a black box — you can't observe which agents are running, what tools they call, or why they failed. Agent Flight Recorder makes it visible.

It reads Claude Code session transcripts directly from ~/.claude/projects/ and renders a real-time mission-control dashboard showing:

• Agent dispatch/return events with timestamps, status, and duration
• Call chains — the exact sequence of tool calls each agent made (Bash, Read, Skill, etc.)
• Skills tracking — which /skills each agent invoked
• Pipeline DAG — task nodes with fork/join connectors showing parallel branches and dependencies
• Parallel dispatch grouping — agents dispatched simultaneously are visually grouped with a fork indicator
• Session browser — switch between workspaces and historical sessions

Architecture

Claude Code Session
  +-- PreToolUse hook --> hook-handler.js --> events.jsonl
  +-- PostToolUse hook -> hook-handler.js --> events.jsonl

transcript-watcher.js
  +-- reads ~/.claude/projects/{workspace}/{session}/subagents/*.meta.json
  +-- reads ~/.claude/projects/{workspace}/{session}/subagents/*.jsonl
  +-- extracts: agent types, tool calls, skills, tasks, status

dashboard-server.js
  +-- GET /api/workspaces  --> list workspaces and sessions
  +-- GET /api/state       --> full session state (agents, events, tasks, call chains)
  +-- serves public/       --> dashboard UI

SKILL.md
  +-- /agent-flight-recorder       --> inject hooks + start server
  +-- /agent-flight-recorder stop  --> remove hooks + stop server

Zero npm dependencies. Built entirely with Node.js built-in modules.

Quick Start

1. Install as a Claude Code skill

Copy or symlink this directory so Claude Code can discover the SKILL.md:

# Example: symlink into a project's skills directory
ln -s /path/to/agent-flight-recorder /your-project/.claude/skills/agent-flight-recorder

Or add it to your global Claude Code settings.

2. Start the recorder

In any Claude Code session:

/agent-flight-recorder

This will:

1. Inject hooks into ~/.claude/settings.json (auto-detected by Claude Code's file watcher)
2. Start the dashboard server on http://localhost:3120

3. Open the dashboard

Navigate to http://localhost:3120 in your browser.

4. Dispatch agents and watch

Use Claude Code normally. Every Agent tool dispatch will appear in the dashboard in real time. Click any return event to expand the full call chain.

5. Stop when done

/agent-flight-recorder stop

Features

Feature	Description
Event Timeline	Vertical spine with dispatch/return nodes, status colors, and duration
Parallel Dispatch	Agents dispatched within 2 seconds are grouped with a fork indicator on the timeline
Call Chain Expansion	Click a return event to see every tool call in order. Click a node to see the full command
Skills Badges	Highlighted /skill tags inside expanded events
Pipeline DAG	Task nodes arranged by dependency depth. Parallel tasks shown side-by-side with SVG fork/join connectors
Agent Chips	Compact status indicators in the top bar
Session Browser	Dropdown to switch between workspaces and historical sessions
Transcript-based	Reads directly from Claude Code's transcript files — captures subagent activity that hooks miss
Stale Detection	Session status correctly shows "ENDED" when Claude Code exits

Pipeline Visualization

When agents create tasks with dependencies, the pipeline strip renders a DAG (directed acyclic graph):

Sequential:
  [Executor] -----> [Code Review] -----> [Deploy]

Parallel branches (same blockedBy):
  [Analysis] --+--> [Code Review] --+--> [Deploy]
               |                    |
               +--> [Test]     -----+

Tasks are grouped into layers by dependency depth. Tasks at the same depth render side-by-side with SVG fork/join curves between layers.

API

GET /api/workspaces

Returns all workspaces with their recent sessions.

GET /api/state?workspace=<slug>&session=<id>

Returns the full session state:

• sessionActive — whether the session is still running
• subagents[] — each with agentType, description, isActive, skills, toolCounts, callChain
• agentEvents[] — dispatch/return events with accurate status from transcripts
• tasks[] — pipeline tasks with subject, status, blockedBy

File Structure

agent-flight-recorder/
  SKILL.md                  # /agent-flight-recorder entry point
  hook-handler.js           # Claude Code hook script
  dashboard-server.js       # HTTP server (zero dependencies)
  debug-hook.js             # Dev tool: dump raw hook payloads
  public/
    index.html              # Dashboard HTML
    style.css               # Cyberpunk-lite dark theme
    app.js                  # Frontend logic (timeline, pipeline DAG, call chains)
  lib/
    settings-manager.js     # settings.json hook injection/restore
    transcript-watcher.js   # Claude Code transcript parser

Roadmap

Version	Feature	Status
v0.1	Event Timeline + Call Chains + Pipeline DAG	Current
v0.2	Agent Inventory (scan .claude/agents/*.md)	Planned
v0.3	Manual Pipeline Map (user-defined pipeline.json)	Planned
v0.4	Coordinator Parser (auto-detect from coordinator.md)	Planned

License

MIT License