AI coding agents can edit dozens of files, call tools, delegate to subagents, and recover from failures before returning one short answer. The final diff is visible; the path that produced it often is not.
patoles/agent-flow makes that path inspectable. It is an Apache-2.0 real-time visualizer for Claude Code and Codex that renders agents, tool calls, branches, returns, messages, and file activity as an interactive execution graph.
Agent Flow is useful for more than an attractive demo. It answers operational questions: Which subagent stalled? What tool call caused the delay? Why was a file touched repeatedly? Did parallel work converge cleanly? Which prompt produced unnecessary branching?
The project offers a standalone browser app, a source-based web app, and a VS Code extension. It can watch Claude Code and Codex concurrently, so teams do not need separate observability tools for each runtime.
What Agent Flow Is
Agent Flow is an observability interface for coding-agent execution. Instead of presenting a flat terminal transcript, it maps relationships between the parent agent, delegated agents, tool calls, messages, and returns.
Its current feature set includes:
- a live interactive node graph with pan, zoom, and detail inspection
- concurrent Claude Code and Codex session discovery
- tabs for multiple active sessions
- timeline and transcript panels
- a file-attention heatmap
- authoritative Codex token counts from rollout events
- arbitrary JSONL log watching and replay
- a standalone browser experience and a VS Code-compatible extension
This is an observability layer, not another coding agent. Agent Flow does not decide how agents should work; it helps humans understand how they did work.
How the Two Runtime Pipelines Work
Claude Code and Codex expose activity differently, so Agent Flow uses a runtime-specific collection path.
For Claude Code, a lightweight HTTP hook server receives events directly. In source mode, the relay forwards updates to the Next.js interface over Server-Sent Events. That gives the graph near-immediate updates as tools and subagents run.
For Codex, Agent Flow tails rollout files under ~/.codex/sessions/**/rollout-*.jsonl. It respects CODEX_HOME for non-default installations and reads the agent’s native event stream, including tool activity, reasoning events, and token accounting.
The visualizer can watch both sources at once. Sessions are tagged by runtime and displayed side by side. AGENT_FLOW_RUNTIME=claude or AGENT_FLOW_RUNTIME=codex can narrow standalone monitoring; the VS Code setting agentVisualizer.runtime provides the equivalent control.
Why Agent Observability Matters
A failed build tells you the outcome, not the decision chain. A large diff tells you what changed, not why an agent explored three abandoned paths first.
Visual traces help in four ways:
- Understand decomposition. See how a request became tasks and how work was delegated.
- Debug causality. Follow the exact tool-call chain preceding a wrong edit or failed test.
- Find waste. Spot slow calls, repeated reads, redundant branches, and idle subagents.
- Improve prompts. Compare execution shapes and learn which instructions produce focused work.
This becomes increasingly valuable as teams move from one agent in one terminal to several agents working concurrently.
Three Ways to Run It
The fastest route needs no clone:
npx agent-flow-app
The browser app uses port 3001 by default. --port, --no-open, and --verbose adjust launch behavior.
To develop from source:
git clone https://github.com/patoles/agent-flow.git
cd agent-flow
pnpm i
pnpm run setup
pnpm run dev
The development interface opens on http://localhost:3000. The repository requires Node.js 20+ and pnpm.
For an editor-native workflow, install the VS Code extension and run Agent Flow: Open Agent Flow. The extension supports VS Code-compatible editors version 1.85 or newer and automatically configures Claude Code hooks when its panel first opens.
A Practical Debugging Workflow
Start with a real task rather than a demo trace. Open Agent Flow, run a moderately complex refactor, and observe the graph without intervening.
After completion:
- inspect the longest nodes in the timeline
- open unexpected tool calls and read their inputs and results
- look for files with unusually high attention
- compare parent-agent work with delegated branches
- check whether branches returned useful evidence or duplicated one another
- connect the observed behavior back to the original prompt
The important metric is not the number of nodes. A large graph can represent sensible parallelism; a small graph can still contain a costly wrong assumption. Use the visualization to form a hypothesis, then verify it against the transcript and resulting code.
Privacy and Telemetry
Agent traces can contain sensitive development context, so collection boundaries matter.
According to the project, anonymous telemetry is opt-out and enabled by default only in the published npx agent-flow-app binary. Source development and the VS Code extension do not emit telemetry. The published binary reports aggregate operational fields such as session count, duration, event count, platform, version, observed model identifiers, watched runtimes, and error classes—not prompts, file paths, tool-call contents, user information, or environment variables.
Set AGENT_FLOW_TELEMETRY=false or DO_NOT_TRACK=1 to disable it. Teams should still review the current schema and their own data-handling requirements before adopting any observability tool.
Where Agent Flow Fits
Agent Flow is especially useful for:
- developers learning how coding agents interpret prompts
- teams debugging multi-agent orchestration
- maintainers evaluating agent efficiency and tool usage
- demos where a flat terminal log hides the architecture
- post-run reviews based on saved JSONL traces
It is less useful as a performance benchmark by itself. Visual activity is evidence, but not a quality score. Pair it with tests, code review, task success criteria, and cost or latency measurements.
Final Take
Coding agents are becoming systems rather than single chat turns. Once they branch, delegate, and operate concurrently, logs alone become difficult to reason about.
Agent Flow gives that execution a spatial model. Its combination of Claude Code hooks, Codex rollout parsing, multi-session tabs, graph exploration, timeline analysis, transcripts, and replay makes hidden orchestration inspectable without replacing the tools developers already use.
The project is a strong reminder that better agents need better observability. When you can see the flow, you can debug the work—and improve the instructions that shape it.
