The Problem

Claude Code and Codex agents execute as black boxes. You see the final result, not the journey: which tools the agent reached for, how subagents branched and coordinated, where time went. Debugging multi-agent workflows means staring at logs and reconstructing behavior by hand.

What This Does

Agent Flow makes agent orchestration visible in real time. It watches Claude Code and Codex session files, streams events through a relay, and renders an interactive node graph of agent activity — tool calls, subagent spawns, reasoning, token counts, and message transcripts. The project is a portfolio of four self-contained pieces: a VS Code extension (extension/), a standalone web app (web/), a relay server (scripts/relay.ts), and a small app server (app/src/server.ts) that serves the visualizer via npx agent-flow-app.

The system auto-detects sessions from both runtimes concurrently, supports multi-session tabs, and can replay JSONL event logs. Claude Code hooks stream events via a local HTTP server for zero-latency updates; Codex sessions are tailed from ~/.codex/sessions/**/rollout-*.jsonl via extension/src/codex-session-watcher.ts.

How It Is Wired

Execution starts in three independent places. The VS Code extension boots from extension/src/extension.ts, which calls start in extension/src/codex-session-watcher.ts — that function reaches 90 functions and is called by nothing else in the repo. The web app's relay starts from main in scripts/dev-relay.ts, reaching 46 functions. The standalone app starts from startServer in app/src/server.ts, reaching 53 functions. From each entry point, the shortest path to a filesystem effect is short: start -> processExistingContent hits fs.readFileSync; main -> createRelay -> writeDiscoveryFile hits fs.writeFileSync; startServer -> init -> getOrCreateInstallId reads filePath directly.

The highest-blast-radius functions are elapsed (called from 19 places), fire (12), and asString (12). Three modules are hubs with 12–18 dependents: extension/src/constants.ts, extension/src/protocol.ts, and extension/src/logger.ts — churn in any of them ripples widely. The call graph shows 609 internal edges; generateStressScenario alone calls emit 21 times.

File-by-file map: extension/src/session-watcher.ts owns session detection and replay; extension/src/transcript-parser.ts handles message parsing; extension/src/webview-provider.ts manages the VS Code panel and generates nonces (the one crypto operation in the repo); web/lib/vscode-bridge.ts bridges the webview to the extension; web/hooks/simulation/types.ts defines the simulation state machine. A 5-module import cycle exists in web/hooks/simulation/ — changing those files requires touching mutually-dependent modules.

How To Use It

git clone https://github.com/moses-y/agent-flow
cd 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. For the standalone app: npx agent-flow-app (options: --port, --no-open, --verbose). Runtime selection is via the agentVisualizer.runtime setting in VS Code or the AGENT_FLOW_RUNTIME env var for the web app.

Real-World Use

A developer debugging a failed multi-agent build: start Agent Flow, run the Claude Code session that triggers the failure, then trace the exact sequence of tool calls and subagent spawns on the canvas. The timeline panel shows where time went; the transcript panel shows what each agent saw. The JSONL replay mode (extension/scripts/simulate-events.js) lets you replay a captured session for post-mortem analysis without re-running the agent.

Code Health & Issues

Static analysis found 27 findings: 6 high, 21 medium. The high-severity issues are an import cycle in web/hooks/simulation/ (3 files mutually reachable) and 37 duplicated 6-line blocks across 16 files, concentrated in extension/src/codex-session-watcher.ts, session-watcher.ts, and discovery.ts. Medium findings include 18 files with high branching density — extension/src/permission-detection.ts has 22 branch points over 63 lines.

SDLC gaps: no CI pipeline exists despite 115 source files — every merge ships unbuilt. The test suite covers only 5 files against 115 (ratio 0.043). No Dependabot or Renovate is configured for the 4 package manifests. app/src/server.ts uses exec() over a runtime value. The repo has a license, lockfile, and no committed secrets.

The Bottom Line

A genuinely useful debugging tool for anyone building on Claude Code or Codex — the visualization is the product, and the multi-runtime support is a real differentiator. The codebase is young: no CI, thin tests, and duplicated logic in the watchers will make maintenance painful as it grows. Worth adopting for agent-heavy development workflows; not yet production-hardened.