agentopolis 0.6.0__tar.gz

agentopolis-0.6.0/.gitignore

@@ -0,0 +1,5 @@
+.venv/
+__pycache__/
+.playwright-mcp/
+__pycache__/
+dist/

agentopolis-0.6.0/CHANGELOG.md

@@ -0,0 +1,74 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres
+to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.6.0] - 2026-06-13
+
+### Changed
+- Renamed the project from Botapest to **Agentopolis**. The CLI is now
+  `agentopolis`, the PyPI package is `agentopolis`, the zoning manifests are
+  `.agentopolis.json` / `.agentopolis-nation.json`, and the dev env vars are
+  `AGENTOPOLIS_*`. Re-run `agentopolis attach` after upgrading.
+
+## [0.5.0] - 2026-06-13
+
+### Added
+- Single-view dashboard combining the city map and the dispatch floor on one page,
+  with eighth-turn rotation and pan/zoom on the main page.
+- Dispatch room reimagined as a zoomed city-hall interior with departmental
+  stations — Information, Records, Operations, Permits & Works, and Switchboard.
+- Hover tooltips on the freight train, container ships, and the package track;
+  hovering the track lists every package dependency.
+- Dynamic district color key and a cloud-services section in the legend.
+- Automatic cloud-provider detection from dependencies and config files
+  (AWS, GCP, Azure, Cloudflare, Stripe, OpenAI, Anthropic, GitHub Actions,
+  Terraform, and more), each tethered to the district that uses it.
+- Rotate / zoom / reset controls panel in the top-right of both the main map and
+  the standalone `city.html` explorer.
+
+## [0.4.0] - 2026-06-12
+
+### Added
+- Diamond-ring radial city layout: concentric district rings around a civic plaza,
+  canals between layers, a radial street grid, a freight train, and rotation.
+
+## [0.3.1] - 2026-06-12
+
+### Added
+- Organic, structure-driven layout with repo-relative thresholds.
+- River with bridges, package freight line, docker port, and a cemetery for
+  deleted files.
+
+## [0.3.0] - 2026-06-12
+
+### Added
+- Organic blocks: carved edge lots and per-lot building jitter.
+
+### Fixed
+- Quieter exit on Ctrl+C.
+
+## [0.2.1] - 2026-06-12
+
+### Added
+- Kind-based building archetypes, language signs, and an isometric city hall.
+- GitHub repository linked in the package metadata.
+
+### Fixed
+- Ctrl+C hung while browsers held SSE streams open.
+
+## [0.2.0] - 2026-06-12
+
+### Added
+- Installable `botapest` CLI, published to PyPI.
+- Auto-free the port on startup.
+
+## [0.1.0] - 2026-06-12
+
+### Added
+- Initial release: The Grand Botapest Hotel — a Habbo-style visualizer for Claude
+  Code agents, with subagent attribution, replay, waiting aura, and tooltips.
+- Botapest City prototype: an architecture skyline generated from a git repo.
+- Combined dispatch floor and live skyline, with a continuous cityscape and
+  waterfront.

agentopolis-0.6.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LeChristopher Blackwell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agentopolis-0.6.0/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: agentopolis
+Version: 0.6.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
+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.

agentopolis-0.6.0/README.md

@@ -0,0 +1,57 @@
+# 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
+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.

agentopolis-0.6.0/agentopolis/cli.py

@@ -0,0 +1,72 @@
+"""agentopolis — run from any git repo to watch agents build its city."""
+import argparse
+import subprocess
+import threading
+import time
+import webbrowser
+
+import uvicorn
+
+from . import hooks, nation, server
+
+
+def free_port(port: int) -> None:
+    holders = lambda: subprocess.run(["lsof", "-ti", f":{port}"],
+                                     capture_output=True, text=True).stdout.split()
+    pids = holders()
+    if not pids:
+        return
+    print(f"freeing port {port} (pid {', '.join(pids)})")
+    for sig in ("-TERM", "-KILL"):
+        subprocess.run(["kill", sig, *pids], capture_output=True)
+        for _ in range(20):
+            if not holders():
+                return
+            time.sleep(.1)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="agentopolis",
+        description="Habbo-style visualization of Claude Code agents building your repo as a city.")
+    parser.add_argument("command", nargs="?", default="serve", choices=["serve", "attach", "detach"],
+                        help="serve the city (default), or attach/detach Claude Code hooks")
+    parser.add_argument("--repo", default=".", help="git repo to map as the city (default: cwd)")
+    parser.add_argument("--zone", help="zoning manifest (default: <repo>/.agentopolis.json, else auto-zoned)")
+    parser.add_argument("--root", help="map every git repo under this dir as a nation of cities")
+    parser.add_argument("--port", type=int, default=4242)
+    parser.add_argument("--no-open", action="store_true", help="don't open the city in a browser")
+    args = parser.parse_args()
+
+    if args.command == "attach":
+        hooks.attach(args.port)
+    elif args.command == "detach":
+        hooks.detach()
+    else:
+        free_port(args.port)
+        server.configure(args.repo, args.zone)
+        root = args.root or (nation.is_mother(args.repo) and args.repo)   # a mother repo is a nation
+        if root:
+            server.configure_nation(root, None)
+        where = f"nation: {root}" if root else f"repo: {args.repo}"
+        url = f"http://localhost:{args.port}"
+        print(f"Agentopolis {'Nation' if root else 'City'} on {url} ({where})")
+        if not hooks.is_attached():
+            print("tip: run `agentopolis attach` so Claude Code sessions report to the city")
+        if not args.no_open:
+            opener = threading.Timer(1, lambda: webbrowser.open(url))
+            opener.daemon = True
+            opener.start()
+        # SSE streams watch runner.should_exit so open browsers don't block Ctrl+C;
+        # the graceful-shutdown timeout is the backstop for any other slow request
+        runner = uvicorn.Server(uvicorn.Config(server.app, port=args.port,
+                                               log_level="warning", timeout_graceful_shutdown=2))
+        server.runner = runner
+        try:
+            runner.run()
+        except KeyboardInterrupt:           # uvicorn re-raises the Ctrl+C after shutdown
+            pass
+
+
+if __name__ == "__main__":
+    main()

agentopolis-0.6.0/agentopolis/hooks.py

@@ -0,0 +1,69 @@
+"""Attach/detach the city to Claude Code via ~/.claude/settings.json hooks.
+
+Hooks fire-and-forget to localhost with a 1s timeout, so Claude Code is
+never blocked when the city isn't running.
+"""
+import json
+from pathlib import Path
+
+SETTINGS = Path.home() / ".claude" / "settings.json"
+BACKUP = SETTINGS.with_suffix(".json.agentopolis.bak")
+EVENTS = [
+    "SessionStart",
+    "UserPromptSubmit",
+    "Notification",
+    "PreToolUse",
+    "PostToolUse",
+    "Stop",
+    "SubagentStop",
+    "SessionEnd",
+]
+def command(port: int) -> str:
+    return (
+        f"curl -sf -m 1 -X POST http://localhost:{port}/hook "
+        "-H 'Content-Type: application/json' --data-binary @- "
+        ">/dev/null 2>&1 || true"
+    )
+
+
+def has_hotel_hook(entries: list) -> bool:
+    return any(
+        "/hook" in hook.get("command", "") and "curl" in hook.get("command", "")
+        for entry in entries
+        for hook in entry.get("hooks", [])
+    )
+
+
+def is_attached() -> bool:
+    if not SETTINGS.exists():
+        return False
+    hooks = json.loads(SETTINGS.read_text()).get("hooks", {})
+    return any(has_hotel_hook(entries) for entries in hooks.values())
+
+
+def attach(port: int = 4242) -> None:
+    settings = json.loads(SETTINGS.read_text()) if SETTINGS.exists() else {}
+    BACKUP.write_text(json.dumps(settings, indent=2))
+    hooks = settings.setdefault("hooks", {})
+    added = 0
+    for event in EVENTS:
+        entries = hooks.setdefault(event, [])
+        if not has_hotel_hook(entries):
+            entries.append({"matcher": "", "hooks": [{"type": "command", "command": command(port)}]})
+            added += 1
+    SETTINGS.write_text(json.dumps(settings, indent=2) + "\n")
+    print(f"attached {added} events ({SETTINGS}, backup at {BACKUP.name})")
+    print("new Claude Code sessions will now report to the city")
+
+
+def detach() -> None:
+    if not SETTINGS.exists():
+        return
+    settings = json.loads(SETTINGS.read_text())
+    hooks = settings.get("hooks", {})
+    for event in list(hooks):
+        hooks[event] = [e for e in hooks[event] if not has_hotel_hook([e])]
+        if not hooks[event]:
+            del hooks[event]
+    SETTINGS.write_text(json.dumps(settings, indent=2) + "\n")
+    print("detached — agentopolis hooks removed")

agentopolis-0.6.0/agentopolis/nation.py

@@ -0,0 +1,129 @@
+"""Nation view: many repos as one map, grouped into states.
+
+discover_repos() finds git repos one level under a root. summarize() reads
+cheap git stats per repo (no file-content reads, so it scales to dozens).
+load_nation() folds in an optional .agentopolis-nation.json that names the
+states (repo clusters).
+"""
+import json
+import time
+from collections import Counter
+from pathlib import Path
+
+from .seed import git, tracked
+
+PALETTE = ["#16a085", "#5b8dd9", "#c0395b", "#d4a953", "#8e5d9f",
+           "#b5651d", "#2980b9", "#4a6b5c", "#c9b78a", "#5c6b73"]
+
+FAMILY_NAMES = {
+    "backend":  "Logic Highlands",
+    "frontend": "Interface Coast",
+    "infra":    "Iron Province",
+    "data":     "The Mines",
+    "docs":     "The Scriptorium",
+    "neutral":  "The Hinterlands",
+}
+FAMILY_COLOR = {
+    "backend":  "#2980b9",
+    "frontend": "#27ae60",
+    "infra":    "#7f8c8d",
+    "data":     "#d4a953",
+    "docs":     "#c9b78a",
+    "neutral":  "#7d6b8a",
+}
+
+# extension → archetype family; picks the family with the most tracked files (assets ignored)
+FAMILY_EXT = {
+    "backend": {"py", "go", "rb", "rs", "java", "php", "cs", "kt", "scala", "ex", "clj"},
+    "frontend": {"js", "ts", "jsx", "tsx", "vue", "svelte"},
+    "docs": {"md", "rst", "txt", "adoc"},
+    "infra": {"tf", "yml", "yaml", "sh", "toml", "dockerfile"},
+    "data": {"sql", "csv", "parquet", "ipynb"},
+}
+
+
+def family_of(exts: Counter) -> str:
+    best, score = "neutral", 0
+    for fam, group in FAMILY_EXT.items():
+        n = sum(exts[e] for e in group)
+        if n > score:
+            best, score = fam, n
+    return best
+
+
+def discover_repos(root: str) -> list[str]:
+    out = []
+    for entry in sorted(Path(root).iterdir()):
+        if entry.is_symlink() or not entry.is_dir():
+            continue
+        if (entry / ".git").exists():
+            out.append(entry.name)
+    return out
+
+
+def is_mother(repo: str) -> bool:
+    """A git repo that nests ≥2 git repos of its own — a metropolis, not a city."""
+    return (Path(repo) / ".git").exists() and len(discover_repos(repo)) >= 2
+
+
+def summarize(repo: str, exclude: set | None = None) -> dict:
+    files = tracked(repo, exclude)
+    last = git(repo, "log", "-1", "--format=%ct").strip()
+    commits = git(repo, "rev-list", "--count", "HEAD").strip()
+    exts = Counter(Path(f).suffix.lstrip(".").lower() for f in files if "." in f)
+    age = round((time.time() - int(last)) / 86400) if last else 9999
+    low = [f.lower() for f in files]
+    return {"files": len(files), "commits": int(commits or 0), "age_days": age,
+            "lang": (exts.most_common(1) or [("", 0)])[0][0],
+            "family": family_of(exts),
+            "hasInfra": any(f.endswith(".tf") or f.rsplit("/", 1)[-1].startswith("dockerfile")
+                            or ".github/workflows/" in f for f in low),
+            "hasFrontend": any(f.endswith((".html", ".css", ".jsx", ".tsx", ".scss", ".vue")) for f in low),
+            "hasDocs": any(f.endswith(".md") for f in low)}
+
+
+CAPITAL = "."                                  # capital city id == the mother repo's own path
+
+
+def mother_nation(root: str) -> dict:
+    """A mother repo as a one-state metropolis: a capital (its own glue) + each subrepo a city."""
+    subs = discover_repos(root)
+    name = Path(root).resolve().name
+    cities = [{"repo": CAPITAL, "name": "⊙ capital", "state": name, **summarize(root, set(subs))}]
+    cities += [{"repo": r, "state": name, **summarize(str(Path(root) / r))} for r in subs]
+    states = [{"id": name, "name": name, "color": PALETTE[0], "repos": [CAPITAL, *subs]}]
+    return {"root": name, "states": states, "cities": cities}
+
+
+def load_nation(root: str, manifest_path: str | None) -> dict:
+    path = Path(manifest_path) if manifest_path else Path(root) / ".agentopolis-nation.json"
+    if not path.exists() and is_mother(root):   # an explicit manifest wins; a bare mother is a metropolis
+        return mother_nation(root)
+    repos = discover_repos(root)
+    man = json.loads(path.read_text()) if path.exists() else {}
+
+    summaries = {r: summarize(str(Path(root) / r)) for r in repos}
+
+    state_of, states = {}, []
+    for i, st in enumerate(man.get("states", [])):
+        members = [r for r in st["repos"] if r in repos]
+        if not members:
+            continue
+        for r in members:
+            state_of[r] = st["id"]
+        states.append({"id": st["id"], "name": st.get("name", st["id"]),
+                       "color": st.get("color", PALETTE[i % len(PALETTE)]), "repos": members})
+
+    by_family: dict[str, list[str]] = {}
+    for r in repos:
+        if r not in state_of:
+            by_family.setdefault(summaries[r]["family"], []).append(r)
+    for fam, members in sorted(by_family.items()):
+        sid = f"auto_{fam}"
+        for r in members:
+            state_of[r] = sid
+        states.append({"id": sid, "name": FAMILY_NAMES[fam],
+                       "color": FAMILY_COLOR[fam], "repos": members})
+
+    cities = [{"repo": r, "state": state_of[r], **summaries[r]} for r in repos]
+    return {"root": Path(root).resolve().name, "states": states, "cities": cities}