Node Repulsion
-150
Link Distance
80
Link Strength
0.5
Data Source
Graph Actions
WebSocket Connection
Disconnected
0
Total Nodes
0
Agents
0
Tools
0
Subagents
0
Connections
0
Events

### Timeline Replay

Event 0 / 0
Speed
500ms

### Legend

#### Node Types

Agent Session
Tool
Subagent
User Prompt

#### Link Types

Uses Tool
Spawns Subagent
Temporal Sequence
Error Propagation

#### Node Size

Node size represents activity level (event count). Larger nodes indicate more events/interactions.

#### Interactions

• Drag nodes to reposition
• Scroll to zoom in/out
• Hover for details
• Click to focus

## About This Tool

### Purpose

The D3 Agent Coordination Graph visualizes the complex relationships between Claude Code agents, tools, and subagents in multi-agent systems. It uses D3's force-directed graph layout to reveal coordination patterns, tool usage frequencies, and agent spawning hierarchies through an interactive network visualization.

### Features

- Force-Directed Layout - Automatic physics-based node positioning with configurable forces
- Interactive Node Dragging - Manually reposition nodes to explore relationships
- Zoom & Pan - Navigate large coordination graphs with smooth zoom and pan
- Real-time Updates - Optional WebSocket connection for live event streaming
- Timeline Replay - Step through events to see graph evolution over time
- Multi-Source Data - Import from files or connect to live observability server
- Activity-Based Sizing - Node size reflects event count and usage frequency
- Color-Coded Entities - Visual distinction between agents, tools, and subagents
- Rich Tooltips - Detailed information on hover with event counts and metadata
- Configurable Physics - Adjust repulsion, link distance, and connection strength

### Web Research Integration

Source: D3 Force-Directed Graph - Observable

Techniques Applied:

- Force Simulation Setup - Implemented `d3.forceSimulation()` with `forceLink()` for connection strength, `forceManyBody()` for node repulsion, and `forceCenter()` for centering. Each force is independently configurable via UI controls.
- Node Drag Behavior - Applied `d3.drag()` with three event handlers: `dragstarted` fixes node position and restarts simulation alpha, `dragged` updates coordinates in real-time, and `dragended` releases constraints while allowing simulation to settle.
- Tick-Based Animation - Utilized simulation's `tick` event to continuously update SVG element positions (links via `x1, y1, x2, y2` attributes and nodes via transform translation), creating smooth physics-based animation.

### Graph Data Structure

The visualization processes Claude Code hook events into a graph structure:

- Nodes - Represent entities: Agent sessions (source_app + session_id), Tools (from PreToolUse/PostToolUse), Subagents (from SubagentStop), User prompts (from UserPromptSubmit)
- Links - Represent relationships: Agent→Tool (usage), Agent→Subagent (spawning), Event→Event (temporal sequence), Agent→Error (error propagation)
- Node Properties - id (unique identifier), type (agent/tool/subagent/user), label (display name), eventCount (activity level), metadata (additional context)
- Link Properties - source (from node), target (to node), type (relationship kind), strength (connection weight), events (supporting events)

### Usage

1. Load Data - Click "Sample Data" to load example multi-agent scenario, or use "Import Events" to load .json/.jsonl hook event files
2. Adjust Physics - Tune node repulsion, link distance, and link strength sliders to optimize layout for your data size
3. Explore Graph - Drag nodes to reposition, scroll to zoom, hover for tooltips showing event counts and details
4. Timeline Replay - Use timeline slider to step through events chronologically, or click Play to auto-replay graph evolution
5. Connect Live - Click "Connect" under WebSocket to stream real-time events from observability server (requires server at localhost:4000)
6. Analyze Patterns - Identify heavily-used tools (large purple nodes), agent hierarchies (green subagent connections), and coordination bottlenecks

### Hook Event Mapping

The tool processes these Claude Code hook events:

- PreToolUse - Creates Agent→Tool link, increases tool activity count
- PostToolUse - Updates link with success/error status, adds error propagation links on failure
- SubagentStop - Creates Subagent node and Agent→Subagent spawn link
- UserPromptSubmit - Creates User node and Agent→User interaction link
- Notification - Creates coordination checkpoint markers in timeline

### Sample Data Scenario

The included sample data demonstrates a realistic multi-agent workflow:

- Main agent (infinite-agents session) orchestrates the workflow
- Uses Read, Write, Bash, and Grep tools extensively
- Spawns 3 parallel subagents for concurrent code generation tasks
- Each subagent uses different tool combinations (Read+Write, Grep+Edit, Bash+Write)
- User provides 2 prompts that trigger agent coordination
- One subagent encounters an error, creating error propagation path

### WebSocket Integration

Connect to the Claude Code hooks observability server for real-time updates:

1. Start the observability server: `./scripts/start-system.sh`
2. Click "Connect" in the WebSocket Connection section
3. Graph will update automatically as new events arrive
4. New nodes animate in with transitions, links strengthen with repeated usage
5. Compatible with the multi-agent observability system architecture