{
"issues": [
{
"type": "npm-audit",
"message": "esbuild: esbuild enables any website to send any requests to the development server and read the response",
"severity": "medium"
}
],
"status": "PASSED",
"scannedAt": "2026-05-04T06:42:09.327Z",
"semgrepRan": false,
"npmAuditRan": true,
"pipAuditRan": true
}
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.
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
The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
First-time install walkthrough for Claude Code, Codex CLI, and ChatGPT.
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 codex (defaults to watching both)
For non-default Codex installs, set the CODEX_HOME environment variable.
JSONL Event Log
You can also point Agent Flow at a JSONL event log file:
Set agentVisualizer.eventLogPath in your VS Code settings to the path of a .jsonl file
Agent Flow will tail the file and visualize events as they arrive
Commands
| Command | Description |
|---------|-------------|
| Agent Flow: Open Agent Flow | Open the visualizer panel |
| Agent Flow: Open Agent Flow to Side | Open in a side editor column |
| Agent Flow: Connect to Running Agent | Manually connect to an agent session |
| Agent Flow: Configure Claude Code Hooks | Set up Claude Code hooks for live streaming |
For the VS Code extension: a VSCode-compatible IDE 1.85+ (e.g. VS Code, Cursor, Windsurf)
Development
pnpm i # install dependencies for all packages
pnpm run setup # configure Claude Code hooks (one-time)
pnpm run dev # start dev server + event relay
pnpm run dev starts both the Next.js dev server and an event relay that receives Claude Code events and streams them to the browser via SSE.
Other scripts:
| Script | Description |
|--------|-------------|
| pnpm run dev:demo | Start with demo/mock data |
| pnpm run dev:relay | Run the event relay server standalone |
| pnpm run dev:extension | Watch-build the extension |
| pnpm run build:all | Production build (webview + extension) |
| pnpm run build:web | Build the Next.js web app |
| pnpm run build:extension | Build the extension |
| pnpm run build:webview | Build the webview assets |
Agent Flow ships opt-out anonymous usage telemetry, enabled by default only
in the published npx agent-flow-app binary. pnpm run dev and the VS Code
extension emit nothing. Only aggregate events are sent — session count,
duration, event count, OS/arch, Agent Flow version, distinct model IDs
observed, which runtimes were watched, and error class names. Prompts, file
paths, tool calls, user info, and environment variables are never sent.
Turn off:export AGENT_FLOW_TELEMETRY=false or export DO_NOT_TRACK=1
(disabled installs write zero state to disk — no ~/.agent-flow/ directory)
Inspect the payload:cat ~/.agent-flow/telemetry/events.jsonl
Claude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows - all through natural language commands.
