Agent Flow：把 Claude Code 与 Codex 的执行过程画成节点图
Real-time visualization of Claude Code agent orchestration — see your agents think, branch, and coordinate as they work.
秒懂
- 它是什么？
- Agent Flow 是 Simon Patole 为调试自家 AI agent 产品而做的可视化工具，通过 Claude Code 的 HTTP hook 和 Codex 的 rollout 文件把 agent 的工具调用、分支与返回流程实时渲染成可交互的节点图。它解决的是可观测性问题，不是能力问题。
- 适合谁用？
- 如果你在本地跑 Claude Code 或 Codex，并且经常需要回答“刚才那一步为什么调了这个工具”这类问题，Agent Flow 值得装一次，先用 pnpm run dev:demo 看它把数据结构成什么样，再决定是否让它接管你的 Claude Code hooks。如果你只是想让 agent 跑完拿到结果，或者你的执行环境不允许本地进程写 ~/.claude 配置、也不允许向外部端点发送匿名事件，那它带来的收益不足以抵消这些代价。
- 能商用吗？
- 可以。Apache-2.0 是宽松许可证：你可以使用、修改并销售基于它的软件，只需保留版权和许可证声明。
- 还在维护吗？
- 在维护。仓库最近一次提交在 66 天前。
- 用什么语言写的？
- 主要是 TypeScript（依据 GitHub 的语言统计）。
以上回答依据项目的 GitHub 数据（最近同步于 2026年9月15日）和我们的分析，不构成法律意见。
开源项目深度解析
它要解决的其实是一个调试视角问题
Claude Code 的执行对外是个黑盒。你看到的是它最后改了哪些文件、跑了哪些命令，看不到中间为什么这么选。README 里作者说得很直白：他在开发 CraftMyGame 这个由 AI agent 驱动的游戏创作平台时，调试 agent 行为很痛苦，于是把它做成了可视化的，再对外开源。这个出身决定了 Agent Flow 的定位不是提升 agent 能力，而是把已有的执行轨迹摊开给人看。
目标用户是那些把 Claude Code 或 Codex 当成日常开发工具、并且已经开始写 subagent 或多步工具链的人。README 列了四个使用场景：理解 agent 怎么拆解问题、追查工具调用链、定位耗时点、通过观察来学习怎么写更好的 prompt。前三个是排障，第四个是学习。如果你的 agent 调用只有一两步，节点图不会比终端输出多告诉你什么。
两条采集路径决定了它能看见什么
Agent Flow 支持 Claude Code 和 Codex 两个 runtime，但两者的数据来源完全不同，这一点 README 写得很清楚，也决定了可视化粒度的差异。
Claude Code 走的是 hooks。项目自带一个轻量 HTTP hook server，Claude Code 在事件发生时直接把事件推给它，README 用 zero-latency streaming 描述这条链路。VS Code 扩展首次打开面板时会自动配置这些 hooks，也可以从命令面板手动跑 Agent Flow: Configure Claude Code Hooks。需要注意的是，这意味着 Agent Flow 会改写你的 Claude Code 配置。
Codex 走的是文件 tail。它读取 ~/.codex/sessions/**/rollout-*.jsonl，并遵循 CODEX_HOME 环境变量。README 特别提到这里能拿到 tool calls、reasoning，以及来自 Codex 自身事件流的 authoritative token counts。文件 tail 和 HTTP 推送的差别在于延迟和完整性：前者依赖 Codex 把事件落盘，后者是事件驱动的。
第三条路径是通用的 JSONL 回放：把 agentVisualizer.eventLogPath 指向任意 .jsonl 文件，Agent Flow 会 tail 它并可视化到达的事件。这条路径让工具不绑定在特定 runtime 上，也让事后复盘成为可能。
数据到界面这一段，README 在开发章节里给了机制：pnpm run dev 同时启动 Next.js dev server 和一个 event relay，relay 接收 Claude Code 事件并通过 SSE 推给浏览器。也就是说前端不是轮询，是服务端推送。
三种启动方式，代价各不相同
最轻的入口不需要 VS Code，也不需要克隆仓库：
npx agent-flow-app
它会在浏览器里启动可视化界面，默认端口 3001，可用 --port 改；--no-open 阻止自动开浏览器；--verbose 打印详细事件日志。README 的用法是：另开一个终端启动 Claude Code 会话，事件会实时流入。
第二条路是从源码跑：
pnpm i pnpm run setup pnpm run dev
pnpm run setup 是一次性的，用来配置 Claude Code hooks。之后打开 http://localhost:3000。这条路适合要改代码或看 demo 数据的人，pnpm run dev:demo 会带 mock 数据启动，pnpm run dev:relay 可以只跑 relay 服务。
第三条是 VS Code 扩展，装上之后从命令面板运行 Agent Flow: Open Agent Flow，快捷键是 Mac 上的 Cmd+Alt+A 或 Windows/Linux 上的 Ctrl+Alt+A。扩展同样会自动配置 hooks。
配置面很小，只有四个键：agentVisualizer.runtime 默认 auto 表示同时看两个 runtime，可改成 claude 或 codex；agentVisualizer.devServerPort 默认 0 表示生产模式；agentVisualizer.eventLogPath 默认空；agentVisualizer.autoOpen 默认 false。非 VS Code 的两个入口改用 AGENT_FLOW_RUNTIME 环境变量，取值同样是 claude 或 codex。环境要求是 Node.js 20 以上、pnpm，以及 Claude Code CLI 本身。
同时监听两个 runtime 是个刻意的默认值
agentVisualizer.runtime 默认是 auto，也就是三个入口都同时监听 ~/.claude/projects/ 和 ~/.codex/sessions/，会话并排显示并按 runtime 打标签。README 对这个默认值的解释是：如果你只用其中一个，另一个是无害的 no-op，没有可见影响，也不需要用户做任何操作。
这个设计选择值得单独说。并排显示两个 runtime 的会话，只有在同时使用 Claude Code 和 Codex 时才有价值，而这类用户可能并不多。代价是默认路径下工具会去访问两个目录。作者显然权衡过，认为多扫一个不存在的目录比让用户先做一次配置决策更划算。
如果你只用其中一个，把它显式设成 claude 或 codex 更干净，也能避免把另一个 runtime 的目录纳入监控范围。这不是性能问题，是边界问题。
遥测默认开启，而且只在一条路径上
README 的隐私章节写明：Agent Flow 附带 opt-out 的匿名使用遥测，且只在已发布的 npx agent-flow-app 二进制里默认开启。pnpm run dev 和 VS Code 扩展不发送任何内容。发送的只有聚合事件。
这个划分是有意的，也基本合理：npx 路径是最低门槛的试用方式，作者需要知道有多少人在用；源码路径和扩展路径的用户已经做了更多投入，不必再采集。但对使用者来说，结论很直接：如果你对出网流量敏感，用 pnpm run dev 或装扩展，不要用 npx agent-flow-app，或者在接受默认值之前先确认 opt-out 的具体开关在哪。README 在这一段是被截断的，opt-out 的具体做法无法从现有材料确认。
许可方面，项目采用 Apache-2.0。这个许可包含专利授权条款，对商业使用相对友好，但具体到你的组织是否合规，需要你自己判断，这里不构成法律意见。
它不适合什么场景
最明显的一条：Agent Flow 是本地可观测性工具，不是远程或生产环境的监控方案。它的两条主要采集路径都依赖本机文件系统（~/.claude/projects/、~/.codex/sessions/）或本机 Claude Code 的 hook 配置。如果你的 agent 跑在容器、CI 或远端机器上，这套机制不会自动延伸过去。
第二条：它只覆盖 Claude Code 和 Codex。README 里没有任何关于其他 agent 框架的说明。虽然 agentVisualizer.eventLogPath 提供了通用 JSONL 入口，但前提是你的 runtime 能产出符合预期的 JSONL 事件流，这一点 README 没有给出格式规范，需要自己试。
第三条：hooks 会改动你的 Claude Code 配置。对于在共享开发机或受限环境里工作的人，这是个实际障碍，不是偏好问题。
第四条：可视化本身有认知成本。当一次会话产生几百个工具调用时，节点图会不会比文本日志更难读，从现有材料无法判断，README 也没有讨论大规模会话下的表现。
替代方案与真正的差异
最直接的替代不是另一个可视化工具，而是回到 Claude Code 自身的输出：终端里的工具调用记录加上会话日志文件。这条路零配置、零依赖、不改你的 hooks，缺点是它是线性的文本流，分支和返回关系要靠自己脑补。Agent Flow 相对它的增量就是把线性流变成有拓扑结构的图，并且把时间线和 transcript 放在同一界面里。
另一类替代是通用的 agent 追踪方案，比如把事件发到 OpenTelemetry 之类的后端再做可视化。差异在部署形态：那类方案要求你先把事件导出到外部 collector，适合已经在做统一可观测性建设的团队；Agent Flow 是本地优先，事件不出机器（npx 路径的遥测除外），代价是只能在装了它的那台开发机上用。
所以选型问题可以简化成一句：你是想让单人在本地快速看懂一次会话，还是想把 agent 行为纳入团队级的追踪体系。前者是 Agent Flow 的场景，后者不是。
维护成本与版本节奏
从发布记录看，项目在 2026 年 4 月到 7 月之间发了三个版本：v0.8.0 加入 Codex runtime 支持，v0.9.0 是新模型支持加 Codex 发现修复，v0.9.1 修 Windows 上的 Claude Code 会话发现。版本号还停在 0.9.x，说明接口和配置键仍可能变动。
这个节奏透露两件事。一是项目在跟着上游 runtime 走：Codex 的 rollout 文件格式、Claude Code 的 hooks 行为一旦变化，Agent Flow 就得跟着修，v0.9.0 和 v0.9.1 连着两天发版就是这种耦合的表现。二是跨平台细节仍在补，Windows 的会话发现是最近才修的。
对你的实际影响是：把 Agent Flow 当作跟随上游的辅助工具，而不是稳定的基础设施。升级前值得看一眼 release notes，因为 hooks 配置和 rollout 解析这两块是最容易随上游漂移的部分。
编辑结论
如果你在本地跑 Claude Code 或 Codex，并且经常需要回答“刚才那一步为什么调了这个工具”这类问题，Agent Flow 值得装一次，先用 pnpm run dev:demo 看它把数据结构成什么样，再决定是否让它接管你的 Claude Code hooks。如果你只是想让 agent 跑完拿到结果，或者你的执行环境不允许本地进程写 ~/.claude 配置、也不允许向外部端点发送匿名事件，那它带来的收益不足以抵消这些代价。上手前先确认三件事：Node.js 是否 20 以上；agentVisualizer.runtime 该设成 auto 还是单一 runtime；以及你能否接受 npx agent-flow-app 这条路径默认开启的匿名遥测，因为 pnpm run dev 和 VS Code 扩展都不发任何事件。
社区笔记