The idea

You spin up Claude agents. They work on your code. But instead of staring at terminal logs, you watch a little western town come to life.

Each building is a project. Each floor is an agent. When an agent needs you, a speech bubble pops up — click it, answer, and they get right back to work.

Quick start

npx claude-town-app

That's it. Your town opens in the browser, ready for business.

It scans the current directory for projects, so run it from wherever your repos live. A password is auto-generated and printed to the console on first run.

Note: Claude Town uses your existing Claude Code subscription to run agents. No separate API key needed.

Requirements

• Bun — curl -fsSL https://bun.sh/install | bash
• Claude Code subscription (Max or Team plan)
• Git

Reading the town

The buildings tell you everything at a glance:

| What you see | What it means | |---|---| | Flickering yellow windows | Agent is busy working | | Boarded-up dark windows | Agent finished the job | | Pulsing orange glow | Agent is waiting on you | | Speech bubble floating above | Click me! Agent has a question |

No dashboards. No log-tailing. Just a town you can read like a book.

How to use it

Build something --> Click +, pick a project, choose a building style (saloon, bank, sheriff office...), write a prompt, and watch your agent get to work.

Check in --> Windows glow and flicker as agents work. You can feel the activity without opening anything.

Respond --> Speech bubble? Click it. Quick-response panel lets you answer and get back to watching the sunset.

Go deeper --> Click any building to expand it — full conversation logs, streaming output, spawn more agents on the same project.

Each agent gets its own git worktree, so multiple agents can work on the same repo without stepping on each other. When they finish, changes merge back automatically.

CLI options

| Option | Description | Default | |---|---|---| | --port <number> | Port to run on | 3000 | | --no-open | Don't auto-open browser | opens browser | | --password <string> | Set town password | auto-generated | | --data-dir <path> | Data directory | ~/.claude-town |

npx claude-town-app --port 4000 --no-open

What's under the hood

Frontend (React 19 + Vite)         Backend (Hono + Bun)
  ├── Pixel art town scene           ├── Claude Agent SDK sessions
  ├── CSS-rendered building sprites  ├── File-based JSON storage
  ├── Day/night cycle + sounds       ├── Git worktree isolation
  ├── Quick-response panels          ├── Auto-merge on completion
  └── WebSocket client               └── WebSocket broadcasts

Real-time — WebSocket pushes every state change, message, and event to all connected clients. No polling.

Resumable — Send feedback to a completed agent and it picks back up with full conversation context via the SDK's resume option.

Isolated — Each agent works in its own git worktree. No merge conflicts between agents. Changes merge back when the job is done.

The stack

| Layer | Tech | |---|---| | Runtime | Bun | | Backend | Hono | | Frontend | React 19, Vite, Tailwind CSS v4 | | Agents | @anthropic-ai/claude-agent-sdk | | Font | Press Start 2P | | Aesthetic | Pure vibes |

Building styles

Your agents deserve nice offices. Pick from 8 hand-crafted pixel art buildings:

Saloon · Bank · Sheriff Office · General Store · Hotel · Masjid · Blacksmith · Post Office

Each one is rendered entirely in CSS. No image sprites. No canvas. Just divs with dreams.

Development

Want to contribute? Saddle up:

git clone https://github.com/yazinsai/claude-town.git
cd claude-town
bun install
bun run dev

Open http://localhost:5173 — you're the new sheriff in town.