Vibecraft: Visualizing AI Agents in 3D Space When Terminal Logs Aren't Enough

Hook

When you're running three Claude Code instances simultaneously—one refactoring authentication, another writing tests, a third debugging deployment scripts—your terminal becomes an unreadable wall of interleaved output. What if you could literally see which AI agent is doing what?

Context

Claude Code and similar AI coding assistants operate through tool calls: reading files, executing bash commands, writing code. For a single session, following along in your terminal works fine. But the moment you scale to multiple parallel instances—say, coordinating a backend refactor while another agent handles frontend updates—you lose spatial awareness. Which Claude just modified that config file? Which one is stuck waiting on a long-running build? Traditional terminal multiplexers like tmux help, but you're still context-switching between text panes, grep'ing through logs, and mentally tracking state.

Vibecraft emerged from this orchestration problem. Instead of parsing terminal output, it intercepts Claude Code's internal tool hooks (the bash scripts that execute when Claude reads a file or runs a command) and broadcasts those events over WebSockets to a browser-based 3D environment. Each Claude instance gets an avatar that physically moves between themed "stations"—a Bookshelf for file reads, a Desk for writes, a Terminal for bash commands. The spatial metaphor transforms abstract API calls into scannable visual information. You can glance at the scene and immediately understand: "Ah, Claude-1 is reading documentation while Claude-2 is executing tests." It's not just eye candy; it's information architecture for multi-agent workflows.

Technical Insight

Vibecraft's architecture hinges on a modified hook system. Claude Code supports custom bash scripts that intercept tool usage—when Claude wants to read a file, it actually calls a bash script that you can replace. Vibecraft provides drop-in replacement hooks that preserve Claude's functionality while adding WebSocket event emission. Here's the simplified flow for a file read operation:

#!/bin/bash
# read_file.sh - Modified Claude Code hook

FILE_PATH="$1"
SESSION_ID="$TMUX_PANE"  # Unique identifier from tmux

# Execute the actual file read
CONTENT=$(cat "$FILE_PATH")

# Emit event to Vibecraft WebSocket server
curl -X POST http://localhost:3000/event \
  -H "Content-Type: application/json" \
  -d '{
    "session": "'"$SESSION_ID"'",
    "tool": "read_file",
    "target": "'"$FILE_PATH"'",
    "timestamp": '$(date +%s)'
  }' &  # Background the curl to avoid blocking Claude

# Return content to Claude
echo "$CONTENT"

This pattern repeats for write_file, bash, search, and other tools. The hooks are non-blocking (note the backgrounded curl), so Claude's performance remains unchanged. The WebSocket server, written in TypeScript with Node.js, maintains an in-memory registry of active sessions and broadcasts events to connected browser clients.

On the frontend, Three.js renders a persistent 3D scene. When an event arrives, the corresponding avatar tweens to the appropriate station using GSML (GreenSock Animation Platform). The station selection logic maps tool types to spatial locations:

function getStationForTool(tool: ToolType): Station {
  const stationMap: Record<ToolType, Station> = {
    read_file: 'bookshelf',
    write_file: 'desk',
    bash: 'terminal',
    search: 'archive',
    edit: 'workbench'
  };
  return stationMap[tool] || 'center';
}

function handleToolEvent(event: ToolEvent) {
  const avatar = getAvatar(event.session);
  const targetStation = getStationForTool(event.tool);
  const position = STATION_POSITIONS[targetStation];
  
  // Animate avatar movement
  gsap.to(avatar.position, {
    x: position.x,
    y: position.y,
    z: position.z,
    duration: 0.8,
    ease: 'power2.inOut'
  });
  
  // Trigger spatial audio at destination
  playStationSound(targetStation, position);
}

The spatial audio is particularly clever. Each station has an associated sound (paper rustling for Bookshelf, keyboard clicks for Desk, command bleeps for Terminal) that plays with 3D positioning based on the camera's location. When orchestrating multiple sessions, you can literally hear which stations are active without looking at the screen.

The tmux integration enables bidirectional control. Vibecraft doesn't just visualize—it can send prompts back to specific Claude sessions. When you click an avatar and type a message in the browser, Vibecraft uses tmux send-keys to inject that text into the corresponding terminal pane:

function sendPromptToSession(sessionId: string, prompt: string) {
  const tmuxCommand = `tmux send-keys -t ${sessionId} "${prompt}" Enter`;
  exec(tmuxCommand, (error) => {
    if (error) {
      console.error(`Failed to send prompt: ${error}`);
    }
  });
}

This transforms Vibecraft from a passive monitor into an active orchestration layer. You can visually see which Claude is idle, click it, and immediately assign new work—all without leaving the 3D interface.

The hex tile "draw mode" adds another dimension. Users can place hexagonal tiles in 3D space and annotate them with labels. This creates a spatial project map: "This region is the authentication system" with tiles labeled as components. When Claude agents work on files in those areas, you see activity clustered spatially, giving you architectural awareness. It's a rudimentary form of codebase cartography, mapping abstract file hierarchies to manipulable 3D space.

Gotcha

The platform dependency is brutal: macOS and Linux only, no Windows support. This stems from the bash hook requirement—Vibecraft's entire event pipeline depends on Unix shell scripts intercepting Claude's tool calls. Windows users are completely locked out unless they're running WSL2, and even then, tmux integration gets flaky with terminal emulation quirks.

More fundamentally, you're modifying Claude Code's internals. The hooks you install replace Claude's default tool execution scripts, which means every time Anthropic updates Claude Code, there's risk of breakage. If Claude changes its hook interface or execution model, Vibecraft stops working until someone updates the hook scripts. You're also creating potential conflicts—if another tool tries to hook the same events, you get unpredictable behavior. This isn't a polished plugin system with versioning and compatibility guarantees; it's brittle instrumentation.

The value proposition collapses for single-session use. If you're running one Claude instance, the 3D visualization is overkill. You're installing dependencies (Node.js, tmux, the browser client), modifying hooks, and managing a WebSocket server just to see one avatar move around a workshop. A simple tail -f on Claude's log file gives you 90% of the insight with zero setup. The spatial metaphor only pays dividends when you're juggling multiple concurrent sessions and need at-a-glance differentiation. For solo work, it's an impressive demo that adds complexity without corresponding benefit.

Verdict

Use if: You're regularly orchestrating 3+ parallel Claude Code sessions on complex, multi-component projects where visual session differentiation and spatial audio cues genuinely improve your ability to track which agent is handling what. The tmux integration and bidirectional prompting make this a legitimate orchestration interface for power users who've already automated workflows with multiple AI instances. Skip if: You primarily work with a single Claude session, run Windows without WSL2, or prefer terminal-native workflows where tmux panes and grep suffice. The setup overhead and maintenance burden (hook modifications, dependency management) only make sense when the multi-session visualization directly solves a coordination pain point you currently experience. If you're exploring out of curiosity rather than desperation, standard Claude Code will serve you better.