claude-village

A Mac desktop app that visualizes running Claude Code sessions as an animated Minecraft-style village. Each session is a tab. Each agent is a voxel character walking between themed zones based on the tool it is using right now - reading files in the library, writing code in the office, searching in the mine, running tests on the farm, committing in the nether portal, and so on.

Screenshots

Village overview — The village seen from orbit: nine tool-mapped zones on a round island, agents clustered by the zone they are using, boats cruising the sea, minor islands on the horizon.

Grass and flowers on the island — Close look at the grass cap: scattered grass tufts and flowers, signposts in front of each zone, a cluster of agents standing beside the Spawner.

Agents at the Office zone — Agents at the Office. Each character has a name label; the latest action shows as a speech bubble, and hovering opens a tooltip.

Panorama view — Wide-angle view across the water - clouds overhead, boats sailing past, villagers on the shoreline.

Underwater atmosphere — Dive the camera below the waterline and the scene swaps to an underwater atmosphere: blue-teal fog, hidden sky, sandy seabed with rocks and seagrass, fish drifting past.

Settings dialog with hook installer — Install / Uninstall the Claude Code hook non-destructively from the Settings dialog, with a diff preview. Session filter and ghost-retirement timer live here too.

In-app help dialog — Built-in Help covers camera / mouse / keyboard controls and a live zones table pulled from the source.

Get going

Download the .dmg, drag to Applications, run the Gatekeeper unlock.

Tabs, zones, tooltips, timeline, settings - how to drive the app.

🛠 Development

Clone, install, dev loop, test, build, package.

Under the hood

📐 Design spec

Architecture, data flow, zones, animations, tooltips.

📋 Implementation plan

The 17 tasks that built the app.

Live status of tasks, tech debt, lessons learned.

CI reports

🧪 Unit tests

Vitest HTML report from the latest main build.

V8 coverage - line, statement, branch, function.

Playwright HTML report (runs against the real packaged app).

Credits

Created by Haim Adrian for Claude Code users.