Agentopolis — the office your Claude Code agents clock into

## How it works

One command. No config. No cloud.

Run `npx agentopolis`

It starts a tiny server on 127.0.0.1, puts the office in your menu bar, and — with your explicit consent — adds async, observe-only hooks to ~/.claude/settings.json. Your existing hooks are untouched, and the file is backed up first.

Code like you always do

Every Claude Code session opens a room in the suite named after its repo. Subagents walk out through the door with a headset on, sit down at a desk, and do whatever they are actually doing — reading, editing, testing, committing.

Glance, don't babysit

When a session needs a permission or an answer, its room lights a pulsing beacon and a coworker stands out front with a hand up. Everything else stays calm. One look at the floor tells you who is working, who is stuck, and what actually landed.

## Reading the floor

Every pixel maps to something real. Nothing here is decorative fiction.

You see	It means
Office suite	A repo (project directory). Suites keep their spot and connect by hallway, so the layout is learnable.
Hot desk	An unnamed session — temporary, marked with a cone. Cleared when the session ends.
Meeting room	An explicitly named session, name over the door. Name a session and its hot desk is promoted to a room — and the room survives restarts.
Coworker	An agent. The foreman in the yellow headset is the session's main loop; subagents wear their own colors (Explore, Plan, general-purpose…).
Coworker at a desk	Truthful activity from real tool calls: researching, editing, testing, building, running, committing, installing, planning, delegating. The monitor color is the activity.
Beacon + raised hand	The session needs you — a permission request or a question is waiting.
Green burst + ✓ banner	Something actually landed: a test suite went green, or a commit was made. The only thing the office celebrates.
Red flash	A turn failed. Recovery is visible too — no silent errors, no fake fires.
Someone at the water cooler	An idle agent. Idle should look idle.
Lights off	A named session ended. The room stays on the floor, dark, ready to reopen.

## Principles

Two rules the renderer never breaks.

⚑Truth before animation

Every animation is driven by a real event from Claude Code hooks. A coworker only types while a tool call is actually running; the moment it ends, they stop. States come from a reducer over a versioned event protocol — not vibes.

Stale activities time out to idle, never to “failed”. Out-of-order events are tolerated, duplicates dropped. If the floor shows a test running, a test is running — and clicking the coworker shows you the event behind it.

✓Outcomes, not elapsed time

A busy-looking office is not a productive one. Agentopolis celebrates exactly two things — a test suite going green and a commit landing — and nothing else. Tool calls, token counts, and wall-clock time never earn a burst.

So a run that spins for twenty minutes and produces nothing looks exactly like what it is. Attention is the only other loud thing on the floor; when nobody needs you, it is just a calm place to leave open. Idle throttles to 8fps, and a closed widget renders nothing at all.

## Privacy is the architecture

Not a settings toggle — the way the whole thing is built.

Local only

The server binds to 127.0.0.1 and nothing else — ever. No telemetry, no analytics, no cloud, no network calls. This page has none either.

Metadata only

Redaction happens at the edge, in the hook bridge, before anything hits disk. File names, not contents. Commands truncated to 80 chars with secrets masked. No prompts, no assistant messages, no file bodies — ever.

Open source

MIT licensed, zero runtime dependencies, small enough to actually read. Every sprite is drawn procedurally in code — no tilesets, no sprite sheets, no third-party art licenses to relicense later.

One-command uninstall

npx agentopolis --uninstall removes the hooks and the bridge from your machine. Your local history lives in ~/.agentopolis — delete it any time.

## FAQ

Everything people ask before they run it.

Will this slow down Claude Code?

No. The hooks are async and observe-only — they never block a tool call, a permission prompt, or your input, and they carry a 10-second timeout as a hard ceiling. If the city server isn't running, hook payloads spool to a local folder and are replayed on the next start.

What data leaves my machine?

Nothing. The server listens on 127.0.0.1 only, rejects non-loopback requests, and there is no telemetry of any kind. What's stored locally is already-redacted metadata: session ids, tool names, file names, truncated commands with secrets masked. File contents, prompts, and assistant messages never reach the event stream in the first place.

Does it mess with my Claude Code settings?

Only with your consent — it asks before touching anything (or pass --yes). Hooks are merged into ~/.claude/settings.json non-destructively: existing hooks from other tools are untouched, the file is backed up before the first write, and uninstall removes only Agentopolis's own entries.

Do I lose the floor plan when I restart?

No. Suites, meeting rooms, and their positions persist in ~/.agentopolis/city.json and survive restarts. Events that fire while the server is down are spooled and replayed, so the office catches up on what it missed.

Can I try it without installing hooks?

Yes — npx agentopolis --demo runs a synthetic agent swarm and never touches your Claude settings. In fact, the background of this page is that exact demo: the shipped renderer fed by the shipped demo script, running live in your browser.

Will it eat my battery?

Measured, not asserted (Apple silicon, sampled over 20s): the server idles at ~0.5% of one core and 67 MB. The widget costs ~14% of one core with a busy three-suite office and ~6–9% when the office is quiet, and renders nothing at all while its popover is closed. Pixel art is stepped animation, so the renderer caps at 20fps while work happens and 8fps when it doesn’t, and static floors and walls are baked once instead of redrawn. prefers-reduced-motion is honored, and a calm mode removes walking and celebrations entirely.

How is this different from Munder Difflin?

Munder Difflin is a harness — it spawns and orchestrates agents for you, with real terminals, an orchestrator, and shared memory, inside an Electron app. Agentopolis is a viewer: it spawns nothing and orchestrates nothing, it just shows you the sessions you already start, from your menu bar, installed with one command. If you want a team of agents run for you, theirs is the better fit. If you want to see what your own agents are doing without adopting a new workflow, use this. They attach hooks per session and we install globally, so you can run both at once.

Wait, isn’t there another Agentopolis?

Yes, and it got there first on PyPI. CodeBlackwell/agentopolis is an unrelated Python project that renders a codebase as an isometric city from its git history. Same name, different tool, different registry, no affiliation. This one is the npm package agentopolis.