D3 Agent Coordination Graph

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