Agent Flow Visualization

# Agent Flow

> Skill by [ara.so](https://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.

## Installation

### Via VS Code Marketplace

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

Or install directly: [marketplace.visualstudio.com/items?itemName=simon-p.agent-flow](https://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)

## Quick Start

```
# 1. Open Command Palette
Cmd+Shift+P (Mac) / Ctrl+Shift+P (Win/Linux)

# 2. Run the command
> Agent Flow: Open Agent Flow

# 3. Start a Claude Code session in your workspace
# Agent Flow auto-detects it and begins streaming
```

Or use the keyboard shortcut:
- **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 |

## 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
}
```

### Auto-Open on Agent Start

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

## Claude Code Hooks Setup

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.

### Automatic Configuration

Run from Command Palette:
```
> 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.

## JSONL Event Log Mode

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

```jsonc
// settings.json
{
  "agentVisualizer.eventLogPath": "${workspaceFolder}/logs/