README.md

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.

Agent Flow visualization

Why Agent Flow?

I built Agent Flow while developing CraftMyGame, a game creation platform driven by AI agents. Debugging agent behavior was painful, so we made it visual. Now we're sharing it.

Claude Code is powerful, but its execution is a black box — you see the final result, not the journey. 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: Watch agent execution as an 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 from Codex's own event stream
Multi-session support: Track multiple concurrent agent sessions with tabs
Interactive canvas: Pan, zoom, click agents and tool calls to inspect details
Timeline & transcript panels: Review the 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

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/patoles/agent-flow.git
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 — events will stream to the browser in real-time.

VS Code Extension

Install the extension
Open the Command Palette (Cmd+Shift+P) and run Agent Flow: Open Agent Flow
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 `co

agent-flow