CodeCrossing

A cozy 3D village where AI coding agents work as villagers, building software together.

Overview

CodeCrossing provides a visual environment for AI agents that:

• Visualize work as a 3D voxel village where agents appear as animal villagers
• Orchestrate teams with multi-agent coordination (Planner, Implementer, Reviewer)
• Stream real-time with WebSocket updates showing tool usage and progress
• Run locally with secure token auth and no data leaving your machine

Quick Start

# Start CodeCrossing
npx codecrossing

This will:

1. Configure your dev folder (first time only)
2. Start the backend server on port 3001
3. Generate a secure session token
4. Open https://codecrossing.dev in your browser

Features

Agent System

| Role | Animal | Name | Purpose | |------|--------|------|---------| | General | 🦄 Unicorn | Unity | Versatile, handles any task | | Planner | 🐧 Penguin | Percy | Breaks down tasks into phases | | Implementer | 🐻 Bear | Bruno | Writes code following plans | | Enforcer | 🐱 Cat | Cleo | Validates work against standards | | Reviewer | 🦊 Fox | Felix | Code review and cleanup | | Researcher | 🦜 Parrot | Polly | Gathers information |

Security

| Protection | Implementation | |------------|----------------| | Local-only backend | Runs on localhost, no remote access | | Token authentication | Generated per session, expires on restart | | No data upload | Your code stays on your machine | | API key isolation | Claude keys in local environment only |

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    CodeCrossing System                       │
│                                                              │
│  ┌────────────────────────────────────────────────────────┐ │
│  │       Frontend (Deployed: codecrossing.dev)            │ │
│  │  ┌───────────┐  ┌──────────┐  ┌──────────────────┐    │ │
│  │  │   R3F     │  │  Zustand │  │ WebSocket Client │    │ │
│  │  │  Village  │  │   Store  │  │                  │    │ │
│  │  └─────┬─────┘  └────┬─────┘  └────────┬─────────┘    │ │
│  │        └─────────────┼──────────────────┘              │ │
│  │               3D Village Scene                         │ │
│  └───────────────────────┬────────────────────────────────┘ │
│                          │ WSS (Token Auth)                  │
│  ┌───────────────────────┴────────────────────────────────┐ │
│  │        Backend (Local: localhost:3001)                 │ │
│  │  ┌────────────┐  ┌──────────────┐  ┌───────────────┐  │ │
│  │  │ WebSocket  │  │ Orchestrator │  │ Agent Spawner │  │ │
│  │  │   Server   │  │     Loop     │  │ (Claude Code) │  │ │
│  │  └─────┬──────┘  └──────┬───────┘  └───────┬───────┘  │ │
│  │        └────────────────┼──────────────────┘           │ │
│  │                   ┌─────┴─────┐                        │ │
│  │                   │  Agents   │ Claude Code            │ │
│  │                   │  (Percy,  │ Child Processes        │ │
│  │                   │  Bruno,   │                        │ │
│  │                   │  Felix)   │                        │ │
│  │                   └───────────┘                        │ │
│  └────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘

WebSocket Protocol

Real-time communication between frontend and backend:

// Backend → Frontend
type ServerEvent =
  | { type: 'mode_change', mode: 'idle' | 'planning' | 'executing' }
  | { type: 'chat_message', from: string, content: string }
  | { type: 'agent_start', agentId: string, phase: string }
  | { type: 'agent_tool_start', tool: string, input: any }
  | { type: 'agent_complete', agentId: string }
  | { type: 'breakpoint', message: string }
  | { type: 'error', message: string };

// Frontend → Backend
type ClientAction =
  | { action: 'send_message', message: string }
  | { action: 'approve_plan' }
  | { action: 'respond_to_breakpoint', response: string }
  | { action: 'spawn_yard_agent', agentType: string };

Commands

# Start CodeCrossing
npx codecrossing

# Reconfigure dev folder
npx codecrossing init

# Development
npm run dev              # Frontend + Backend
npm run dev:frontend     # Frontend only
npm run dev:backend      # Backend only

# Quality
npm run typecheck        # TypeScript
npm run lint             # ESLint
npm run check            # Both

Configuration

| Variable | Description | Default | |----------|-------------|---------| | PORT | Backend WebSocket port | 3001 | | FRONTEND_URL | Frontend origin for CORS | https://codecrossing.dev | | DEV_FOLDER | Development folder path | Prompted on first run |

Config stored in ~/.codecrossing.json.

Requirements

• Node.js 18+ or Bun
• Claude Code installed (claude auth login)
• Modern browser (Chrome, Firefox, Safari, Edge)

Project Structure

| Directory | Description | |-----------|-------------| | src/components/village/ | 3D scene elements | | src/components/villagers/ | Agent characters | | src/components/ui/ | UI panels | | src/backend/orchestrator/ | Multi-agent loop | | src/backend/agents/ | Agent configs | | src/store/ | Zustand state | | src/audio/ | Sound system | | skills/ | Agent skills | | templates/ | Component templates |

Roadmap

See .vision/NORTH_STAR.md for detailed vision.

Next priorities:

1. Skill system - Reusable capabilities for agents
2. Multi-project support - Switch between projects
3. Agent memory - Persist context across sessions
4. Performance - Optimize for more agents

Engineering Principles

CodeCrossing follows cozy-first design:

• Simple over complex - Low-poly visuals, straightforward architecture
• Performance through refs - No useState in useFrame loops
• Shared geometries - Reuse Three.js objects
• TypeScript everywhere - Explicit types, no any

See CLAUDE.md for development guidelines.

Inspiration

• Animal Crossing - Cozy village aesthetics
• Claude Code - AI coding assistant
• React Three Fiber - React + Three.js

Credits

• Music: Towball's Crossing by Towball
• Sound Effects: Pixabay
• 3D Assets: MagicaVoxel, low-poly models

License

MIT