commandcraft

v0.1.1

Published

6 days ago

Watch your code base rise - RTS-style interface for Claude Code

0High
0Medium
0Low

jerof

claude claude-code ai coding visualization rts strategy-game dashboard developer-tools

CommandCraft

Watch your code base rise - A classic RTS-style interface for Claude Code.

See your coding session transform into a living medieval city. Files become buildings, workers construct them in real-time, and bugs become enemy raids when tests fail.

Quick Start

npx commandcraft

That's it! The dashboard opens automatically and starts capturing Claude Code events.

What You'll See

Buildings: Each file you create becomes a building (components are houses, APIs are markets, tests are barracks)
Workers: Little villagers walk to construction sites and build your code
Bug Raids: When tests fail, enemy bugs attack your buildings
Tech Tree: Progress through ages as your project grows (Seed → MVP → Scale)
Minimap: Click to navigate, see workers and bugs in real-time
Sounds: Satisfying construction sounds, fanfares, and alerts

Features

Isometric City View

Your codebase visualized as a classic RTS-style city with:

8 building types based on file type (component, page, API, utility, config, test, style, type)
5 construction stages with animated progress
Workers that walk between buildings
Depth-sorted rendering with smooth camera controls

Real-time Updates

Files appear as buildings construct
Workers move to active construction sites
Bug raids spawn when tests fail
Achievements unlock as you hit milestones

Tech Tree Progression

Seed Stage: 1-10 files - Your project is born
MVP Age: 11-50 files - Core features built
Scale Age: 50+ files - Production ready

Achievement System

First File Created
First Test Passing
10/25/50/100 Files
Zero Failing Tests
And more...

Controls

| Key | Action | |-----|--------| | WASD / Arrows | Pan camera | | Right-drag | Pan camera | | Left-click | Select building / Move unit | | Double-click | Open file in IDE |

Options

npx commandcraft [options]

Options:
  --help, -h       Show help message
  --no-browser     Don't open browser automatically
  --no-hooks       Don't configure Claude Code hooks
  --port <port>    Use a specific port (default: 3000)

How It Works

Hooks: CommandCraft registers hooks with Claude Code to capture events
Bridge: Events are sent to the dashboard via Server-Sent Events (SSE)
Visualization: The dashboard renders your session as an isometric city
State: Zustand manages building positions, workers, and game state

Manual Setup

If you prefer manual setup or want to develop:

# Clone the repo
git clone https://github.com/commandcraft/commandcraft
cd commandcraft

# Install dependencies
npm install

# Start development server
npm run dev

# Open dashboard
open http://localhost:3000/dashboard

Configure Claude Code Hooks Manually

Add to ~/.claude/settings.json:

{
  "hooks": [
    {
      "matcher": "CommandCraft",
      "hooks": [
        { "event": "PreToolUse", "command": "node /path/to/commandcraft/.claude/hooks/bridge.js" },
        { "event": "PostToolUse", "command": "node /path/to/commandcraft/.claude/hooks/bridge.js" },
        { "event": "Stop", "command": "node /path/to/commandcraft/.claude/hooks/bridge.js" }
      ]
    }
  ]
}

Tech Stack

Framework: Next.js 16 (App Router)
Rendering: HTML5 Canvas (2D isometric)
State: Zustand
Styling: Tailwind CSS
Animation: Framer Motion
Sound: Web Audio API (synthesized)
Real-time: Server-Sent Events (SSE)

Troubleshooting

Dashboard shows no activity

Make sure CommandCraft is running (npx commandcraft)
Start a new Claude Code session in a different terminal
Check that hooks are configured: cat ~/.claude/settings.json

Buildings not appearing

Events are received when Claude Code uses tools (Write, Edit, Bash)
Try asking Claude to create a file

Sound not playing

Click anywhere on the page first (browser autoplay policy)
Check the sound toggle button in the top-right of the resource bar

Port already in use

npx commandcraft --port 3001

Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

License

MIT