agent-flow
by patoles
Real-time visualization of Claude Code agent orchestration — see your agents think, branch, and coordinate as they work.
992stars
111forks
TypeScript
Added 3/25/2026
Installation
# Add to your Claude Code skills
git clone https://github.com/patoles/agent-flowGetting Started
Guides for using ai agents skills like agent-flow.
- Caveman: Cut Claude Token Use by 65%How agent-side prompt compression works, when to use it, and when not to.
- What is an AI Skills Marketplace?Definitions, how marketplaces work, and how to choose between them in 2026.
- Getting Started with AI SkillsFirst-time install walkthrough for Claude Code, Codex CLI, and ChatGPT.
Security ReportVerified
Last scanned: 5/4/2026
{
"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
}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.runtimesetting - Claude Code hooks: Lightweight HTTP hook server receives events directly from Claude Code for zero-latency streaming
- Codex rollout tailing: Reads
~/.codex/sessions/**/rollout-*.jsonl(respectsCODEX_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.runtimeto"auto"/"claude"/"codex"in your settings pnpm run devandnpx agent-flow-app: set theAGENT_FLOW_RUNTIMEenvironment variable toclaudeorcodex(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.eventLogPathin your VS Code settings to the path of a.jsonlfile - 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 |
Keyboard Shortcut
| Shortcut | Action |
|---|---|
Cmd+Alt+A (Mac) / Ctrl+Alt+A (Win/Linux) |
Open Agent Flow |
Settings
| Setting | Default | Description |
|---|---|---|
agentVisualizer.runtime |
"auto" |
Which agent runtime(s) to watch: "auto" (both), "claude", or "codex" |
agentVisualizer.devServerPort |
0 |
Development server port (0 = production mode) |
agentVisualizer.eventLogPath |
"" |
Path to a JSONL event log file to watch |
agentVisualizer.autoOpen |
false |
Auto-open when an agent session starts |
Requirements
- Node.js 20+ (LTS recommended)
- pnpm
- Claude Code CLI
- 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 |
Star History
Author
Created by Simon Patole, for CraftMyGame.
Privacy & Telemetry
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=falseorexport DO_NOT_TRACK=1(disabled installs write zero state to disk — no~/.agent-flow/directory) - Inspect the payload:
cat ~/.agent-flow/telemetry/events.jsonl - Full schema + exact fields: see the v0.8.1 entry in
extension/CHANGELOG.md or the
serialize()function in scripts/telemetry.ts - Reset your anonymous identity: delete
~/.agent-flow/installation-id— a fresh random UUIDv4 will be generated on next run
License
Apache 2.0 — see LICENSE for details.
The name "Agent Flow" and associated logos are trademarks of Simon Patole. See TRADEMARK.md for usage guidelines.
Frequently Asked Questions
What is agent-flow?
agent-flow is an open-source ai agents skill for AI coding assistants such as Claude Code, Codex CLI, and ChatGPT, built by patoles. Real-time visualization of Claude Code agent orchestration — see your agents think, branch, and coordinate as they work. It has 992 GitHub stars.
Is agent-flow safe to use?
Yes. agent-flow passed SkillsLLM's automated security scan — a dependency vulnerability audit plus prompt-injection heuristics — with no high-severity issues. You can read the full report in the Security Report section on this page.
How do I install agent-flow?
Clone the repository with "git clone https://github.com/patoles/agent-flow" and add it to your Claude Code skills directory (see the Installation section above).
What programming language is agent-flow written in?
agent-flow is primarily written in TypeScript. It is open-source under patoles on GitHub, so you can review or fork the full source.
Are there alternatives to agent-flow?
Yes. SkillsLLM lists many other AI Agents skills you can browse and compare side by side. Open the AI Agents category from the badge at the top of this page, or use the Related Skills and comparison links further down to weigh agent-flow against similar tools.
Comments (0)
to leave a comment.
No comments yet. Be the first to share your thoughts!
Related Skills
An agentic skills framework & software development methodology that works.
234,966
20,863
Shell
AI Agentsaibrainstorming
The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
220,060
33,721
JavaScript
AI Agentsai-agentsanthropic
The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
185,940
28,768
JavaScript
AI Agentsai-agentsanthropic
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.
120,031
19,897
Shell
AI Agents
Use Garry Tan's exact Claude Code setup: 23 opinionated tools that serve as CEO, Designer, Eng Manager, Release Manager, Doc Engineer, and QA
112,329
16,695
TypeScript
AI AgentsSKILL.md