vibecraft: Instructions file for Claude Code

Vibecraft - Technical Documentation

This document explains the Vibecraft codebase for future AI assistants working on this project.

Project Purpose

Vibecraft visualizes Claude Code's activity in real-time as a 3D workshop. When Claude uses tools (Read, Edit, Bash, etc.), a character moves to corresponding workstations in a Three.js scene. The user can also send prompts to Claude from the browser via tmux integration.

Architecture Overview

Claude Code → Hook Script → WebSocket Server → Browser (Three.js)
                  ↓
            events.jsonl (persistent log)

Data Flow

1. Claude Code executes tools (Read, Edit, Bash, etc.)
2. Hook script (hooks/vibecraft-hook.sh) receives JSON via stdin from Claude Code's hook system
3. Hook writes to ~/.vibecraft/data/events.jsonl AND POSTs to http://localhost:4003/event
4. WebSocket server (server/index.ts) broadcasts events to connected clients
5. Browser (src/main.ts) receives events and moves the Claude character

Important: Both hook and server use ~/.vibecraft/data/ as the data directory. This ensures they share the same files regardless of how vibecraft was installed (npx, global npm, or local dev).

EventBus Architecture

Events are handled via a decoupled EventBus pattern, separating concerns into focused handler modules:

handleEvent(event)
    ↓
eventBus.emit(type, event, context)
    ↓
┌─────────────────────────────────────────────────────────┐
│  soundHandlers.ts      → Tool sounds, lifecycle sounds  │
│  notificationHandlers.ts → Zone floating text           │
│  characterHandlers.ts  → Movement, states               │
│  subagentHandlers.ts   → Task spawn/remove              │
│  zoneHandlers.ts       → Zone attention/status          │
│  feedHandlers.ts       → Thinking indicator             │
└─────────────────────────────────────────────────────────┘
    ↓
main.ts continues       → UI updates (DOM), special cases

Files:

• src/events/EventBus.ts - Core event dispatch with typed handlers
• src/events/handlers/ - Handler modules (6 files)
• src/events/handlers/index.ts - Barrel export with registerAllHandlers()