Metadata-Version: 2.4
Name: agentopolis
Version: 0.16.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
Project-URL: Changelog, https://github.com/CodeBlackwell/agentopolis/blob/master/CHANGELOG.md
Author-email: LeChristopher Blackwell <codeblackwell@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: agents,claude-code,isometric,pixel-art,visualization
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Topic :: Software Development :: Version Control :: Git
Requires-Python: >=3.11
Requires-Dist: fastapi>=0.110
Requires-Dist: uvicorn>=0.29
Provides-Extra: card
Requires-Dist: pillow>=10.1; extra == 'card'
Provides-Extra: test
Requires-Dist: httpx; extra == 'test'
Requires-Dist: pillow>=10.1; extra == 'test'
Requires-Dist: pytest-playwright>=0.5; extra == 'test'
Requires-Dist: pytest>=8; extra == 'test'
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, building shape = language
family — pyramids for scripting, glass drums for web, ziggurats for compiled,
toggleable to key off rarity/size/age instead; 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

cd ~/code/any-repo
agentopolis .                       # zero-setup: hooks attached, city on :4242, hooks removed on exit

agentopolis movie                   # replay this repo's git history as a growing city
agentopolis movie ../other-repo     # …or any local repo
agentopolis movie https://github.com/owner/repo   # …or any public github repo

agentopolis crawl ~/code            # rank a folder of repos by movie potential
agentopolis marathon ~/code         # play every repo's movie back-to-back, with a selection bar
```

`agentopolis .` is the one-command path: it attaches the Claude Code hooks on
start and removes them again when you quit (Ctrl+C) — no separate setup or
teardown. Open http://localhost:4242, then start any Claude Code session and it
reports in automatically. No live session handy? http://localhost:4242/?demo
runs a scripted day in the city.

Prefer persistent hooks? `agentopolis attach` wires them once (a backup of
settings.json is written), `agentopolis` then just serves, and `agentopolis
detach` removes them. `agentopolis .` leaves a manual attach untouched. Flags:
`--repo`, `--port`, `--zone`.

**First visit?** A guided onboarding tour spotlights each part of the interface,
narrated by a pixel "Chief of Staff" — replay it anytime from the ⭐ badge. See
[docs/tour.md](docs/tour.md).

**Movie mode** (`agentopolis movie [target]`) replays a repo's whole git history
as a city that grows and re-forms commit by commit. `target` is a local repo dir
or a public github url; github repos download only the minimum git data (a
`blob:none` clone removed right after seeding) and the city is held in memory
only. Run outside a git repo and agentopolis tells you how to point it at one
instead of opening a blank map.

**Crawl & marathon** scan a folder of repos. `agentopolis crawl <folder>` ranks
them by movie potential (formation ladder, history length, deletions). `agentopolis
marathon <folder>` then grabs every repo's movie and plays them best-first in one
auto-advancing reel with a selection bar to jump around — all local and offline,
and cached per repo+HEAD so the next run is instant. `--top N` caps the playlist.

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

## 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.
