botapest 0.2.0__tar.gz

botapest-0.2.0/.gitignore

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

botapest-0.2.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.

botapest-0.2.0/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.4
+Name: botapest
+Version: 0.2.0
+Summary: Botapest City — Habbo-style visualization of Claude Code agents building your repo as a city
+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
+
+# Botapest City
+
+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 /path/to/botapest   # installs the `botapest` CLI globally
+botapest attach                     # one-time: fire-and-forget hooks into ~/.claude/settings.json
+
+cd ~/code/any-repo
+botapest                            # 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. `botapest detach` removes the hooks (a backup
+of settings.json is written on attach). Flags: `--repo`, `--port`, `--zone`.
+
+**Zoning:** if the repo has a `.botapest.json` manifest it defines the city's
+components, layers, and clouds (see `city/maisight.json` for a full example);
+otherwise botapest 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.

botapest-0.2.0/README.md

@@ -0,0 +1,57 @@
+# Botapest City
+
+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 /path/to/botapest   # installs the `botapest` CLI globally
+botapest attach                     # one-time: fire-and-forget hooks into ~/.claude/settings.json
+
+cd ~/code/any-repo
+botapest                            # 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. `botapest detach` removes the hooks (a backup
+of settings.json is written on attach). Flags: `--repo`, `--port`, `--zone`.
+
+**Zoning:** if the repo has a `.botapest.json` manifest it defines the city's
+components, layers, and clouds (see `city/maisight.json` for a full example);
+otherwise botapest 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.

botapest-0.2.0/botapest/cli.py

@@ -0,0 +1,49 @@
+"""botapest — run from any git repo to watch agents build its city."""
+import argparse
+import subprocess
+import time
+
+import uvicorn
+
+from . import hooks, 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="botapest",
+        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>/.botapest.json, else auto-zoned)")
+    parser.add_argument("--port", type=int, default=4242)
+    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)
+        print(f"Botapest City on http://localhost:{args.port} (repo: {args.repo})")
+        uvicorn.run(server.app, port=args.port, log_level="warning")
+
+
+if __name__ == "__main__":
+    main()

botapest-0.2.0/botapest/hooks.py

@@ -0,0 +1,62 @@
+"""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.botapest.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 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 — botapest hooks removed")

botapest-0.2.0/botapest/seed.py

@@ -0,0 +1,68 @@
+"""Build a city snapshot from a git repo + zoning manifest.
+
+Per building: loc (mass), commits + age (attention), centrality (how many
+other components it has co-committed with). A component may set "group": N
+to aggregate files into one building per N-segment path prefix.
+"""
+import subprocess
+import time
+from fnmatch import fnmatch
+from pathlib import Path
+
+
+def git(repo: str, *args: str) -> str:
+    return subprocess.run(["git", "-C", repo, *args], capture_output=True, text=True).stdout
+
+
+def component_of(path: str, components: list) -> str | None:
+    for c in components:
+        if any(fnmatch(path, g) for g in c["globs"]):
+            return c["id"]
+    return None
+
+
+def count_lines(path: Path) -> int:
+    try:
+        return sum(1 for _ in open(path, errors="ignore"))
+    except OSError:
+        return 0
+
+
+def seed(repo: str, zone: dict) -> dict:
+    comp = {f: component_of(f, zone["components"]) for f in git(repo, "ls-files").splitlines()}
+    files = [f for f, c in comp.items() if c]
+
+    commits = dict.fromkeys(files, 0)
+    last = dict.fromkeys(files, 0)
+    cocomp = {f: set() for f in files}
+    timestamp = 0
+    touched: list[str] = []
+    for line in git(repo, "log", "--name-only", "--pretty=%ct").splitlines() + [""]:
+        if line.isdigit() or not line:                  # commit boundary: flush previous
+            comps = {comp[f] for f in touched}
+            for f in touched:
+                commits[f] += 1
+                last[f] = max(last[f], timestamp)
+                if len(touched) <= 15:                  # mega-commits aren't coupling signal
+                    cocomp[f] |= comps - {comp[f]}
+            touched = []
+            if line.isdigit():
+                timestamp = int(line)
+        elif line in commits:
+            touched.append(line)
+
+    group = {c["id"]: c.get("group") for c in zone["components"]}
+    buildings: dict[str, dict] = {}
+    now = time.time()
+    for f in sorted(files):
+        depth = group[comp[f]]
+        key = "/".join(f.split("/")[:depth]) if depth else f
+        b = buildings.setdefault(key, {"path": key, "component": comp[f], "loc": 0,
+                                       "commits": 0, "centrality": 0, "age_days": 9999, "files": 0})
+        b["loc"] += count_lines(Path(repo, f))
+        b["commits"] += commits[f]
+        b["centrality"] = max(b["centrality"], len(cocomp[f]))
+        if last[f]:
+            b["age_days"] = min(b["age_days"], round((now - last[f]) / 86400))
+        b["files"] += 1
+    return {"zone": zone, "buildings": list(buildings.values())}

botapest-0.2.0/botapest/server.py

@@ -0,0 +1,112 @@
+"""Botapest City — event relay + city seeding.
+
+Receives Claude Code hook payloads on POST /hook, normalizes them, and
+broadcasts to browsers over SSE at GET /events. GET /city-data.json
+seeds the configured repo's city on demand (cached per git HEAD).
+"""
+import asyncio
+import json
+import os
+from collections import deque
+from pathlib import Path
+
+from fastapi import FastAPI, Request
+from fastapi.responses import StreamingResponse
+from fastapi.staticfiles import StaticFiles
+
+from .seed import git, seed
+from .zone import load_zone
+
+app = FastAPI()
+subscribers: set[asyncio.Queue] = set()
+history: deque = deque(maxlen=100)
+city = {"repo": ".", "zone_path": None, "head": None, "data": None}
+
+
+def configure(repo: str, zone_path: str | None) -> None:
+    city.update(repo=repo, zone_path=zone_path, head=None, data=None)
+
+MAX_DETAIL = 80
+
+
+def normalize(raw: dict) -> dict:
+    event = {
+        "event": raw.get("hook_event_name", "unknown"),
+        "session": (raw.get("session_id") or "")[:8],
+    }
+    if raw.get("agent_id"):                    # event fired inside a subagent
+        event["agent_id"] = raw["agent_id"][:8]
+        event["agent_type"] = raw.get("agent_type", "agent")
+    tool = raw.get("tool_name")
+    if tool:
+        event["tool"] = tool
+        tool_input = raw.get("tool_input") or {}
+        detail = (
+            tool_input.get("file_path")
+            or tool_input.get("command")
+            or tool_input.get("pattern")
+            or tool_input.get("query")
+            or tool_input.get("url")
+            or tool_input.get("description")
+            or ""
+        )
+        if detail.startswith("/"):
+            detail = os.path.basename(detail)
+        event["detail"] = str(detail)[:MAX_DETAIL]
+        file_path, cwd = tool_input.get("file_path") or "", raw.get("cwd") or ""
+        if cwd and file_path.startswith(cwd + "/"):
+            event["path"] = file_path[len(cwd) + 1:]
+        if tool == "Bash" and "git commit" in str(tool_input.get("command") or ""):
+            event["commit"] = True
+        if tool in ("Task", "Agent"):
+            event["agent_type"] = tool_input.get("subagent_type", "agent")
+            event["agent_name"] = str(tool_input.get("description", "agent"))[:40]
+    if event["event"] == "UserPromptSubmit":
+        event["detail"] = str(raw.get("prompt") or "")[:MAX_DETAIL]
+    if event["event"] == "Notification":
+        event["detail"] = str(raw.get("message") or "")[:MAX_DETAIL]
+    return event
+
+
+@app.post("/hook")
+async def hook(request: Request) -> dict:
+    raw = await request.json()
+    event = normalize(raw)
+    history.append(event)
+    for queue in subscribers:
+        queue.put_nowait(event)
+    return {"ok": True}
+
+
+@app.get("/city-data.json")
+def city_data() -> dict:
+    head = git(city["repo"], "rev-parse", "HEAD").strip()
+    if city["head"] != head:
+        city["data"] = seed(city["repo"], load_zone(city["repo"], city["zone_path"]))
+        city["head"] = head
+    return city["data"]
+
+
+@app.get("/events")
+async def events() -> StreamingResponse:
+    queue: asyncio.Queue = asyncio.Queue()
+    for event in history:                       # replay so late joiners see state
+        queue.put_nowait(event)
+    subscribers.add(queue)
+
+    async def stream():
+        try:
+            yield "retry: 2000\n\n"
+            while True:
+                try:
+                    event = await asyncio.wait_for(queue.get(), timeout=15)
+                    yield f"data: {json.dumps(event)}\n\n"
+                except asyncio.TimeoutError:
+                    yield ": ping\n\n"
+        finally:
+            subscribers.discard(queue)
+
+    return StreamingResponse(stream(), media_type="text/event-stream")
+
+
+app.mount("/", StaticFiles(directory=Path(__file__).parent / "static", html=True), name="static")

botapest-0.2.0/botapest/static/city-live.js

@@ -0,0 +1,34 @@
+// City backdrop on the main page: fixed view, grows from live events via cityHandle().
+const cityCanvas = document.getElementById('citybg');
+const cityCtx = cityCanvas.getContext('2d');
+const cityCam = { ox: 0, oy: 0, s: 1 };
+let cityState = null;
+
+fetch('city-data.json').then(r => r.json()).then(data => {
+  cityState = City.layout(data);
+  City.fit(cityCam, cityCanvas, cityState, 115, 30, 1.18);
+  requestAnimationFrame(function frame(t) {
+    cityCtx.clearRect(0, 0, cityCanvas.width, cityCanvas.height);
+    City.draw(cityCtx, cityCam, cityState, t);
+    requestAnimationFrame(frame);
+  });
+});
+
+function cityHandle(e) {
+  if (cityState) City.applyEvent(cityState, e);
+}
+
+cityCanvas.addEventListener('mousemove', m => {
+  const r = cityCanvas.getBoundingClientRect();
+  const hit = cityState && City.pick(cityState,
+    (m.clientX - r.left) * (cityCanvas.width / r.width),
+    (m.clientY - r.top) * (cityCanvas.height / r.height));
+  const tip = document.getElementById('tooltip');
+  if (hit) {
+    tip.textContent = `${hit.path} · ${hit.floors} fl · ${hit.commits} commits`
+      + `${hit.scaffold ? ' · under construction' : ''}`;
+    tip.style.left = `${m.clientX + 14}px`;
+    tip.style.top = `${m.clientY + 14}px`;
+    tip.style.display = 'block';
+  } else tip.style.display = 'none';
+});