Agent Flow visualizes Claude Code and Codex sessions as a live node graph
Real-time visualization of Claude Code agent orchestration — see your agents think, branch, and coordinate as they work.
At a glance
- What is it?
- Agent Flow is a TypeScript visualizer, shipped as a VS Code extension and a standalone web app, that turns Claude Code and Codex agent execution into an interactive graph. It is useful for debugging tool call chains, and it is a viewer rather than a controller.
- Who is it for?
- Adopt Agent Flow if you already run Claude Code or Codex and need to see the order of tool calls when a session misbehaves. Skip it if you want a controller, a hosted dashboard, or a log format it does not already parse.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 66 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The debugging gap Agent Flow targets
Claude Code reports what it finished, not how it got there. The README frames this plainly: execution is a black box, and you see the final result rather than the journey. When a session produces a wrong edit or stalls, the useful information is the sequence of tool calls that preceded it, and that sequence is not the part the CLI surfaces by default. Agent Flow exists to expose that sequence as a graph. The author built it while working on CraftMyGame, a game creation platform driven by agents, because debugging agent behavior in that project was painful. That origin explains the shape of the tool: it is a debugging instrument for people who write prompts and then watch what the agent does with them, not a general purpose observability platform. The README lists four intended uses: understanding how a problem gets broken down, tracing tool call chains after a failure, spotting slow or redundant work, and building intuition for prompt writing. The last one is the softest claim in the list and the hardest to verify, but the first three map to concrete panels in the UI.
Two ingestion paths: HTTP hooks and rollout tailing
The mechanism differs by runtime, and the difference matters when you are deciding what you will actually see. For Claude Code, Agent Flow runs a lightweight HTTP hook server. Claude Code hooks post events to it, and the visualizer streams them onward, which the README describes as zero-latency streaming. For Codex, there are no hooks to install. Agent Flow instead tails files matching `~/.codex/sessions/**/rollout-*.jsonl`, respecting the `CODEX_HOME` environment variable for non-default installs. The README notes that this path surfaces tool calls, reasoning, and what it calls authoritative token counts from Codex's own event stream. That wording is a hint about a real asymmetry: with Codex, Agent Flow is reading a file the runtime already writes, so token accounting comes from the source. With Claude Code, the numbers arrive through the hook payload. Both runtimes can be watched at once. Sessions appear side by side and are tagged by runtime, and the README states that if you only use one, the other is a harmless no-op. There is a third ingestion path that has nothing to do with either runtime: point `agentVisualizer.eventLogPath` at any `.jsonl` file and Agent Flow tails it. That makes the visualizer usable for replaying a captured session, which is the more interesting capability for anyone doing post-mortems.
Getting it running without VS Code
The fastest path is a single command: `npx agent-flow-app`. That starts the visualizer in a browser and, by default, opens it. The README documents three flags: `--port <number>` to change the server port from its default of 3001, `--no-open` to suppress the browser launch, and `--verbose` for detailed event logs. You then start a Claude Code session in another terminal and events stream in. Running from source takes four commands: `git clone https://github.com/patoles/agent-flow.git`, `cd agent-flow`, `pnpm i`, then `pnpm run setup` to configure the Claude Code hooks once, and `pnpm run dev` to start the Next.js dev server plus the event relay on port 3000. The relay receives Claude Code events and pushes them to the browser over SSE. If you want to see the interface before wiring up a real session, `pnpm run dev:demo` starts it with mock data, which is the sensible first step. The extension route is install, then run Agent Flow: Open Agent Flow from the Command Palette. The README says the extension configures Claude Code hooks automatically the first time you open the panel, with a manual fallback command, Agent Flow: Configure Claude Code Hooks. Requirements are Node.js 20 or newer, pnpm, the Claude Code CLI, and an IDE at 1.85 or above for the extension.
Runtime selection and the settings that actually change behavior
Five settings are documented, and only two of them alter what gets ingested. `agentVisualizer.runtime` defaults to `"auto"`, which watches both runtimes; set it to `"claude"` or `"codex"` to restrict it. Outside VS Code, the equivalent is the `AGENT_FLOW_RUNTIME` environment variable, which accepts the same two values and defaults to watching both. `agentVisualizer.eventLogPath` defaults to an empty string and is the switch that turns on JSONL file tailing. The remaining three are ergonomic: `agentVisualizer.devServerPort` defaults to `0`, which the README describes as production mode; `agentVisualizer.autoOpen` defaults to `false`; and the port and verbose flags exist only on the CLI. There is a keyboard shortcut, `Cmd+Alt+A` on Mac and `Ctrl+Alt+A` on Windows and Linux. The commands table lists four palette entries, including one to open the panel in a side editor column and one to manually connect to a running agent session. If you are debugging a Codex install in a non-standard location, `CODEX_HOME` is the variable to set before anything else, because without it the rollout tailing will look in the default path and find nothing.
Where the tool stops being the right choice
Agent Flow is a viewer. Nothing in the README describes pausing, steering, or replaying a session with modified inputs. If your problem is that an agent took a wrong turn and you want to intervene, this shows you the turn and leaves the intervention to you. The runtime coverage is also narrower than the name suggests. The description mentions Claude Code, and the README adds Codex, but those are the only two runtimes with dedicated ingestion paths. Anything else has to be expressed as a JSONL event log in the format Agent Flow expects, and the README does not document that schema. That is a genuine gap: the `eventLogPath` setting is presented as a general escape hatch, but without a published event format you are reverse engineering it. Telemetry is worth flagging. The README states that the published `npx agent-flow-app` binary ships anonymous usage telemetry enabled by default, opt-out, and that `pnpm run dev` and the VS Code extension emit nothing. The privacy section is truncated in the supplied material, so the exact contents of the aggregate events are not something I can confirm. If you work somewhere that treats outbound telemetry as a procurement question, that truncation is the first thing to resolve, and the source route or the extension sidesteps it entirely.
How it differs from reading the JSONL yourself
The obvious alternative is not a competing visualizer. It is opening the session log in a terminal. Claude Code writes session data under `~/.claude/projects/`, Codex writes rollout files under `~/.codex/sessions/`, and both are JSONL. A `jq` pipeline over those files gives you the same underlying events with no install, no hook configuration, and no port to manage. The difference is in what each approach is good at. Grepping a JSONL file answers a question you already know how to ask: find the calls to a specific tool, count how many times a file was touched, pull the token totals. A node graph answers questions you have not formulated yet, because branching and return flows are visible as structure rather than as line offsets you have to reconstruct mentally. The timeline, transcript, and file attention heatmap panels described in the README are the parts that have no direct shell equivalent. The trade is real in the other direction too: a terminal pipeline works over SSH, works in CI, and does not care which IDE you use. Agent Flow needs a browser or a VS Code compatible editor, Node 20 or newer, and pnpm if you build from source.
Maintenance surface and licence
The repository is TypeScript, licensed Apache-2.0, not archived, and the release cadence visible in the supplied material is three releases between April and July 2026: v0.8.0 adding Codex runtime support, then v0.9.0 and v0.9.1 on the same day in July, covering model support, Codex discovery fixes, and a Windows Claude Code session discovery fix. That pattern, a feature release followed within minutes by a patch, suggests the discovery layer is where breakage concentrates. Session discovery depends on file layout in `~/.claude/projects/` and `~/.codex/sessions/`, and those paths are controlled by the runtimes, not by Agent Flow. A Windows discovery bug and Codex discovery fixes in the same window is consistent with that. Expect to update when Claude Code or Codex changes where it writes. The upgrade itself is cheap: reinstall the extension or re-run the npx command, and the hook configuration is a one-time `pnpm run setup` unless the hook payload format changes. Apache-2.0 permits commercial use and modification and includes a patent grant; it also requires that you retain the licence and notice files and state significant changes if you redistribute. That is a summary of the licence text, not legal advice, and if you plan to embed Agent Flow in a product you should read the full terms.
Editorial conclusion
Adopt Agent Flow if you already run Claude Code or Codex and need to see the order of tool calls when a session misbehaves. Skip it if you want a controller, a hosted dashboard, or a log format it does not already parse. Before installing, confirm your Node version is 20 or newer, check whether the opt-out telemetry in the npx agent-flow-app binary is acceptable in your environment, and verify that your IDE is 1.85 or above if you plan to use the extension.
Community notes