Metadata-Version: 2.4
Name: agentopolis
Version: 0.8.0
Summary: Agentopolis — Habbo-style visualization of Claude Code agents building your repo as a city
Project-URL: Homepage, https://github.com/CodeBlackwell/agentopolis
Project-URL: Source, https://github.com/CodeBlackwell/agentopolis
Project-URL: Issues, https://github.com/CodeBlackwell/agentopolis/issues
Author-email: LeChristopher Blackwell <codeblackwell@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: agents,claude-code,isometric,pixel-art,visualization
Requires-Python: >=3.11
Requires-Dist: fastapi>=0.110
Requires-Dist: uvicorn>=0.29
Description-Content-Type: text/markdown

# Agentopolis

A Habbo-style isometric visualization of Claude Code at work, in two views on
one page. **The dispatch floor** (City Hall): every agent is a pixel worker —
your main session checks in at reception, subagents walk through the door when
spawned, and tool calls send workers to stations — the CRT terminal for `Bash`,
the archive shelf for `Read`/`Grep`, the workshop for `Edit`/`Write`, the
telephone booth for web tools. **The skyline above**: the city is the codebase
itself, seeded from git history and zoned by architecture (a zoning manifest
maps globs to components and layers; floors = cross-component centrality,
footprint = lines of code, window glow = recency; managed services float as
tethered clouds). As agents work, the city builds itself out — edits wrap
buildings in scaffolding, a `git commit` drops the scaffolds and adds floors,
new files pop up new buildings. `/city.html` is a full-screen explorer with
pan/zoom. The city re-seeds itself from git whenever HEAD moves.

## Install & run

```bash
uv tool install agentopolis         # or: pipx install agentopolis
                                    # or: brew install codeblackwell/tap/agentopolis
agentopolis attach                  # one-time: fire-and-forget hooks into ~/.claude/settings.json

cd ~/code/any-repo
agentopolis                         # its city on http://localhost:4242
```

Open http://localhost:4242, then start any Claude Code session — new sessions
report in automatically. No live session handy? http://localhost:4242/?demo
runs a scripted day in the city. `agentopolis detach` removes the hooks (a backup
of settings.json is written on attach). Flags: `--repo`, `--port`, `--zone`.

**Zoning:** if the repo has a `.agentopolis.json` manifest it defines the city's
components, layers, and clouds (see `city/maisight.json` for a full example);
otherwise agentopolis auto-zones from the repo's top-level directories. For repo
hackers: `just dev` serves ../maisight with its manifest.

## How it works

```
Claude Code hooks ──curl──▶ POST /hook ──▶ normalize ──SSE──▶ canvas renderer
```

- `hooks.py` registers a `curl -m 1 ... || true` command on eight hook events
  (SessionStart, UserPromptSubmit, Notification, Pre/PostToolUse, Stop,
  SubagentStop, SessionEnd). It never blocks Claude Code — if the hotel isn't
  running, the curl times out silently.
- `server.py` (FastAPI) trims each payload to `{event, session, tool, detail}`
  (plus `agent_id`/`agent_type` for events fired inside subagents), keeps the
  last 100 events, and broadcasts over SSE — late-joining browsers get a replay.
- `static/render.js` + `static/hotel.js` draw the room and guests on a plain
  canvas — original pixel art, no Habbo assets. Subagent tool calls move their
  own guest, a pulsing gold aura marks a session waiting on you (permission or
  idle), and hovering a guest shows who they are and what they're doing.

## Known limits (v0)

- Front-facing avatars only; no directional sprites yet.
