Agent-Town for Claude Code

Watch your Claude Code agents at work: a Claude Code plugin and a macOS menu bar app (now on Windows too) that show your sessions, subagents, background tasks and approvals as a small 3D office. (Not related to other projects named agent-town.)

Website: samsonchen.github.io/agent-town-claude-code

繁體中文說明

agent-town shows Claude Code's work as a small office on macOS and Windows, seen from above, with 3D characters. The top-down view was inspired by Gather Town. You are the CEO. Each Claude Code session is a Chief of Staff with a staff of its own, and you can watch them take your tickets, call staff, run background jobs, wait for your approval and phone the report back.

1. What agent-town is

Why it exists

Some tasks in Claude Code take a long time. You type a prompt, Claude Code starts reading files, running commands and calling subagents, and then you wait. I wanted to know two things:

• What is Claude Code doing right now?
• Is it done yet?

The first idea was small: play a sound when a long task finishes. That covers "is it done yet".

While working on the sound, I noticed that Claude Code already says a lot about what it is doing: which tool it is calling, which subagent it started, which background task is running, when it is waiting for approval, when it compacts its notes. A sound uses only the last of these. If every one of those events can be heard, it can also be seen, so the sound grew into an office.

What it is made of

• town-link: a Claude Code plugin that watches what Claude Code does and sends short event messages to the app on your own computer, over a local connection. It never changes what Claude Code does.
• The agent-town app: on macOS, a menu bar app that draws the office with RealityKit and plays the sounds; on Windows, a tray app built with Godot that draws the same office.

Nothing leaves your computer except a few short requests per task: town-link asks Haiku, on your own Claude plan or API key, for a task title, the kind of task, and staff roles. See What town-link reads and sends.

What it is not

• It is not a dashboard for measuring productivity. It shows what is happening, not how well.
• It does not control Claude Code. You still work in the terminal or the Claude desktop app; agent-town only watches.
• It is not finished. See Known issues and the roadmap.

2. Installing

You need both parts: the plugin in Claude Code, and the app on your Mac or Windows PC.

The town-link plugin

town-link is built as a Claude Code mod (a plugin with a hooks module), so it needs a Claude Code version that runs mods: v2.1.287 or later. In a Claude Code session:

/plugin marketplace add samsonchen/agent-town-claude-code

/plugin install town-link@agent-town-claude-code

Or from a terminal:

claude plugin marketplace add samsonchen/agent-town-claude-code

claude plugin install town-link@agent-town-claude-code

Then restart Claude Code. In a session, /town shows the installed town-link version and whether the plugin is connected to the app, and /town on or /town off turns sending on or off for all sessions.

Updates are not automatic for this marketplace. To update:

claude plugin marketplace update agent-town-claude-code

claude plugin update town-link@agent-town-claude-code

In the Claude Desktop app: the Code tab, the terminal and the VS Code extension on one Mac share plugins installed for your user, so installing once in any of them is enough. To install from the Code tab itself, click + next to the prompt box, then Add plugins, add the marketplace samsonchen/agent-town-claude-code, and install town-link. This only makes sense for Code tab sessions that run on your Mac (see where it works).

Like every plugin with a hooks module, town-link runs with your user's permissions. It only watches: what it reads and sends.

The app on macOS

Requires macOS 15 or later. With Homebrew:

brew tap samsonchen/agent-town-claude-code https://github.com/samsonchen/agent-town-claude-code

brew install --cask samsonchen/agent-town-claude-code/agent-town

Or download AgentTown-<version>.dmg from Releases, open it, and drag AgentTown into Applications.

The app is signed with a Developer ID and notarized by Apple, so it opens like any other app.

The app appears in the menu bar as a small building, with no Dock icon. Open it before you start work: town-link sends events only while the app is running. To have it start with your Mac, turn on Settings → Open at login.

To update: brew upgrade --cask agent-town, or download the new .dmg.

The plugin and the app have their own version numbers and are updated separately. /town shows the plugin's version, and About shows the app's. The numbers don't need to match: what matters is the protocol between them, which both versions check. If they ever can't work together, /town says so.

The app checks GitHub once a day for a newer app and a newer town-link (Settings → Updates; it sends nothing about you). When one is out, a dot appears on the menu bar icon, the menu says which, and the Updates window shows the commands for how you installed it. A Claude Code session keeps the town-link it started with, so restart your sessions after updating the plugin.

This is the beginning of the README. Read the rest at the original. Read the full README ↗