Open-source 3D visualization for Claude Code agents - monitor multiple sessions with a hexagonal grid interface.
- 3D Hexagonal Grid - Beautiful Three.js visualization inspired by RTS games
- Real-time Monitoring - Watch tool calls, file operations, and commands as they happen
- Multi-Session Support - Track multiple Claude Code instances simultaneously
- Session Analytics - Tool usage counts, activity timelines, and status tracking
- Cross-Platform - Works on Windows, macOS, and Linux
- Open Source - Fully auditable, no telemetry, your code stays local
macOS/Linux:
curl -fsSL https://raw.githubusercontent.com/sudoBrandino/claude-hive/main/install.sh | bashWindows (PowerShell):
irm https://raw.githubusercontent.com/sudoBrandino/claude-hive/main/install.ps1 | iexThis downloads the Docker image, starts the container, and installs the hooks automatically.
If you prefer to set things up manually:
# Create a docker-compose.yml anywhere
cat > docker-compose.yml << 'EOF'
services:
hive:
image: ghcr.io/sudoBrandino/claude-hive:latest
container_name: claude-hive
ports:
- "4520:4520"
restart: unless-stopped
EOF
# Start
docker compose up -d
# Open dashboard
open http://localhost:4520Then install hooks manually (see Platform Support).
# Clone the repository
git clone https://github.com/sudoBrandino/claude-hive
cd claude-hive
# Install hooks
node cli/index.js setup --docker
# Build and start
docker compose up -d --build
# Open dashboard
open http://localhost:4520The Docker setup separates concerns:
| Component | Location | Description |
|---|---|---|
| Server | Container | WebSocket + Express server on port 4520 |
| Dashboard | Container | Pre-built React + Three.js UI |
| Hooks | Host | Lightweight bash script (curl + jq) |
┌─────────────────────────────────────────────────────────────────┐
│ HOST MACHINE │
│ ┌──────────────┐ ┌─────────────────┐ │
│ │ Claude Code │────▶│ send-event.sh │──┐ │
│ │ │ │ (bash + curl) │ │ │
│ └──────────────┘ └─────────────────┘ │ │
├────────────────────────────────────────────┼────────────────────┤
│ DOCKER CONTAINER │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ Claude Hive Server (port 4520) │ │
│ │ ├── /events (POST) ← receives hook events │ │
│ │ ├── WebSocket ← streams to dashboard │ │
│ │ └── Static files ← serves React UI │ │
│ └──────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
# Build and start
docker compose up -d
# View logs
docker compose logs -f
# Stop
docker compose down
# Rebuild after changes
docker compose up -d --buildThe setup auto-detects your OS and uses the appropriate hook script:
| Platform | Hook Script | Dependencies |
|---|---|---|
| Windows | send-event.ps1 (PowerShell) |
None - uses built-in cmdlets |
| macOS | send-event.sh (bash) |
curl, jq |
| Linux | send-event.sh (bash) |
curl, jq |
# macOS
brew install jq
# Ubuntu/Debian
sudo apt install jq curl
# Verify
curl --version && jq --versionNo additional tools needed - PowerShell is built-in. Just make sure Docker Desktop is installed.
┌─────────────────────────────────────────────────────────────────┐
│ Claude Hive Architecture │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌─────────────────┐ ┌─────────────┐ │
│ │ Claude Code │────▶│ Hive Hooks │────▶│ Hive Server │ │
│ │ Instances │ │ (PostToolUse, │ │ (localhost: │ │
│ │ │ │ Stop, etc.) │ │ 4520) │ │
│ └──────────────┘ └─────────────────┘ └──────┬──────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ WebSocket Stream │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ React + Three.js Dashboard │ │
│ │ │ │
│ │ ┌─────────────────────┐ ┌────────────────────────────┐ │ │
│ │ │ 3D Hex Grid │ │ Sidebar │ │ │
│ │ │ ┌───┐ ┌───┐ │ │ - Session list │ │ │
│ │ │ ┌───┐ ┌───┐ ┌───┐ │ │ - Event stream │ │ │
│ │ │ └───┘ └───┘ │ │ - Analytics │ │ │
│ │ └─────────────────────┘ └────────────────────────────┘ │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
| Command | Description |
|---|---|
npm start |
Start the Hive server |
npm run setup |
Install hooks into Claude Code |
npm run dev |
Start server + client in dev mode |
npm run build |
Build production client |
# Using npx (after publishing)
npx claude-hive # Start server
npx claude-hive setup # Install hooks (Node.js mode)
npx claude-hive setup -d # Install hooks (Docker mode - bash/curl)
npx claude-hive doctor # Diagnose issues
npx claude-hive uninstall # Remove hooksClaude Hive uses Claude Code's native hooks system to capture events:
{
"hooks": {
"PostToolUse": [{
"matcher": ".*",
"hooks": [{
"type": "command",
"command": "node /path/to/send-event.js"
}]
}]
}
}Each Claude Code hook triggers a small script that forwards the event:
// Hook receives JSON from stdin
{
"session_id": "abc123",
"hook_event_name": "PostToolUse",
"tool_name": "Write",
"tool_input": { "file_path": "/src/app.ts" }
}
// Script POSTs to Hive server
POST http://localhost:4520/eventsThe server broadcasts events to all connected clients via WebSocket:
// Client connects
const ws = new WebSocket('ws://localhost:4520');
// Receives events in real-time
ws.onmessage = (event) => {
const { type, event, session } = JSON.parse(event.data);
// Update visualization
};claude-hive/
├── server/
│ └── index.js # WebSocket + Express server
├── client/
│ ├── src/
│ │ ├── App.jsx # Main React app
│ │ └── components/
│ │ ├── HexGrid.jsx # Three.js hex visualization
│ │ └── Sidebar.jsx # Session list & events
│ └── package.json
├── hooks/
│ ├── send-event.js # Hook script (Node.js mode)
│ ├── send-event.sh # Hook script (Docker mode - macOS/Linux)
│ └── send-event.ps1 # Hook script (Docker mode - Windows)
├── cli/
│ ├── index.js # CLI entry point
│ ├── setup.js # Hook installation
│ └── doctor.js # Diagnostics
├── Dockerfile # Multi-stage build
├── docker-compose.yml # Container orchestration
└── package.json
| Endpoint | Method | Description |
|---|---|---|
/events |
POST | Receive hook events |
/api/sessions |
GET | List all sessions |
/api/events |
GET | Get event history |
/api/stats |
GET | Aggregated statistics |
/health |
GET | Health check |
ws:// |
WebSocket | Real-time event stream |
PORT=8080 npm startEdit hooks/send-event.js to add custom processing:
// Add custom metadata
event.custom_field = 'value';
// Filter events
if (event.tool_name === 'Read') return; // Skip read events| Feature | Claude Hive | VibeCraft |
|---|---|---|
| Source | Open | Closed |
| License | MIT | Proprietary |
| 3D Visualization | Yes (hex grid) | Yes (hex grid) |
| Docker Support | Yes | No |
| Voice Input | No | Yes (Deepgram) |
| Analytics | Basic | Unknown |
| Telemetry | None | Amplitude |
Contributions welcome! Please read the contributing guidelines first.
# Development setup
git clone https://github.com/your-username/claude-hive
cd claude-hive
npm install
cd client && npm install && cd ..
npm run devMIT License - see LICENSE for details.
Inspired by VibeCraft and the Claude Code monitoring ecosystem.
Built with:
- React - UI framework
- Three.js - 3D visualization
- @react-three/fiber - React renderer for Three.js
- Express - Web server
- ws - WebSocket library