Using claude-village

claude-village is a Mac desktop app that renders your running Claude Code sessions as an animated Minecraft-style village. Each session is a tab, each agent is a voxel character, and the character walks between themed zones based on whichever tool it is using at that instant. Watching the village gives you a spatial, ambient sense of what Claude is doing without having to stare at a scrolling terminal.

Launching

Open claude-village.app from Applications or Launchpad. The window opens with two panes:

• A sidebar on the left that lists your recent Claude Code sessions (newest first).
• A tabbed main area on the right that shows the village view for each open session.

When a new session starts in any terminal, it appears in the sidebar and a tab opens automatically if the session is active (any activity in the last 60 seconds). Older sessions still show up in the sidebar but do not auto-open a tab; click the row to open one manually. When a session goes idle for long enough, its agent turns into a ghost and eventually retires.

Sidebar

The sidebar shows each session's short ID, project, and last-activity timestamp, sorted by most recent activity first. Status is derived from last activity:

• active - activity in the last 60 seconds (auto-opens a tab).
• idle - activity in the last 10 minutes.
• ended - older than 10 minutes (rendered dimmed).

Click a row to open that session in a new tab. A session already open in a tab is highlighted so you do not open it twice.

The village (the tab body)

The main area of a tab is a 3D village made up of nine themed zones arranged in a ring around a central mayor square:

Agents in a session are one of:

• Mayor - the top-level Claude agent for this session. Stands in the center square.
• Villagers - active sub-agents (spawned via Task). Each walks to the zone matching whatever tool it is using right now.
• Ghosts - sub-agents that went idle. They drift toward the tavern and eventually retire (configurable).

Tooltips

Hover any of the following for a tooltip:

• A zone tile (shows zone name and the tools it represents).
• The signpost (shows destination hosts for recent WebFetch / MCP calls).
• A tool icon floating above a character.
• A villager or ghost (shows agent ID and current tool).

Speech bubbles

Each character has a name label floating above its head and, when it is saying something, a short speech bubble directly under the label. Both are rendered at a fixed on-screen size (name 14px, bubble 13px, with a subtle shadow) so they stay readable at any camera angle or zoom level.

Click the speech bubble to open the right-side bubble drawer, which shows the full message text plus metadata (timestamp, tool, parent agent). Press Esc to close the drawer.

Timeline strip

The bottom of the tab hosts a collapsible timeline strip. Each row is one agent, each segment is a tool call, and time flows left to right. Click a segment to pan the camera to that agent at that moment in the village view. Collapse the strip when you just want the village.

Camera controls

• Click and drag anywhere in the village to rotate the camera.
• Scroll (pinch on a trackpad) to zoom in and out.
• Click a zone to glide the camera's focus to that zone; click a timeline segment to glide to that agent.
• Arrow keys pan the camera along the ground plane relative to where it is currently facing: Up / Down move along the view axis, Left / Right strafe sideways. Forward / back is boosted (~2.2x strafe speed) so the perceived motion feels balanced - forward-pan translates the orbit target along the camera look direction which visually reads slower than strafing at the same world speed. Hold Shift to pan faster. Panning overrides any in-flight focus-agent / focus-zone glide, so pressing an arrow key always gives you immediate manual control.
• + / = (or PgUp) dolly the camera in; - / _ (or PgDn) dolly out.
• Arrow/dolly keys are ignored while focus is inside a text input, textarea, or any other editable field, so typing in Settings never jitters the camera.
• Tilt the camera below the horizon to dive underwater. The world switches to an underwater atmosphere automatically: a blue-teal exponential fog attaches, the sky and clouds hide, and a school of fish appears swimming above the seabed. Rise back above the waterline and the sky returns.

Sidebar footer icons

The bottom of the sidebar has a row of three icon-only buttons, pinned under the session list:

• Settings (gear icon) - opens the settings panel.
• Help (? icon) - opens the Help dialog (keyboard shortcuts, camera / mouse controls, and a quick rundown of each zone).
• About (info icon) - opens the About dialog (version and credits).

Each button has a hover highlight and a tooltip; keyboard focus shows an outline.

Settings

Open settings from the gear icon in the sidebar footer.

• Data source - JSONL tailing is always on. There is no toggle; if you want lower-latency events, add the optional hook via the Install hook button below.
• Install / Uninstall hook - two buttons above the manual JSON snippet. Install merges the claude-village hook entries into ~/.claude/settings.json (or $CLAUDE_CONFIG_DIR/settings.json) after showing a side-by-side before/after diff; existing user hooks are preserved. Uninstall removes only the entries that target 127.0.0.1:49251, leaving any user hooks intact. Both are idempotent. The manual snippet stays for users who prefer hand-merging.
• Ghost retirement timer (minutes) - how long a villager can stay idle before it becomes a ghost. Ghosts then hang around for an hour before despawning. Valid range is 1 to 60 minutes; the choice is persisted to {userData}/user-settings.json and applied on the next 30-second retirement tick. The 1-hour ghost TTL is fixed.

About is no longer nested inside Settings; use the dedicated About icon in the sidebar footer instead.

Help

Open Help from the ? icon in the sidebar footer. The Help dialog covers:

• Camera controls (orbit, zoom, focus-on-click, timeline pan).
• Mouse interactions (zone / signpost / character tooltips, clickable bubbles).
• Keyboard shortcuts (Esc, Cmd+,, Cmd+W, Cmd+Option+I, arrow pan, dolly keys).
• A zone-by-zone table matching the list above, so you do not have to memorise which zone maps to which tool.

Press Esc or click the backdrop to close.

About

Pick one of:

• macOS menu bar -> claude-village -> About claude-village.
• The About icon (info glyph) in the sidebar footer.

Shows the current version and a link to the GitHub repo.

Tabs

• New active sessions (activity within the last 60 seconds) auto-open as tabs.
• Right-click a tab to pin it - pinned tabs stay open across app restarts. Pin state is persisted to {userData}/pinned.json.
• Click the x on a tab to close it. Closing a tab does not affect the underlying Claude Code session.
• The tab bar scrolls horizontally when you have more tabs than fit the window, while the village view keeps its full width, so no session pushes the 3D scene off-screen.

Keyboard shortcuts

• Esc - close the bubble drawer, any open modal, or the settings pane.
• Cmd+, - open settings.
• Cmd+W - close the current tab.
• Cmd+Option+I - toggle DevTools (renderer).
• Arrow keys - pan the village camera along the ground plane (hold Shift for faster).
• + / = / PgUp - dolly the camera in. - / _ / PgDn - dolly out.