multi-agent-flow

Real-time visualization of Claude Code and Codex agent orchestration. Watch your agents think, branch, and coordinate as they work. Demo video here.

A performance-focused fork of patoles/agent-flow with multi-window support and a benchmark harness for tracking render-path regressions.

Why?

Claude Code is powerful, but its execution is a black box — you see the final result, not the journey. multi-agent-flow makes the invisible visible:

• Understand agent behavior — See how Claude breaks down problems, which tools it reaches for, and how subagents coordinate
• Debug tool call chains — When something goes wrong, trace the exact sequence of decisions and tool calls that led there
• See where time is spent — Identify slow tool calls, unnecessary branching, or redundant work at a glance
• Learn by watching — Build intuition for how to write better prompts by observing how Claude interprets and executes them

Features

• Live agent visualization: Interactive node graph with real-time tool calls, branching, and return flows
• Claude Code + Codex: Auto-detects sessions from both runtimes concurrently and shows them side-by-side, or restrict to one via the agentVisualizer.runtime setting
• Claude Code hooks: Lightweight HTTP hook server receives events directly from Claude Code for zero-latency streaming
• Codex rollout tailing: Reads ~/.codex/sessions/**/rollout-*.jsonl (respects CODEX_HOME) and surfaces tool calls, reasoning, and authoritative token counts
• Multi-session support: Track multiple concurrent agent sessions
• Interactive canvas: Pan, zoom, click agents and tool calls to inspect details
• Timeline & transcript panels: Full execution timeline, file attention heatmap, and message transcript
• JSONL log file support: Point at any JSONL event log to replay or watch agent activity

Fork additions

• Multi-window panels — detach sessions into independent window.open'd panels; render-rAF auto-pauses for hidden / minimized panels
• Page-wide FPS indicator in the top bar
• Shared simulation manager with one rAF loop across all sessions, plus typed-array agent position buffers

Getting Started

Quick Start (no VS Code required)

npx agent-flow-app

This starts the visualizer in your browser. Start a Claude Code session in another terminal — events will stream in real-time.

Options:

• --port <number> — change the server port (default: 3001)
• --no-open — don't open the browser automatically
• --verbose — show detailed event logs

Standalone Web App (from source)

git clone https://github.com/DFearing/multi-agent-flow.git
cd multi-agent-flow
pnpm i
pnpm run setup      # configure Claude Code hooks (one-time)
pnpm run dev        # start the web app + event relay

Open http://localhost:3000 and start a Claude Code session in another terminal — events will stream to the browser in real-time.

VS Code Extension

1. Install the extension
2. Open the Command Palette (Cmd+Shift+P) and run Agent Flow: Open Agent Flow
3. Start a Claude Code or Codex session in your workspace — Agent Flow will auto-detect it

Agent Flow automatically configures Claude Code hooks the first time you open the panel. To manually reconfigure, run Agent Flow: Configure Claude Code Hooks from the Command Palette.

Runtime selection

By default Agent Flow watches both Claude Code (~/.claude/projects/) and Codex (~/.codex/sessions/) concurrently in all three entry points (VS Code extension, pnpm run dev, npx agent-flow-app). Sessions are shown side-by-side and tagged by runtime. If you only use one, the other is a harmless no-op — no visible effect, no user action needed.

To restrict to one runtime:

• VS Code extension: set agentVisualizer.runtime to "auto" / "claude" / "codex" in your settings
• pnpm run dev and npx agent-flow-app: set the AGENT_FLOW_RUNTIME environment variable to claude or codex (defaults to watching both)

For non-default Codex installs, set the CODEX_HOME environment variable.

JSONL Event Log

You can also point Agent Flow at a JSONL event log file:

1. Set agentVisualizer.eventLogPath in your VS Code settings to the path of a .jsonl file
2. Agent Flow will tail the file and visualize events as they arrive

Commands

Command	Description
Agent Flow: Open Agent Flow	Open the visualizer panel
Agent Flow: Open Agent Flow to Side	Open in a side editor column
Agent Flow: Connect to Running Agent	Manually connect to an agent session
Agent Flow: Configure Claude Code Hooks	Set up Claude Code hooks for live streaming

Keyboard Shortcut

Shortcut	Action
Cmd+Alt+A (Mac) / Ctrl+Alt+A (Win/Linux)	Open Agent Flow

Settings

Setting	Default	Description
agentVisualizer.runtime	"auto"	Which agent runtime(s) to watch: "auto" (both), "claude", or "codex"
agentVisualizer.devServerPort	0	Development server port (0 = production mode)
agentVisualizer.eventLogPath	""	Path to a JSONL event log file to watch
agentVisualizer.autoOpen	false	Auto-open when an agent session starts

Requirements

• Node.js 20+ (LTS recommended)
• pnpm
• Claude Code CLI
• For the VS Code extension: a VSCode-compatible IDE 1.85+ (e.g. VS Code, Cursor, Windsurf)

Development

pnpm i              # install dependencies for all packages
pnpm run setup      # configure Claude Code hooks (one-time)
pnpm run dev        # start dev server + event relay

pnpm run dev starts both the Next.js dev server and an event relay that receives Claude Code events and streams them to the browser via SSE.

Other scripts:

Script	Description
pnpm run dev:demo	Start with demo/mock data
pnpm run dev:relay	Run the event relay server standalone
pnpm run dev:extension	Watch-build the extension
pnpm run build:all	Production build (webview + extension)
pnpm run build:web	Build the Next.js web app
pnpm run build:extension	Build the extension
pnpm run build:webview	Build the webview assets
pnpm run build:app	Build the standalone Node binary (relay + prebuilt webview, single-port)
pnpm sim <scenario>	Replay a deterministic event scenario into the running relay
pnpm test	Run the relay + extension test suites

Scenario simulator (pnpm sim)

A deterministic wire-format simulator that writes JSONL event files in the layout the relay expects. Use it to drive the visualizer without needing a live agent session — useful for development, demos, and the benchmark harness.

pnpm sim --list                    # list available scenarios
pnpm sim concurrent                # 3 sessions × 3 subagents/round, continuous
pnpm sim multi-session --speed 2   # run 2× faster

Scenarios live in scripts/sim/scenarios.ts: solo, tool-failure, subagents, multi-session, stress, permission-prompt, concurrent. The simulator only produces JSONL — start the relay separately (pnpm dev, pnpm dev:relay, or npx agent-flow-app).

Performance benchmark harness (bench/)

Empirical A/B/C harness that compares render performance across checkouts using a deterministic simulator workload and headless Chromium with CDP perf instrumentation. Measures FPS mean, frame-time p50/p95/p99, long-task count + total blocking time, scripting/task/layout time, heap peak/mean, and React commit count.

cd bench
pnpm install
pnpx playwright install chromium

node run-bench.mjs                       # all stacks × throttles × 5 reps (~60 min)
node run-bench.mjs --smoke --stack A-base  # ~50 s smoke
node run-bench.mjs --summarize           # re-aggregate without re-running

Outputs land in bench/results/: runs.jsonl (raw per-run rows + CDP snapshot) and summary.md (aggregated comparison + deltas). Full flag list, stack configuration, and caveats: see bench/README.md.

Star History

Author

Created by Simon Patole, for CraftMyGame.

Privacy & Telemetry

Agent Flow ships opt-out anonymous usage telemetry, enabled by default only in the published npx agent-flow-app binary. pnpm run dev and the VS Code extension emit nothing. Only aggregate events are sent — session count, duration, event count, OS/arch, Agent Flow version, distinct model IDs observed, which runtimes were watched, and error class names. Prompts, file paths, tool calls, user info, and environment variables are never sent.

• Turn off: export AGENT_FLOW_TELEMETRY=false or export DO_NOT_TRACK=1 (disabled installs write zero state to disk — no ~/.agent-flow/ directory)
• Inspect the payload: cat ~/.agent-flow/telemetry/events.jsonl
• Full schema + exact fields: see the v0.8.1 entry in extension/CHANGELOG.md or the serialize() function in scripts/telemetry.ts
• Reset your anonymous identity: delete ~/.agent-flow/installation-id — a fresh random UUIDv4 will be generated on next run

License

Apache 2.0 — see LICENSE for details.

The name "Agent Flow" and associated logos are trademarks of Simon Patole. See TRADEMARK.md for usage guidelines.