patoles/agent-flow

Agent Flow – Visual Debugger for Claude Code & Codex Agents

What it is – A real‑time visualizer that turns the hidden inner‑workings of Claude Code and Codex AI agents into an interactive node‑graph. It shows how agents break problems into steps, call tools, spawn sub‑agents, and return results, letting you watch the whole “thought process” as it happens.

Why it matters – When building AI‑driven applications (e.g., the Antics game‑creation platform), developers often only see the final output of an LLM‑agent, making debugging a guess‑work exercise. Agent Flow exposes the execution trace, tool‑call chain, and timing information, so you can pinpoint slow or erroneous steps, understand branching logic, and improve prompt engineering.

Key features

• Live visualization – Interactive canvas with pan/zoom; nodes represent reasoning steps, tool calls, and sub‑agents.
• Dual‑runtime support – Works with Claude Code and Codex simultaneously; you can view both side‑by‑side or limit to one via a setting.
• Zero‑latency streaming – A lightweight HTTP hook receives Claude Code events directly; Codex events are read from its rollout JSONL logs.
• Multi‑session handling – Multiple concurrent agent sessions appear as tabs.
• Timeline & transcript panels – See a chronological view, file‑attention heatmap, and full message transcript.
• JSONL replay – Load any saved event log to replay past sessions.
• VS Code extension – Open the visualizer inside the editor with a single command or shortcut (Cmd/Ctrl+Alt+A).

How to use it

1. Quick start – Run npx agent-flow-app (Node 20+, pnpm) and a browser window opens on localhost:3001.
2. From source – Clone the repo, run pnpm i && pnpm run setup && pnpm run dev. The dev server hosts the Next.js web app and an event‑relay that streams SSE data to the UI.
3. VS Code – Install the extension, then run Agent Flow: Open Agent Flow from the command palette.
4. Configuration – Use the agentVisualizer.runtime setting or the AGENT_FLOW_RUNTIME env var to select Claude, Codex, or both. Point agentVisualizer.eventLogPath at a .jsonl file to visualize offline logs.

Typical workflow

• Start a Claude Code or Codex session in a terminal.
• Agent Flow automatically detects the session and begins streaming events.
• Watch the graph grow: each node shows the reasoning snippet, tool invoked, and timing.
• Click a node to inspect full details (prompt, response, token counts, etc.).
• Use the timeline panel to locate bottlenecks or unexpected branches.

Privacy – Telemetry is opt‑out and only sends anonymous aggregates (session count, duration, model IDs, OS). No prompts, file paths, or user data leave the machine. Disable via AGENT_FLOW_TELEMETRY=false or DO_NOT_TRACK=1.

Who built it – Simon Patole, the creator of the Antics AI‑driven game‑creation platform.

License – Apache 2.0.

---

Agent Flow is a genuine open‑source tool for visualizing and debugging LLM‑agent runtimes, fitting squarely within the AI/agent tooling ecosystem.