Agent Flow: Real-Time AI Agent Orchestration Visualizer
See your Claude Code and Codex agents think, branch, and coordinate in real-time.
- Source repo
- patoles/agent-flow
- Stars
- ★ 1.7k
- Last updated
- 9d ago
- License
- Apache-2.0
- Primary language
- TypeScript
- FA score
- 45/100 · Major gaps
At a glance
- How it runs
- Works with
- Platform-specificCodex · Claude Code
- Cost
- Free software; you pay for model usage
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- Debugging complex Claude Code agent workflows where you need to trace the exact sequence of tool calls and decisions that led to an error.
- Not a fit if
- Teams using agent frameworks other than Claude Code or Codex
- Users unwilling to install Node.js 20+ and pnpm
- Source review
- 45/100 · Major gaps 2 safety controls not found
What does this agent do, and when should you use it?
Agent Flow is a developer tool that provides real-time visualization of Claude Code and Codex agent execution via an interactive node graph. It captures events through Claude Code's HTTP hook server and Codex's rollout logs, displaying tool calls, branching, and return flows live. The tool offers multiple entry points: a quick-start browser app (npx agent-flow-app), a standalone web app run via pnpm run dev, and a VS Code extension. Key features include multi-session tab support, interactive canvas with pan/zoom, timeline and transcript panels, a file-attention heatmap, and JSONL log file replay. Built by the creator of CraftMyGame, Agent Flow is open-sourced under Apache 2.0 and includes opt-out telemetry for the npm binary.
Agent Flow captures agent events through three mechanisms: an HTTP hook server that receives events directly from Claude Code; tailing Codex session files at ~/.codex/sessions/**/rollout-*.jsonl (respecting CODEX_HOME); and watching arbitrary JSONL event log files. It then assembles these into a real-time interactive node graph that shows agent thinking, tool calls, and subagent coordination. Users can pan, zoom, and click nodes to inspect details, review the full timeline and message transcript, and see a file-attention heatmap. The tool supports multiple concurrent sessions, displayed as tabs, and can restrict monitoring to one runtime via settings or environment variables. It also supports replaying events from JSONL files for offline analysis.
- Debugging complex Claude Code agent workflows where you need to trace the exact sequence of tool calls and decisions that led to an error.
- Monitoring multiple concurrent AI agent sessions in real time during a large refactoring or feature development.
- Learning how Claude interprets and executes prompts by watching its real-time reasoning and tool selection.
- Analyzing historical agent sessions by pointing the visualizer at a JSONL event log file for post-mortem review.
- Optimizing prompt design for Claude Code by observing branch points and unnecessary tool calls in the visualization.
- Using Codex with its accurate token counts and reasoning output to understand resource usage and logic.
How do you install or deploy this agent?
Agent Flow offers three installation paths:
- Quick Start (no VS Code): Run
npx agent-flow-app(requires Node.js 20+). - Standalone Web App: Clone the repo, run
pnpm i, thenpnpm run setup(one-time hooks configuration), and finallypnpm run devto start the app. - VS Code Extension: Install the extension, then run 'Agent Flow: Open Agent Flow' from the Command Palette. It will auto-configure Claude Code hooks on first open. Requirements include Node.js 20+, pnpm, and the Claude Code CLI.
How do you use this agent?
Start Agent Flow using one of the installations. Then, in a separate terminal, start a Claude Code or Codex session; events will stream to the visualizer in real-time. Use --port to change the server port, --no-open to prevent auto-opening the browser, and --verbose for detailed logs. For the VS Code extension, use the Command Palette commands or keyboard shortcut Cmd+Alt+A / Ctrl+Alt+A. Configure runtime via agentVisualizer.runtime setting or AGENT_FLOW_RUNTIME environment variable. To watch a JSONL log, set agentVisualizer.eventLogPath.
What are this agent's strengths and limitations?
- Real-time interactive visualization makes agent execution transparent and debuggable.
- Supports both Claude Code and Codex simultaneously with multi-session tabs.
- Offers JSONL log file replay for offline analysis and debugging.
- Multiple deployment options: CLI, standalone web app, and VS Code extension, catering to different workflows.
- Opt-out telemetry, with local data inspection and identity reset capability.
- Tied to Claude Code and Codex runtimes; no support for other agent frameworks or LLM providers.
- Requires Node.js 20+ and pnpm, adding environment setup overhead.
- Telemetry is enabled by default in the npx binary, though opt-out is available.
- Dependence on Claude Code hooks and Codex log formats may break if those tools change.
- No documented integration with CI/CD pipelines or other automation tools.
How does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Agent Flow: Real-Time AI Agent Orchestration Visualizer This agent | 45 · Major gaps | CLIFree + model costs | ★ 1.7k | 9d ago | TypeScript | Codex · Claude Code |
| Ordewell | 67 · Some gaps | CLIFree + model costs | ★ 202 | today | TypeScript | Codex · Claude Code · OpenAI API · Claude API |
| Plannotator | 78 · Good | CLIFreemium | ★ 9.5k | today | TypeScript | Codex · Claude Code |
| OpenChamber | 42 · Major gaps | Desktop appFree + model costs | ★ 12k | today | TypeScript | — |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows: README clearly states telemetry is opt-out and only aggregate events are sent, not prompts, file paths, etc.; but no user confirmation mechanism (e.g., prompt at install) is provided, and least-privilege principle is not discussed. Data flow transparency is good with telemetry schema and serialize() function. Sensitive data handling is described but implementation not verified. Dependency security only shows version ranges in package.json, no lockfile or audit evidence. External effects include auto-configuring Claude Code hooks, but consent is not mentioned. Rollback mechanism not mentioned. Source attribution has author info, but publisher unverified.
Evidence shows: Tests cover key parsers and file reading logic, self-consistency is good. Dependency availability only shows version ranges in package.json, no lockfile or CI cache evidence. Failure messages not explicitly documented, but tests may imply.
Evidence shows: README clearly identifies target users (Claude Code/Codex users) and use cases (debugging, learning). Capability boundaries are clear with multiple entry points and runtime selection. Trigger precision via settings and env vars. Environment fit requires Node 20+, pnpm, Claude Code CLI, but no version requirement for Codex.
Evidence shows: Information architecture is clear with directory and command tables. Install notes are detailed including quick start and from source. Naming stability not explicitly stated, but version numbers exist. Examples and FAQ have demo video and screenshots, but no FAQ. Known limitations not explicitly listed. License is Apache-2.0 with LICENSE file. Version changelog mentioned in extension/CHANGELOG.md but content not provided. Maintenance responsibility has author info but no maintenance policy.
Evidence shows: Output usability is high with real-time visualization, timeline, transcript. Marginal value is clear, solving black-box problem. Cost-benefit not quantified, but as open-source tool, cost is low.
Evidence shows: README feature claims have test support (e.g., Codex parser tests), but no independent verification. Cross-source corroboration limited, only single repo. Fact-inference separation unclear, e.g., telemetry claims not verified.
- Not found in source: confirmation before actingTurn on (or add) a confirmation step before it acts, and try it in a sandbox or test environment before real data.
- Not found in source: rollback or recovery pathBack up first, or work on a git branch or snapshot, so its changes can be undone.
- Telemetry is opt-out and enabled by default, users must actively disable, potential privacy concern.
- Auto-configuring Claude Code hooks may modify user config without explicit consent.
- Publisher unverified, source credibility unknown.
- Dependency version ranges are broad, no lockfile, supply chain risk not fully mitigated.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
v0.9.2 v0.9.2: Hook setup safety and background subagent fixes
Release notes excerpt
- Fix: hook setup no longer removes other tools' hooks from ~/.claude/settings.json (#73) - Setup (npx agent-flow-app, pnpm run setup, and the VS Code extension) treated any hook URL starting with http://127.0.0.1: as its own, so loopback HTTP hooks registered by other tools were deleted on install. On every activation, the VS Code extension also rewrote them into Agent Flow command hooks …View on GitHub ↗ -
v0.9.1 v0.9.1 — Windows Claude Code session discovery fix
Release notes excerpt
- Fix: Claude Code session discovery on Windows — workspace-to-project-dir matching is now case-insensitive on win32 (#57, part of #4) - VS Code reports drive letters lowercase (c:\...) while Claude Code encodes them uppercase (C--...), so the encoded-directory lookup, the subfolder-session prefix check, and the cwd containment check could all silently miss — no sessions appeared at all - The workspace project dir is now resolved to its actual on-disk casing at startup, and all path comparisons are case-folded on Windows (matching the Codex-side fix from 0.9.0)View on GitHub ↗ -
v0.9.0 v0.9.0 — New model support + Codex discovery fixes
Release notes excerpt
- New model support — Claude Fable 5 / Mythos 5, Sonnet 5, Opus 4.8, GPT-5.x Codex (#57) - Context window sizing: fable/mythos family recognized as 1M context (previously fell back to 200k, showing the gauge 5× overfull); gpt-* family recognized as 400k as the fallback when Codex doesn't report its own authoritative window. Sonnet 5 / Opus 4.8 already matched the existing family patterns …View on GitHub ↗
FAQ
Does Agent Flow support monitoring both Claude Code and Codex at the same time?
agentVisualizer.runtime setting or the AGENT_FLOW_RUNTIME environment variable.Can Agent Flow be used without a live agent session?
agentVisualizer.eventLogPath to the path of a .jsonl file and it will tail and visualize the events.What data is sent in the telemetry?
export AGENT_FLOW_TELEMETRY=false or export DO_NOT_TRACK=1.