Turn any repo into a living isometric city — watch Claude Code agents build it brick by pixel brick in real time, or rewind its entire git history into a time-lapse movie.
Live demo · Install · The two views · Modes · How it works
Your repo, but make it a tiny pixel metropolis. Agentopolis turns a git repository into a Habbo-style isometric city and runs two scenes at once, on one page:
- The skyline is your codebase — seeded from git history, zoned by architecture. Files are buildings, and the city grows taller every time your agents ship.
- The dispatch floor below is City Hall, where every Claude Code agent is a little pixel worker clocking in, hustling between stations, and getting things done.
All hand-drawn pixel art on a plain canvas (no Habbo assets were harmed), zero-config, and the live view never so much as taps Claude Code on the shoulder — it stays completely off the critical path.
- 🖥️ A live "screensaver" for your coding sessions. Park
agentopolison a spare monitor and your codebase turns into a city you watch get built in real time — workers scurry between stations as agents run tools, scaffolding snaps around the file you're editing, and everygit commitcuts the scaffold loose and raises a fresh floor. It's oddly hypnotic, and a glanceable read on exactly what your agents are up to right now. - 🎬 A ridiculously fun way to show off a repo.
agentopolis movie https://github.com/owner/repofast-forwards any public repo's entire git history into a growing-city time-lapse — no clone, no setup, no fuss. Share it as a clean link or an autoplaying embed and it unfurls with a shiny skyline card. Perfect for a README hero, a launch-day flex, or settling the "this project came a long way" argument once and for all.
- Install
- Quickstart
- Usage recipes
- The two views
- Modes
- Sharing & embedding
- Onboarding tour
- Zoning
- How it works
- Development
- Known limits
- License
uv tool install agentopolis # or: pipx install agentopolis
# or: brew install codeblackwell/tap/agentopolisNeeds Python 3.11+ and travels light — FastAPI and uvicorn are the only runtime dependencies.
cd ~/code/any-repo
agentopolis # live: city on :4242, Claude Code sessions auto-report (this run only)
agentopolis ~/code/other-repo # …or point at any repo
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 marathon ~/code # play every repo's movie back-to-back
agentopolis marathon ~/code --list # …or just rank them by movie potentialOpen http://localhost:4242, fire up any Claude Code session, and watch it stroll in and report for duty — no extra wiring. Leave the tab open on a spare monitor and you've got a live screensaver of your agents at work. No session handy? http://localhost:4242/?demo plays a scripted day in the city so you can see the whole show.
Run it right in the repo you're hacking on. By default it clips the hooks on when it starts and tidies them away when you quit — fire-and-forget, nothing to clean up:
cd ~/code/my-project
agentopolis # serve on :4242, hooks attached for this run onlyPin http://localhost:4242 on a second monitor and code with Claude Code like
you always do — every session (and every subagent it spawns) wanders in on its
own. Workers bustle across the dispatch floor as tools run, scaffolding hugs the
file being edited, and each git commit drops the scaffold and raises new floors.
Want the city open for business across every session and project? Attach the hooks once and just serve whenever the mood strikes:
agentopolis attach # write hooks into ~/.claude/settings.json (a backup is saved)
agentopolis # serve the live city; sessions keep reporting in
agentopolis detach # remove the hooks when you're doneBabysitting a whole workspace at once? Spread every repo under a folder across a world map as a nation of cities:
agentopolis --root ~/code # one map, one city per repoRewind any repo's git history and watch the city sprout in fast-forward. Aim it at a public GitHub URL (no clone — it sips just enough git data, all in memory) or a local path:
agentopolis movie https://github.com/owner/repo # any public repo
agentopolis movie ~/code/my-project # …or your own, local
agentopolis movie # …or the current repoWhen the movie rolls, smash Share to grab a clean link, fling it to socials,
or download the build clip. Heads up: links from a local run point at
localhost (great for you, useless for everyone else), so to share with the
world open the same repo on the hosted instance — or your own deployed one:
# Canonical link — unfurls with a generated skyline card:
https://agentopolis.codeblackwell.ai/c/owner/repo
# Chromeless autoplaying embed for a README or blog post:
<iframe src="https://agentopolis.codeblackwell.ai/player/owner/repo"
width="800" height="450" frameborder="0" allowfullscreen></iframe>
Can't decide which repo is the blockbuster? Let Agentopolis scout the talent, then screen the whole lineup back-to-back:
agentopolis marathon ~/code # auto-advancing reel, best first
agentopolis marathon ~/code --top 5
agentopolis marathon ~/code --list # score every repo by movie potential, no playbackThe city is the repo. A zoning manifest maps globs to components and layers (or Agentopolis just eyeballs your top-level directories and zones it for you), then every building is sculpted straight from the code:
| Encoding | Maps to |
|---|---|
| Floors | cross-component centrality (how much depends on it) |
| Footprint | lines of code |
| Window glow | recency — recently-touched files light up |
| Building shape | language family — pyramids for scripting, glass drums for web, ziggurats for compiled |
| Tethered clouds | managed services, floating above the city |
(Bored of shapes-by-language? Flip them to key off rarity / size / age instead.)
As agents work, the city builds itself: edits throw up scaffolding, a git commit
yanks the scaffolds down and stacks on floors, and brand-new files pop into
existence as brand-new buildings. The map quietly re-seeds from git every time
HEAD moves. Grab the full-screen explorer at / and pan, zoom, and gawk to your
heart's content.
Every agent is a pixel worker with somewhere to be. Your main session checks in at reception, subagents stroll through the door the moment they're spawned, and each tool call sends a worker marching off to the right station:
| Station | Tools |
|---|---|
| CRT terminal | Bash |
| Archive shelf | Read, Grep, Glob |
| Workshop | Edit, Write |
| Telephone booth | web tools |
A pulsing gold aura means a session is twiddling its thumbs waiting on you (a permission prompt or just idle). Hover any guest to see who they are and what they're busy with.
| Command | What it does |
|---|---|
agentopolis |
Serve the live city; attach hooks for this run only, removed on exit (zero setup) |
agentopolis <repo> |
Same, but map a repo other than the current dir |
agentopolis movie [target] |
Replay a repo's git history as a city that grows and re-forms commit by commit |
agentopolis marathon <folder> |
Grab every repo's movie and play them best-first in one auto-advancing reel |
agentopolis marathon <folder> --list |
Rank the repos by movie potential (formation ladder, history length, deletions) without playing them |
agentopolis --root <folder> |
Map every git repo under a folder as a nation of cities on a world map |
agentopolis attach / detach |
Wire the hooks into settings.json for good (across every session), or pull them back out |
By default agentopolis is the lazy genius path — it clips the Claude
Code hooks on at startup and whisks them away when you quit, and it's polite
enough to leave a prior manual agentopolis attach alone. Want the hooks to
stick around across every session, even when the city isn't running?
agentopolis attach wires them once (and stashes a backup of settings.json
first), and agentopolis detach pulls them back out.
target is a local repo dir or a public github url. GitHub
repos download only the bare-minimum git data (a blob:none clone that gets
shredded the instant seeding is done) and the city lives entirely in memory. Run
it outside a git repo and Agentopolis won't sulk with a blank map — it'll kindly
point you at one instead.
Runs fully local and offline, and caches per repo+HEAD so the encore is instant.
--top N trims the playlist to the headliners. --list skips playback and just
ranks the repos by movie potential as a table, and --list --json emits that
ranking as JSON.
Building a city from a repo's history is half the fun — showing it off is the other half. Clean canonical links and a chromeless autoplaying player make a city trivial to drop into a README, a group chat, or a launch post:
…/c/owner/repo— canonical movie link (equivalent to?forge=github.com/owner/repo)…/player/owner/repo— chromeless autoplaying movie for iframe embeds and player cards
Shared links unfurl with a generated social card showing the captured skyline. The in-app Share button (top-right of any city) builds these links for you and also offers a downloadable clip — see the sharing recipe for the exact URLs and an embed snippet.
First visit? A guided tour spotlights every part of the interface, narrated by a hand-drawn pixel Chief of Staff who is, frankly, thrilled you're here. It auto-runs once per view (shared movie/forge links included), and the "?" handle beneath the camera controls summons it back anytime. See docs/tour.md.
Drop an .agentopolis.json manifest in the repo to play city planner — it defines
the components, layers, and floating clouds (see
city/example.json for the full blueprint). Skip it and
Agentopolis happily zones the place itself from your top-level directories. Point
at a custom manifest with --zone.
The rest of the knobs: a bare path or --repo (which repo to map, default cwd), --port
(default 4242), --no-open (skip the browser pop), --showcase (serve baked
nation fixtures with no live git).
Claude Code hooks ──curl──▶ POST /hook ──▶ normalize ──SSE──▶ canvas renderer
No magic, just plumbing:
hooks.pyregisters acurl -m 1 … || trueon eight hook events (SessionStart, UserPromptSubmit, Notification, Pre/PostToolUse, Stop, SubagentStop, SessionEnd). It never blocks Claude Code — if the city's asleep, the curl shrugs, times out, and moves on.server.py(FastAPI) slims each payload down to{event, session, tool, detail}(plusagent_id/agent_typefor events fired inside subagents), remembers the last 100 events, and broadcasts them over SSE — so latecomers still get the recap.static/paints the room, the city, and the citizens on a plain canvas. The skyline is seeded from git (seed.py) and re-seeds itself whenever HEAD moves.
Want to tinker under the hood? The justfile has you covered:
just dev # nation for the parent workspace on :4242 (hot reload)
just town ../some-repo # serve one repo as a city on :4243
just movie ../some-repo # time-lapse a repo's history on :4244
just test # backend functional + Playwright UI suite (81 tests)First Playwright run, grab a browser: uv run --extra test playwright install chromium.
Releases are tag-driven — just release X.Y.Z bumps the version, tags, and
pushes, then CI takes the wheel: publish to PyPI, update the Homebrew tap, and
redeploy the hosted demo while you go get coffee.
- Citizens only face forward for now — no directional sprites yet, so everyone's a bit of a poser.
MIT © LeChristopher Blackwell