Vibecraft: Watching Claude Code Think in Three Dimensions

Hook

What if debugging an AI agent wasn’t about parsing logs, but watching a 3D character walk between a bookshelf, a desk, and a terminal? Vibecraft turns Claude Code’s tool usage into a spatial performance you can observe in real-time.

Context

As AI coding assistants mature beyond simple autocomplete, they’ve become autonomous agents that read files, execute bash commands, and modify codebases across dozens of operations per task. But observability hasn’t kept pace. Traditional approaches—scrolling through JSON logs or watching terminal output fly by—become overwhelming when you’re orchestrating multiple Claude instances working on different parts of a system. The cognitive load of tracking “which Claude is doing what” across parallel sessions creates a bottleneck that no amount of tmux window-switching can solve.

Vibecraft emerged from this friction point: the realization that AI agent behavior is fundamentally spatial. When Claude reads documentation, writes code, then tests it in a shell, that’s not a list of events—it’s a workflow with location and movement. By hooking directly into Claude Code’s CLI and piping tool usage events to a WebSocket server, Vibecraft renders this workflow as a 3D scene where Claude moves between stations (bookshelf for file reads, desk for writes, terminal for bash commands). What makes it remarkable isn’t just the visualization—it’s that this works for multiple Claude instances simultaneously, giving you a control room view of parallel AI agents at work.

Technical Insight

Vibecraft’s architecture is deceptively clever: it bypasses API proxying entirely by injecting bash wrapper scripts directly into Claude Code’s execution path. When you run npx vibecraft start, it spawns a Node.js WebSocket server and modifies your environment to intercept Claude’s tool calls at the shell level. Here’s what the hook injection looks like:

# Injected wrapper that intercepts Claude tool calls
original_claude=$(which claude)

function claude() {
  $original_claude "$@" 2>&1 | tee >(while IFS= read -r line; do
    # Parse JSON tool events with jq
    tool=$(echo "$line" | jq -r '.tool // empty')
    args=$(echo "$line" | jq -r '.arguments // empty')
    
    if [ -n "$tool" ]; then
      # Send to WebSocket server
      echo "{\"type\":\"tool\",\"name\":\"$tool\",\"args\":$args}" | \
        websocat ws://localhost:3473/events
    fi
  done)
}

This zero-latency approach means visualization updates happen as Claude executes, not after log aggregation. The WebSocket server maintains state for each Claude session, identified by tmux session names. When Claude invokes read_file, the server dispatches an event to the Three.js frontend, triggering an animation of Claude walking to the bookshelf station.

The multi-agent coordination is where things get interesting. Vibecraft uses tmux as a process orchestration layer, spawning each Claude instance in a named session. The control interface lets you create new Claude instances (rendered as mini-Claudes emerging from a “portal” in the 3D scene) and switch between them:

// Server-side session management
interface ClaudeSession {
  id: string;
  tmuxSession: string;
  position: Vector3;
  currentTool: string | null;
  taskQueue: Task[];
}

class SessionOrchestrator {
  private sessions = new Map<string, ClaudeSession>();
  
  spawnSession(taskDescription: string): ClaudeSession {
    const sessionId = `claude-${Date.now()}`;
    
    // Spawn tmux session with Claude instance
    execSync(`tmux new-session -d -s ${sessionId} 'claude --task "${taskDescription}"'`);
    
    const session = {
      id: sessionId,
      tmuxSession: sessionId,
      position: this.getSpawnPosition(),
      currentTool: null,
      taskQueue: []
    };
    
    this.sessions.set(sessionId, session);
    this.broadcastSessionUpdate();
    return session;
  }
  
  sendPrompt(sessionId: string, prompt: string) {
    // Send text to tmux session's stdin
    execSync(`tmux send-keys -t ${sessionId} "${prompt}" Enter`);
  }
}

The spatial metaphor extends to error handling. When Claude encounters an error (detected by parsing stderr or exit codes), the 3D model plays a “head shake” animation. Git commits trigger a celebration animation. This semantic event parsing happens server-side:

function parseToolEvent(event: ToolEvent): AnimationTrigger {
  if (event.tool === 'bash' && event.result?.exitCode !== 0) {
    return { type: 'error', severity: 'shake' };
  }
  
  if (event.tool === 'bash' && /git commit/.test(event.arguments?.command)) {
    return { type: 'success', celebration: 'commit' };
  }
  
  // Map tools to spatial locations
  const stationMap = {
    'read_file': 'bookshelf',
    'write_file': 'desk',
    'bash': 'terminal',
    'search': 'archive'
  };
  
  return {
    type: 'movement',
    destination: stationMap[event.tool] || 'idle'
  };
}

What elevates Vibecraft beyond novelty is the interaction model it enables. You can send prompts to any Claude instance from the browser (no terminal switching), cancel operations via relayed Ctrl+C signals, and even use voice input through Deepgram integration. The “draw mode” lets you annotate the 3D space with spatial notes—useful for marking which areas of your codebase each Claude instance should focus on. This transforms the visualization from passive monitoring into an active control surface for multi-agent workflows.

Gotcha

The bash hook injection strategy is Vibecraft’s biggest strength and its Achilles heel. Because it wraps the Claude CLI binary, any updates to Claude Code’s output format or execution model can break the parsing logic. You’re essentially running a man-in-the-middle intercept on a tool you don’t control. During testing, a Claude update that changed JSON output formatting required immediate patches to the jq parsing logic. For production use cases where stability matters, this brittleness is a dealbreaker.

Platform limitations are equally significant. Windows users are entirely excluded due to the bash dependency—no PowerShell equivalent exists. The setup process, while streamlined through npx, still requires jq, tmux, and Node 18+ as system dependencies. This isn’t a Docker-based solution you can spin up in isolation; it modifies your shell environment. For developers who prefer minimal system modifications or work in containerized development environments, the invasive setup is a non-starter. Additionally, the 3D rendering can be resource-intensive when visualizing many concurrent Claude sessions—expect noticeable browser CPU usage with more than five active instances.

Verdict

Use if: You’re running multiple Claude Code instances on macOS or Linux and need spatial awareness of parallel agent activities—especially valuable for complex refactoring tasks where different Claudes handle different modules simultaneously. The visualization genuinely aids comprehension when traditional terminal multiplexing becomes cognitively overwhelming. Also consider it if you’re researching LLM agent observability patterns and want to explore spatial UI paradigms beyond text logs. Skip if: You’re on Windows, need production-grade stability (the bash hook injection is too brittle for CI/CD or long-running deployments), prefer minimal dependencies, or primarily work with single Claude instances where terminal output provides sufficient observability. This is a power-user exploration tool for developers comfortable with tmux who value experimental interfaces over battle-tested reliability.