agent-flow

实时可视化 Claude Code 代理思考与协作，调试更直观。

agent-flow 是一个用于实时可视化 Claude Code 代理编排的开源工具。它解决了开发者在运行 Claude Code 时难以直观理解代理内部思考、分支和协作过程的问题。通过提供实时可视化界面，开发者可以清晰地看到代理在执行任务时的思维路径、分支决策以及多个代理之间的协调配合。其核心能力包括捕获代理运行时的详细事件流，并以图形化方式展示代理的思考过程、工具调用和状态转换，从而帮助开发者调试、优化和理解复杂的代理工作流。该项目基于 TypeScript 构建，易于集成到现有的 Claude Code 使用流程中。

开源 free 开源模型

访问官网 ↗ GitHub ↗ 文档 ↗

GitHub 星标 ★ 1654

维护状态维护中

是否开源是

定价模式 free

项目数据

分类开源模型

开发团队patoles

所属国家

官网地址https://marketplace.visualstudio.com/items?itemName=simon-p.agent-flow

GitHubhttps://github.com/patoles/agent-flow

定价模式free

价格说明开源项目，Apache-2.0 许可证，可免费使用和部署。

访问状态

是否开源是

开源协议Apache-2.0

主要语言TypeScript

技术栈/模型agent-visualization,ai-agents,claude-code,developer-tools,llm,vscode-extension

GitHub 星标★ 1654

30天Star增速

HF 下载量

上线时间2026-03-21 00:00:00

最近更新2026-09-23 00:00:00

维护状态维护中

中文支持

访问方式

移动端支持

综合评分

收录时间2026-08-09

浏览次数5

使用教程

难度：入门约 5 分钟部署方式：命令行工具 8 步

环境要求

本机具备 Node.js / npx 环境（命令通过 npx 运行）
一个正在运行的 Claude Code 或 Codex 会话，用于产生可视化事件
可选：VS Code，用于以扩展方式使用
默认会同时监听 ~/.claude/projects/ 与 ~/.codex/sessions/ 两个目录

安装与启动步骤

1确认 Node 环境

agent-flow 通过 npx 启动，先确认本机已装好 Node.js 与 npx，能联网拉取包。
```
node -v && npx -v
```
2启动可视化界面

无需 VS Code，该命令会在浏览器中启动可视化界面，并开始监听代理事件。
```
npx agent-flow-app
```
3另开终端跑代理

在另一个终端启动 Claude Code 会话，其运行事件会实时流入界面并绘制成节点图。
4指定端口启动

服务默认端口为 3001，若被占用可用 --port 换成其他端口。
```
npx agent-flow-app --port 3002
```
5控制打开与日志

--no-open 不自动打开浏览器；--verbose 打印更详细的事件日志，便于排查问题。
```
npx agent-flow-app --no-open --verbose
```
6只监听单一运行时

默认同时监听 Claude Code 与 Codex，用环境变量可只保留其中一个。
```
AGENT_FLOW_RUNTIME=claude npx agent-flow-app
```
7指定 Codex 路径

Codex 安装位置非默认时，设置 CODEX_HOME 指向实际的 Codex 主目录。
```
CODEX_HOME=/your/codex/home npx agent-flow-app
```
8VS Code 扩展方式

也可从 VS Code 市场安装 agent-flow 扩展，再用设置项控制运行时来源。

关键配置

配置项	必填	说明	示例
`agentVisualizer.runtime`	否	VS Code 扩展设置项，限定监听 auto/claude/codex	`auto`
`AGENT_FLOW_RUNTIME`	否	命令行启动时限定运行时为 claude 或 codex	`claude`
`CODEX_HOME`	否	Codex 非默认安装时，指向其主目录	`/your/codex/home`
`--port`	否	可视化服务端口，默认 3001	`3001`

如何确认成功

浏览器自动打开可视化页面（默认端口 3001），在另一终端运行 Claude Code 后能看到节点图与工具调用实时更新。

常见问题

Q：没有 VS Code 可以用吗？

A：可以。直接运行 npx agent-flow-app 即可在浏览器中使用可视化界面，无需安装 VS Code。

Q：3001 端口被占用怎么办？

A：启动时加 --port 参数指定其他端口，例如 npx agent-flow-app --port 3002。

Q：我只用 Claude Code，不想看到 Codex 会话？

A：命令行设 AGENT_FLOW_RUNTIME=claude；VS Code 扩展把 agentVisualizer.runtime 设为 "claude"。

Q：Codex 装在非默认目录识别不到？

A：设置 CODEX_HOME 环境变量指向实际的 Codex 主目录即可。

Q：启动后没有自动弹出浏览器？

A：浏览器可能未自动打开，可手动访问本地服务地址；或本就不想自动打开时加 --no-open。

注意事项

必须另开一个终端运行 Claude Code / Codex 会话，事件才会流入可视化界面。
默认同时监听 ~/.claude/projects/ 与 ~/.codex/sessions/；只用其中一种时另一种为空操作，无副作用。
README 仅给出 npx 快速启动方式，源码方式的 pnpm run dev 未提供安装步骤，需自行参考仓库说明。

核心亮点

实时展示代理思考、分支和协作过程，极大提升调试效率
基于 TypeScript，类型安全，易于扩展和维护
界面直观，降低理解复杂代理工作流的门槛

不足之处

目前仅支持 Claude Code，对其他代理框架兼容性未知
文档/社区待观察

适用场景

调试复杂的 Claude Code 代理任务，定位逻辑错误
教学或演示，直观展示代理的决策过程
优化多代理协作流程，观察协调瓶颈

替代项目

LangSmith、AgentOps、Langfuse

项目介绍

agent-flow 是智能体领域的开源项目，由 patoles 开发，是 2026 年新上线的项目。

在全站 13,014 个收录项目中，它的 GitHub 星标数（1,654）位列前 30%，在智能体分类中处于中上游。

近 42 天，它的 GitHub 星标从 1,517 增加到 1,654，净增 137。

项目仍在小幅维护中，最近一次代码更新于 2026-09-23。Apache-2.0 许可证，可免费使用和部署。

它主要面向的使用场景是：调试复杂的ClaudeCode代理任务，定位逻辑错误。同类可对比的替代方案包括 LangSmith、AgentOps、Langfuse。

上一篇：mcp-server-qdrant

下一篇：dust