# Agent Flow: real-time visualization of Claude Code and Codex agent orchestration

> Agent Flow is a TypeScript VS Code extension and standalone web app that turns Claude Code and Codex session logs into a live node graph. It is useful when you need to see why an agent took a wrong turn, and less useful if you only want the final answer.

**patoles/agent-flow** — Real-time visualization of Claude Code agent orchestration — see your agents think, branch, and coordinate as they work.

- Repository: https://github.com/patoles/agent-flow
- Website: https://marketplace.visualstudio.com/items?itemName=simon-p.agent-flow
- Stars: 1,667 · Forks: 202
- Language: TypeScript
- License: Apache-2.0
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/patoles-agent-flow

## What Agent Flow solves, and who it is for

Claude Code runs as a black box. You give it a task, it emits tool calls, spawns subagents, and eventually prints an answer. The README states the problem plainly: "you see the final result, not the journey." When a run produces the wrong patch or burns ten minutes on a redundant file read, the transcript in your terminal is a flat list of lines with no structure. Agent Flow reconstructs that structure as an interactive node graph, where each tool call, branch and return flow is a node you can click.

The author built it while working on CraftMyGame, a game creation platform driven by AI agents, and released it publicly. The target user is someone already running Claude Code or Codex CLI sessions and wanting to inspect them. That is a narrower audience than "anyone using AI." If you use a chat interface, or an agent framework that is not Claude Code or Codex, the auto-discovery paths do not apply to you.

Four stated goals frame the feature set: understanding how an agent breaks down a problem, debugging tool call chains, spotting where time goes, and building intuition for prompt writing. The first three are diagnostic. The fourth is a learning use, and it is the weakest of the claims because the README offers no study or measurement behind it.

## How the event pipeline works: hooks, rollout tailing and SSE

There are two ingestion paths, one per runtime, and they are mechanically different.

For Claude Code, Agent Flow installs Claude Code hooks. The README describes this as a "lightweight HTTP hook server" that "receives events directly from Claude Code for zero-latency streaming." The setup script `scripts/setup.js`, invoked as `pnpm run setup`, registers those hooks. In the VS Code extension the same configuration happens automatically the first time you open the panel.

For Codex, there is no hook mechanism. Agent Flow tails Codex's own rollout files at `~/.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 "authoritative token counts from Codex's own event stream." That word, authoritative, is doing real work: the counts come from Codex rather than being estimated by Agent Flow.

On the delivery side, `pnpm run dev` starts the Next.js dev server plus an event relay that forwards events to the browser over SSE. The relay can also be run alone with `pnpm run dev:relay`. The web package and the extension package are separate workspace packages under `app/`, `extension/` and `web/`, coordinated by `pnpm-workspace.yaml`.

A third path exists for offline work: point `agentVisualizer.eventLogPath` at any `.jsonl` file and Agent Flow tails it. That is the only way to look at a session you did not capture live.

## Installing Agent Flow and watching your first session

The fastest route needs no VS Code. The README gives this as the quick start:

```bash
npx agent-flow-app
```

This starts the visualizer in your browser. The default server port is 3001, and `--port <number>`, `--no-open` and `--verbose` are the documented options. Start a Claude Code session in another terminal and events should stream in. Note that the published npx binary is the one build that ships telemetry enabled by default; `pnpm run dev` and the VS Code extension emit nothing.

To build from source instead:

```bash
git clone https://github.com/patoles/agent-flow.git
cd agent-flow
pnpm i
pnpm run setup
pnpm run dev
```

`pnpm run setup` configures the Claude Code hooks once. `pnpm run dev` starts the relay on port 3001 and the web app, which you open at http://localhost:3000. Requirements are Node.js 20+ and pnpm; the VS Code extension needs an IDE at version 1.85 or later.

If you want only one runtime, restrict it. In the extension this is a setting:

```json
{
  "agentVisualizer.runtime": "claude"
}
```

For the standalone app, set `AGENT_FLOW_RUNTIME` to `claude` or `codex`. The default is `auto`, which watches both concurrently and tags sessions by runtime. The README claims the unused runtime is "a harmless no-op," which is consistent with how the discovery paths are described, though it is the kind of statement only a run in your own environment can confirm.

To replay a saved log rather than watch live, set `agentVisualizer.eventLogPath` to a `.jsonl` file and Agent Flow tails it.

## Where Agent Flow stops being the right tool

The visualization only exists for runtimes it can discover. Claude Code sessions come from `~/.claude/projects/`; Codex sessions come from `~/.codex/sessions/`. If your agent runs inside a different harness, or if your Claude Code installation writes its session data somewhere the extension does not look, nothing appears. There is no generic adapter documented, only the JSONL path, which requires you to produce the file yourself in a compatible shape.

Live streaming depends on hooks being installed and the relay being reachable. The README documents a manual reconfiguration command, Agent Flow: Configure Claude Code Hooks, which implies hooks can drift or be overwritten. A hook that stops firing produces a panel that looks idle, not an error, and the README does not document what that failure looks like or how to detect it.

Telemetry is opt-out and on by default in the published npx binary. The README says only aggregate events are sent, but the privacy section is truncated in the repository listing, so the full event list is not something this article can state. If that matters to your organization, read the full section in the repository before running the npx command, and prefer the extension or `pnpm run dev`, which the README says emit nothing.

Finally, this is a viewer, not a controller. Nothing in the README suggests you can pause an agent, edit a prompt mid-run, or rerun a branch from the graph. If your problem is intervening in a run, Agent Flow is the wrong layer.

## Agent Flow compared with reading raw JSONL logs

The obvious alternative is not another product. It is `tail -f` on the same files Agent Flow reads, plus `jq` for filtering. That approach has real advantages: no Node.js 20+ requirement, no pnpm workspace, no relay process, no telemetry question, and it works over SSH on a machine where you would never install an IDE.

The difference is representation. A JSONL event stream is chronological and flat. Agent Flow renders it as a graph where branching and return flows have spatial position, and it adds panels the raw file does not have: a timeline, a file attention heatmap, and a message transcript. For a session with one subagent and a dozen tool calls, `jq` is faster to reach for. For a session where three subagents interleave file edits and you need to see which one touched what, the graph is the point.

There is a middle path in the product itself. `agentVisualizer.eventLogPath` lets you keep your existing log capture and only borrow the rendering, which is the configuration worth trying first if you are unsure whether the visualization earns its setup cost.

## Maintenance, upgrades and licence

The repository is not archived. The last push was on 2026-07-11, roughly two months before this article, so the project is current rather than dormant. The release history shows a burst of activity in July 2026: v0.9.0 added model support and Codex discovery fixes, and v0.9.1, published the same day, fixed Windows Claude Code session discovery. v0.8.0, from April 2026, introduced Codex runtime support at all.

That pattern matters for upgrade planning. Windows-specific discovery bugs were still being fixed at v0.9.1, so if you are on Windows, pin to that release or later rather than an earlier one. The version number is still 0.x, which in practice means settings keys and the `agentVisualizer.*` namespace can change without a major-version bump.

Upgrade cost is mostly one-time setup, not ongoing. `pnpm run setup` writes Claude Code hook configuration, and the extension reconfigures hooks on first open. A version that changes the hook payload shape would require re-running setup; the README does not document a rollback path for hook configuration, so keep a note of what Claude Code's settings looked like before you ran it.

The project is Apache-2.0. There is also a TRADEMARK.md at the repository root, which is a common pattern for projects that permit broad code reuse while reserving the name. Apache-2.0 includes an explicit patent grant and requires attribution and notice retention. None of this is legal advice; if you are redistributing a modified build, read LICENSE and TRADEMARK.md together.

## Conclusion

Adopt Agent Flow if you are debugging multi-step Claude Code or Codex runs and need to see tool call order, branching and token counts rather than just the final message. Skip it if your agent work is single-turn, if you cannot run Node.js 20+ or pnpm, or if you object to the opt-out telemetry in the published npx binary. Before relying on it, verify that your Claude Code hooks are registered by running Agent Flow: Configure Claude Code Hooks from the Command Palette, and confirm the runtime setting matches the agent you actually use.

## FAQ

### What is Agent Flow?

It is a real-time visualizer for Claude Code and Codex agent orchestration, distributed as a VS Code extension and as a standalone web app. It renders agent execution as an interactive node graph with tool calls, branching and return flows.

### How do I install Agent Flow?

The README's quick start is `npx agent-flow-app`, which runs the visualizer in your browser on port 3001 by default. You can also install the VS Code extension, or clone the repository and run `pnpm i`, `pnpm run setup` and `pnpm run dev`.

### Does Agent Flow work with Codex as well as Claude Code?

Yes. It auto-detects sessions from both runtimes concurrently and shows them side by side, tagged by runtime. Codex support reads `~/.codex/sessions/**/rollout-*.jsonl` and respects the `CODEX_HOME` environment variable.

### Can I restrict Agent Flow to only one runtime?

Yes. In the VS Code extension set `agentVisualizer.runtime` to `claude` or `codex`; for `pnpm run dev` and `npx agent-flow-app`, set the `AGENT_FLOW_RUNTIME` environment variable. The default is `auto`, which watches both.

### What does Agent Flow need to run?

Node.js 20 or later and pnpm, plus the Claude Code CLI. The VS Code extension requires a VS Code-compatible IDE at version 1.85 or later.

## Sources

- [License: Apache-2.0](https://github.com/patoles/agent-flow/blob/main/LICENSE)
- [patoles/agent-flow on GitHub](https://github.com/patoles/agent-flow)
- [Project website](https://marketplace.visualstudio.com/items?itemName=simon-p.agent-flow)
- [README](https://github.com/patoles/agent-flow/blob/main/README.md)
- [Releases](https://github.com/patoles/agent-flow/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/patoles-agent-flow