agent-flow-visualization

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Agent Flow

Skill by ara.so — Daily 2026 Skills collection.

Agent Flow is a VS Code extension that provides real-time visualization of Claude Code agent orchestration. It renders agent execution as an interactive node graph, showing tool calls, branching, subagent coordination, and timing — turning Claude Code's black-box execution into a transparent, debuggable flow.

由ara.so开发的Skill — 属于Daily 2026 Skills合集。

Agent Flow是一款VS Code扩展，可提供Claude Code Agent编排的实时可视化功能。它将Agent的执行过程渲染为交互式节点图，展示工具调用、分支流程、子Agent协作以及时间线——把Claude Code的黑盒执行过程转化为透明、可调试的流程。

Installation

安装

Via VS Code Marketplace

通过VS Code应用市场

Open VS Code Extensions (
```
Cmd+Shift+X
```
)
Search for Agent Flow by simon-p
Click Install

Or install directly: marketplace.visualstudio.com/items?itemName=simon-p.agent-flow

打开VS Code扩展面板（
```
Cmd+Shift+X
```
）
搜索simon-p开发的Agent Flow
点击安装

或直接通过链接安装：marketplace.visualstudio.com/items?itemName=simon-p.agent-flow

Requirements

系统要求

VS Code 1.85 or later
Claude Code CLI installed and accessible
Node.js (for Claude Code)

VS Code 1.85或更高版本
已安装并可访问Claude Code CLI
Node.js（用于Claude Code）

Quick Start

快速开始

undefined

undefined

1. Open Command Palette

1. 打开命令面板

Cmd+Shift+P (Mac) / Ctrl+Shift+P (Win/Linux)

2. Run the command

2. 运行命令

Agent Flow: Open Agent Flow

3. Start a Claude Code session in your workspace

3. 在工作区启动Claude Code会话

Agent Flow auto-detects it and begins streaming

Agent Flow会自动检测并开始流式传输数据


Or use the keyboard shortcut:
- **Mac**: `Cmd+Alt+A`
- **Win/Linux**: `Ctrl+Alt+A`


或使用快捷键：
- **Mac**: `Cmd+Alt+A`
- **Win/Linux**: `Ctrl+Alt+A`

Commands

命令列表

Command	Description
`Agent Flow: Open Agent Flow`	Open visualizer in current editor column
`Agent Flow: Open Agent Flow to Side`	Open in a side editor column
`Agent Flow: Connect to Running Agent`	Manually connect to a specific agent session
`Agent Flow: Configure Claude Code Hooks`	Set up Claude Code hooks for live event streaming

命令	描述
`Agent Flow: Open Agent Flow`	在当前编辑器列中打开可视化工具
`Agent Flow: Open Agent Flow to Side`	在侧边编辑器列中打开
`Agent Flow: Connect to Running Agent`	手动连接到指定的Agent会话
`Agent Flow: Configure Claude Code Hooks`	设置Claude Code钩子以实现实时事件流式传输

Configuration

配置

Settings available in VS Code settings (

settings.json

jsonc

{
  // Path to a JSONL event log file to watch/replay
  "agentVisualizer.eventLogPath": "/path/to/agent-events.jsonl",

  // Auto-open the visualizer when an agent session starts
  "agentVisualizer.autoOpen": true,

  // Development server port (0 = production mode, use built assets)
  "agentVisualizer.devServerPort": 0
}

可在VS Code设置（

settings.json

）中进行以下配置：

jsonc

{
  // 要监控/回放的JSONL事件日志文件路径
  "agentVisualizer.eventLogPath": "/path/to/agent-events.jsonl",

  // 当Agent会话启动时自动打开可视化工具
  "agentVisualizer.autoOpen": true,

  // 开发服务器端口（0 = 生产模式，使用构建后的资源）
  "agentVisualizer.devServerPort": 0
}

Auto-Open on Agent Start

会话启动时自动打开

jsonc

// settings.json
{
  "agentVisualizer.autoOpen": true
}

jsonc

// settings.json
{
  "agentVisualizer.autoOpen": true
}

Claude Code Hooks Setup

Claude Code钩子设置

Agent Flow uses Claude Code's hook system for zero-latency event streaming. Hooks are configured automatically on first open, but you can reconfigure manually.

Agent Flow使用Claude Code的钩子系统实现零延迟事件流式传输。首次打开时会自动配置钩子，也可手动重新配置。

Automatic Configuration

自动配置

Run from Command Palette:

> Agent Flow: Configure Claude Code Hooks

从命令面板运行：

> Agent Flow: Configure Claude Code Hooks

Manual Hook Configuration

手动钩子配置

If you need to configure hooks manually, Agent Flow starts a local HTTP server that receives events. The hooks forward Claude Code lifecycle events (tool calls, responses, session start/end) to the extension.

Claude Code hooks are configured in

~/.claude/settings.json

or project-level

.claude/settings.json

jsonc

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": ".*",
        "hooks": [
          {
            "type": "command",
            "command": "curl -s -X POST http://localhost:PORT/hook -H 'Content-Type: application/json' -d @-"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": ".*",
        "hooks": [
          {
            "type": "command",
            "command": "curl -s -X POST http://localhost:PORT/hook -H 'Content-Type: application/json' -d @-"
          }
        ]
      }
    ]
  }
}

Agent Flow manages this configuration automatically — prefer using the command palette command.

如果需要手动配置钩子，Agent Flow会启动一个本地HTTP服务器来接收事件。钩子会将Claude Code的生命周期事件（工具调用、响应、会话开始/结束）转发到扩展。

Claude Code钩子配置在

~/.claude/settings.json

或项目级别的

.claude/settings.json

中：

jsonc

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": ".*",
        "hooks": [
          {
            "type": "command",
            "command": "curl -s -X POST http://localhost:PORT/hook -H 'Content-Type: application/json' -d @-"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": ".*",
        "hooks": [
          {
            "type": "command",
            "command": "curl -s -X POST http://localhost:PORT/hook -H 'Content-Type: application/json' -d @-"
          }
        ]
      }
    ]
  }
}

建议使用命令面板中的命令，Agent Flow会自动管理此配置。

JSONL Event Log Mode

JSONL事件日志模式

For replaying past sessions or watching log files generated outside VS Code:

jsonc

// settings.json
{
  "agentVisualizer.eventLogPath": "${workspaceFolder}/logs/agent-session.jsonl"
}

Agent Flow tails the file and visualizes events as they arrive. Use this for:

Post-hoc debugging of agent runs
Sharing agent execution recordings with teammates
CI/CD pipeline agent monitoring

用于回放过往会话或监控VS Code外部生成的日志文件：

jsonc

// settings.json
{
  "agentVisualizer.eventLogPath": "${workspaceFolder}/logs/agent-session.jsonl"
}

Agent Flow会跟踪该文件，并在有新事件到达时进行可视化。可用于：

Agent运行后的调试
与团队成员共享Agent执行记录
CI/CD流水线中的Agent监控

JSONL Event Format

JSONL事件格式

Each line in the log file is a JSON event object:

jsonl

{"type":"session_start","sessionId":"abc123","timestamp":"2026-03-21T10:00:00Z","model":"claude-opus-4-5"}
{"type":"tool_use","sessionId":"abc123","toolName":"bash","input":{"command":"ls -la"},"timestamp":"2026-03-21T10:00:01Z"}
{"type":"tool_result","sessionId":"abc123","toolName":"bash","output":"total 48\n...","timestamp":"2026-03-21T10:00:02Z"}
{"type":"message","sessionId":"abc123","role":"assistant","content":"I can see the files...","timestamp":"2026-03-21T10:00:03Z"}

日志文件中的每一行都是一个JSON事件对象：

jsonl

{"type":"session_start","sessionId":"abc123","timestamp":"2026-03-21T10:00:00Z","model":"claude-opus-4-5"}
{"type":"tool_use","sessionId":"abc123","toolName":"bash","input":{"command":"ls -la"},"timestamp":"2026-03-21T10:00:01Z"}
{"type":"tool_result","sessionId":"abc123","toolName":"bash","output":"total 48\n...","timestamp":"2026-03-21T10:00:02Z"}
{"type":"message","sessionId":"abc123","role":"assistant","content":"I can see the files...","timestamp":"2026-03-21T10:00:03Z"}

Multi-Session Support

多会话支持

Agent Flow tracks multiple concurrent Claude Code sessions with tabs. Each session gets its own visualization canvas.

undefined

Agent Flow通过标签页跟踪多个并发的Claude Code会话，每个会话都有自己的可视化画布。

undefined

Start multiple Claude Code sessions in different terminals

在不同终端中启动多个Claude Code会话

Each appears as a separate tab in Agent Flow

每个会话会在Agent Flow中显示为单独的标签页

Click tabs to switch between session graphs

点击标签页可在会话图之间切换

undefined

undefined

Interactive Canvas Features

交互式画布功能

Navigation

Node Types in the Graph

图中的节点类型

Node Type	Visual	Description
Agent/Subagent	Circle	Claude instance making decisions
Tool Call	Rectangle	Individual tool invocation (bash, read_file, etc.)
Tool Result	Rectangle (dashed)	Output returned from tool
Branch	Diamond	Decision point spawning subagents
Return	Arrow	Subagent returning result to parent

节点类型	视觉样式	描述
Agent/子Agent	圆形	做出决策的Claude实例
工具调用	矩形	单个工具调用（bash、read_file等）
工具结果	虚线矩形	工具返回的输出
分支	菱形	生成子Agent的决策点
返回	箭头	子Agent向父Agent返回结果

Panels

面板

Timeline: Chronological view of all events with durations
Transcript: Full message history between agent and tools
File Heatmap: Which files received the most attention

时间线：按时间顺序排列的所有事件视图，包含持续时间
对话记录：Agent与工具之间的完整消息历史
文件热度图：哪些文件受到最多关注

Contributing / Development Setup

贡献 / 开发设置

bash

git clone https://github.com/patoles/agent-flow
cd agent-flow
npm install

bash

git clone https://github.com/patoles/agent-flow
cd agent-flow
npm install

Build the extension

构建扩展

npm run build

Watch mode for development

开发监听模式

npm run watch

Run with dev server (hot reload)

使用开发服务器运行（热重载）

Set in settings: "agentVisualizer.devServerPort": 3000

在设置中配置: "agentVisualizer.devServerPort": 3000

npm run dev

undefined

npm run dev

undefined

Extension Structure

扩展结构

agent-flow/
├── src/
│   ├── extension.ts          # VS Code extension entry point
│   ├── hookServer.ts         # HTTP server receiving Claude Code hook events
│   ├── sessionManager.ts     # Manages multiple agent sessions
│   ├── webviewProvider.ts    # Webview panel management
│   └── logWatcher.ts         # JSONL file tail watcher
├── webview/
│   ├── src/
│   │   ├── App.tsx           # Main React app
│   │   ├── Graph.tsx         # Node graph canvas (likely D3 or React Flow)
│   │   ├── Timeline.tsx      # Timeline panel
│   │   └── Transcript.tsx    # Message transcript panel
│   └── package.json
└── package.json              # Extension manifest

agent-flow/
├── src/
│   ├── extension.ts          # VS Code扩展入口文件
│   ├── hookServer.ts         # 接收Claude Code钩子事件的HTTP服务器
│   ├── sessionManager.ts     # 管理多个Agent会话
│   ├── webviewProvider.ts    # Webview面板管理
│   └── logWatcher.ts         # JSONL文件跟踪器
├── webview/
│   ├── src/
│   │   ├── App.tsx           # 主React应用
│   │   ├── Graph.tsx         # 节点图画布（可能基于D3或React Flow）
│   │   ├── Timeline.tsx      # 时间线面板
│   │   └── Transcript.tsx    # 对话记录面板
│   └── package.json
└── package.json              # 扩展清单

Common Patterns

常见使用模式

Pattern: Debug a Failing Agent Run

模式：调试失败的Agent运行

Open Agent Flow (
```
Cmd+Alt+A
```
)
Run your Claude Code command that's failing
Watch the graph — look for:
- Red/error nodes indicating failed tool calls
- Unexpected branching
- Loops (agent retrying the same tool)
Click the failed tool node to inspect input/output
Check the Timeline panel for which tool call took unexpectedly long

打开Agent Flow（
```
Cmd+Alt+A
```
）
运行失败的Claude Code命令
查看图——注意：
- 红色/错误节点表示工具调用失败
- 意外的分支流程
- 循环（Agent重复调用同一工具）
点击失败的工具节点查看输入/输出
查看时间线面板，找出耗时过长的工具调用

Pattern: Replay a Saved Session

模式：回放已保存的会话

bash

undefined

bash

undefined

Save Claude Code output to JSONL during a run

在运行时将Claude Code输出保存为JSONL格式

(depends on your Claude Code version/config)

—

claude --output-format jsonl > session-$(date +%s).jsonl

#（取决于你的Claude Code版本/配置） claude --output-format jsonl > session-$(date +%s).jsonl

Point Agent Flow at it

将Agent Flow指向该文件


```jsonc
// .vscode/settings.json (project-level)
{
  "agentVisualizer.eventLogPath": "./logs/session-1234567890.jsonl"
}


```jsonc
// .vscode/settings.json（项目级别）
{
  "agentVisualizer.eventLogPath": "./logs/session-1234567890.jsonl"
}

Pattern: Auto-Visualize All Agent Sessions

模式：自动可视化所有Agent会话

jsonc

// settings.json
{
  "agentVisualizer.autoOpen": true
}

Now every time a Claude Code session starts in your workspace, Agent Flow opens automatically.

jsonc

// settings.json
{
  "agentVisualizer.autoOpen": true
}

现在，每当工作区中启动Claude Code会话时，Agent Flow都会自动打开。

Pattern: Side-by-Side Coding and Visualization

模式：边编码边可视化

undefined

undefined

Open Agent Flow to side so you can code and watch simultaneously

打开Agent Flow到侧边，以便同时编码和监控

Cmd+Shift+P > Agent Flow: Open Agent Flow to Side


This opens the visualizer in a split editor, keeping your code files accessible in the main editor group.

Cmd+Shift+P > Agent Flow: Open Agent Flow to Side


这会在拆分编辑器中打开可视化工具，主编辑器组仍可访问代码文件。

Troubleshooting

故障排除

Agent Flow doesn't detect my Claude Code session

Agent Flow无法检测到我的Claude Code会话

Verify Claude Code is running in the same workspace folder
Check that hooks are configured: run
```
Agent Flow: Configure Claude Code Hooks
```
Verify the hook server is running — look for "Agent Flow hook server listening" in the Output panel (
```
View > Output > Agent Flow
```
)
Try
```
Agent Flow: Connect to Running Agent
```
to manually specify the session

验证Claude Code是否在同一工作区文件夹中运行
检查钩子是否已配置：运行
```
Agent Flow: Configure Claude Code Hooks
```
验证钩子服务器是否在运行——在输出面板中查看“Agent Flow hook server listening”（
```
视图 > 输出 > Agent Flow
```
）
尝试使用
```
Agent Flow: Connect to Running Agent
```
手动指定会话

Hooks aren't forwarding events

钩子未转发事件

bash

undefined

bash

undefined

Test the hook server manually

手动测试钩子服务器

curl -X POST http://localhost:PORT/hook
-H 'Content-Type: application/json'
-d '{"type":"test","sessionId":"test123"}'


Check VS Code Output panel for the correct PORT value.

curl -X POST http://localhost:PORT/hook
-H 'Content-Type: application/json'
-d '{"type":"test","sessionId":"test123"}'


在VS Code输出面板中查看正确的PORT值。

Graph is empty / not updating

图为空 / 不更新

Check
```
agentVisualizer.eventLogPath
```
— if set, Agent Flow reads from file instead of hooks
Clear the setting if you want live hook-based streaming:
jsonc
```
{ "agentVisualizer.eventLogPath": "" }
```
Reload VS Code window (
```
Cmd+Shift+P > Developer: Reload Window
```
)

检查
```
agentVisualizer.eventLogPath
```
——如果已设置，Agent Flow会从文件读取而非钩子
如果需要基于钩子的实时流式传输，请清除该设置：
jsonc
```
{ "agentVisualizer.eventLogPath": "" }
```

重新加载VS Code窗口（

Cmd+Shift+P > 开发者：重新加载窗口

）

Extension not loading

扩展无法加载

bash

undefined

bash

undefined

Check VS Code version meets requirement

检查VS Code版本是否符合要求

code --version

Must be 1.85 or later

必须为1.85或更高版本

Check extension is enabled

检查扩展是否已启用

Extensions panel > search "Agent Flow" > verify enabled

扩展面板 > 搜索"Agent Flow" > 验证是否已启用

undefined

undefined

Multiple sessions showing in wrong tabs

多个会话显示在错误的标签页中

Each session is identified by a unique session ID from Claude Code. If sessions are merging incorrectly, check that each

claude

process is started fresh (not reusing an existing session ID).

每个会话由Claude Code提供的唯一会话ID标识。如果会话合并错误，请确保每个

claude

进程都是全新启动的（不重用现有会话ID）。

Resources

资源

VS Code Marketplace
Demo Video
GitHub Repository
CraftMyGame — the project that inspired Agent Flow
License: Apache 2.0

agent-flow-visualization

Original

Translation

Agent Flow

Agent Flow

Installation

安装

Via VS Code Marketplace

通过VS Code应用市场

Requirements

系统要求

Quick Start

快速开始

1. Open Command Palette

1. 打开命令面板

2. Run the command

2. 运行命令

3. Start a Claude Code session in your workspace

3. 在工作区启动Claude Code会话

Agent Flow auto-detects it and begins streaming

Agent Flow会自动检测并开始流式传输数据

Commands

命令列表

Configuration

配置

Auto-Open on Agent Start

会话启动时自动打开

Claude Code Hooks Setup

Claude Code钩子设置

Automatic Configuration

自动配置

Manual Hook Configuration

手动钩子配置

JSONL Event Log Mode

JSONL事件日志模式

JSONL Event Format

JSONL事件格式

Multi-Session Support

多会话支持

Start multiple Claude Code sessions in different terminals

在不同终端中启动多个Claude Code会话

Each appears as a separate tab in Agent Flow

每个会话会在Agent Flow中显示为单独的标签页

Click tabs to switch between session graphs

点击标签页可在会话图之间切换

Interactive Canvas Features

交互式画布功能

Navigation

导航

Node Types in the Graph

图中的节点类型

Panels

面板

Contributing / Development Setup

贡献 / 开发设置

Build the extension

构建扩展

Watch mode for development

开发监听模式

Run with dev server (hot reload)

使用开发服务器运行（热重载）

Set in settings: "agentVisualizer.devServerPort": 3000

在设置中配置: "agentVisualizer.devServerPort": 3000

Extension Structure

扩展结构

Common Patterns

常见使用模式

Pattern: Debug a Failing Agent Run

模式：调试失败的Agent运行

Pattern: Replay a Saved Session

模式：回放已保存的会话

Save Claude Code output to JSONL during a run

在运行时将Claude Code输出保存为JSONL格式

(depends on your Claude Code version/config)

Point Agent Flow at it

将Agent Flow指向该文件

Pattern: Auto-Visualize All Agent Sessions

模式：自动可视化所有Agent会话

Pattern: Side-by-Side Coding and Visualization

模式：边编码边可视化