🏰 Agent Hollow

Watch your AI coding sessions grow a peaceful pixel-art realm.

Every Claude Code, Codex, OpenCode or Koda session becomes a settler walking out of the keep. The tool it runs decides which workshop it visits, subagents become workers, and tokens fill the storehouse — a calm, Age-of-Empires-style kingdom of your work. No combat, just a quiet realm you can watch at a glance.

A friendly fork of Age of Agents by Mateusz Pawelczuk — all credit for the original design, code and pixel art goes to him.

▶ Live site · Quick start · How it works · Architecture

✨ What is this?

Agent Hollow (npm package agent-hollow) runs as a small local web app alongside your normal CLI workflow. It watches your agent session transcripts and renders them as a calm, real-time strategy realm:

• Each session → a settler. Start a Claude Code, Codex, OpenCode or Koda session and a settler walks out of the keep, carrying your prompt as its task.
• Tools → workshops. The settler heads to the building that matches the work — the forge for code edits, the mage tower for web research, the mine for the terminal.
• Subagents → workers. When a session spawns subagents (e.g. the Task tool), they appear as little workers around their settler.
• Tokens → harvest. Tokens read and produced fill the storehouse. Settlers ponder while thinking, rest when waiting, and stroll home when the day's work is done.
• Two worlds. Switch between a fantasy (top-down) and a sci-fi (isometric) realm on the fly.
• Day & night. The realm follows your local clock — dawn glow, amber dusk, and moonlit nights where every building's windows light up from the inside, fireflies drift through the gardens, and the occasional shooting star crosses the sky. Toggle it with the 🌗 button; preview any time of day with ?hour=22 in the URL.
• Many projects → cities. Each project becomes a city you can switch between; open one for an optional peek at Beads tasks and a Graphify code map (see Project intel).

A glanceable, second-monitor view of what your agents are quietly up to.

🖼️ Gallery

| Fantasy | Sci-Fi | | --- | --- | | | |

Session detail — click a settler to inspect its task, token economy and live activity:

🚀 Quick start

Install — npm i -g. Install it globally for the short hollow command; update with npm update -g agent-hollow when new versions ship:

npm i -g agent-hollow
hollow            # watches ~/.claude, ~/.codex, ~/.opencode & ~/.koda sessions (+ Claude in local Docker), prints the URL
hollow --demo     # calm demo mode (fake sessions)
hollow --open     # also open the browser

The server binds to 127.0.0.1 only and never writes your transcripts anywhere — it just reads them locally and broadcasts game state over a local WebSocket. See Privacy.

From source

git clone https://github.com/acaylor/agent-hollow
cd agent-hollow && npm install
npm run demo     # server (demo) + client (Vite) → http://localhost:5173
npm run dev      # visualize your real sessions

For focused local testing you can limit which session sources are watched:

HOLLOW_SOURCES=codex npm run dev
HOLLOW_SOURCES=claude,codex npm run dev
HOLLOW_CODEX_LOOKBACK_DAYS=3 npm run dev

HOLLOW_SOURCES accepts claude, codex, opencode, and koda. Codex watches recent date folders by default instead of the entire historical ~/.codex/sessions tree.

Local LLMs (Ollama, llama.cpp, vLLM, oMLX)

Local engines don't write transcripts, so Agent Hollow captures them through a small logging proxy. Two ways in:

Ollama (terminal):

hollow local llama3        # wraps `ollama run llama3` and logs it as a hero

The session shows up in the realm; the model appears in the Models tab, where you can assign a sprite (context window is read automatically from Ollama).

Any OpenAI-compatible backend (llama.cpp / vLLM / oMLX / coding agents):

LLM_BASE_URL=http://localhost:8000/v1 hollow local-proxy   # prints a proxy URL

Point your client's base URL at the printed proxy URL. Default backend base URLs:

| Backend | Default base URL | |-----------|---------------------------------| | Ollama | http://localhost:11434/v1 | | llama.cpp | http://localhost:8080/v1 | | vLLM | http://localhost:8000/v1 | | oMLX | http://localhost:10240/v1 |

Overrides: LLM_BASE_URL, LLM_MODEL, LLM_API_KEY.

🧭 How it works

agent session transcript ──▶ server (watcher + state machine) ──▶ WebSocket ──▶ client (PixiJS realm + HUD)

• The server tails JSONL transcripts, turns each line into a Fact, and runs a small per-session state machine (thinking / working / resting / idle / returning).
• It broadcasts a HeroSnapshot for every session over a WebSocket. The snapshot carries what the session is doing (currentTool, recent actions, tokens) — never raw coordinates.
• The client decides where each settler goes and renders the pixel-art realm, the HUD, the minimap and the side panel.
• Running agents in Docker? Local containers are auto-discovered (zero-config) and their Claude sessions read straight out of the container via docker exec — no image changes, no host bind-mounts required. Containerized settlers carry a 🐳 badge in the side panel. Disable with HOLLOW_DOCKER=0.

🏛️ Project intel (optional)

Run several projects at once and each becomes its own city in the top bar — switch between them, or pick All to see every settler together. A city shows how many agents are active and which kind (Claude, Codex, OpenCode, Koda).

Select a city to open the Architect's Hall, a side panel that surfaces two optional, third-party signals about that project — read-only and entirely opt-in:

• 📜 Beads — open tasks from Beads, an AI-native issue tracker that lives in your repo. Agent Hollow reads .beads/issues.jsonl (falling back to bd list --json). Turn it on in a project with bd init.
• 🌳 Graph — a code knowledge graph: symbol, edge and community counts plus the most-connected "god-nodes". Agent Hollow reads graphify-out/graph.json. Generate it with the bundled, dependency-free generator — run npm run graphify in a project (or node scripts/graphify.mjs <dir>) to scan relative imports and write graphify-out/graph.json. You can also use the external Graphify tool; the schema is the same.

Neither tool is bundled or required. If a project has no .beads/ or graphify-out/, the panel just reads "not initialized"; it polls every few seconds, so intel appears as soon as the files do.

🎨 Themes

Two full art sets, switchable from the top bar:

• Fantasy — top-down: keep, mage tower, library, guild, market, mine, orchard & ponds.
• Sci-Fi — isometric: command center, hangars, drone factory, ore refinery, research lab on a calm Martian colony.

🧱 Architecture

A small npm-workspaces monorepo, published as the single agent-hollow CLI:

| Package | Stack | Responsibility | | --- | --- | --- | | packages/shared | TypeScript | WebSocket protocol types (GameEvent, snapshots) | | packages/server | Node + Fastify + ws + SQLite | transcript watcher, state machine, hooks endpoint, demo generator, CLI | | packages/client | Vite + React 19 + PixiJS v8 | the game realm, HUD, minimap, side panel |

npm test      # unit tests (server + client)
npm run build # production client + bundled CLI (dist/cli.js)

🔒 Privacy

• The server listens on 127.0.0.1 only — nothing is exposed to your network.
• Transcripts are read locally and read-only; their contents are never written to disk by Agent Hollow or sent anywhere.
• Installing the optional Claude Code hooks modifies ~/.claude/settings.json (a fast event channel). Demo mode touches nothing of yours.
• Optional interactive mode (off by default). You can let the panel answer Claude Code permission prompts and plan approvals via the local hooks. It stays 127.0.0.1-only; with the mode off, Agent Hollow remains a passive read-only observer. When on, an unanswered prompt (timeout or app closed) always falls back to the terminal — the app never auto-allows. "Always allow" rules live in ~/.agent-hollow/permission-policy.json; the app never edits the permission rules in ~/.claude/settings.json.
• Optional: launch agents from the app (BETA — setup guide). With the Claude Agent SDK installed (npm i @anthropic-ai/claude-agent-sdk), a 🚀 Launch agent button lets you start a Claude Code session from the panel — pick a folder, type a prompt, choose a permission mode. These app-owned sessions are real Claude Code runs (they use your account and tokens) and you answer their permission prompts, plan approvals and multiple-choice questions (a centered "agent question" modal) directly in the panel. The SDK is an optional dependency; without it the button is hidden and nothing changes.
  • Auth for launching: the Agent SDK authenticates from environment variables only — it does not read your interactive Claude Code login. To use your subscription, generate a long-lived token once with claude setup-token, then start the app from a shell where CLAUDE_CODE_OAUTH_TOKEN is set (and ANTHROPIC_API_KEY is unset, or it takes precedence). Without it, launches fail with 401 Invalid authentication credentials; the launch dialog warns when no auth is present.

🛡️ Security

The server binds to 127.0.0.1 only and is built for local use. It defends against the realistic threat — a malicious web page in your browser (a "drive-by" that scripts localhost) — with two layers:

• Origin allowlist. WebSocket and state-changing HTTP requests from a non-local origin are rejected (403). A cross-origin page always sends an Origin header, so it cannot connect or post.
• Session token. A per-machine token in ~/.agent-hollow/session-token (0600) is required for the WebSocket handshake and for sensitive endpoints (launch/stop/message, hook install/uninstall, config writes, /fs/list). The app fetches it from /session-token, which is only served to allowlisted origins. Installed hooks and local tools keep working with no setup — the token is auto-created on first run.

/fs/list (the folder picker) is confined to your home directory. The server refuses to bind to a non-loopback host unless you explicitly set HOLLOW_ALLOW_REMOTE=1.

Honest boundaries: loopback is not isolated per user, so this does not fully protect against another user on a shared machine, and a process running as you can read the token file. Those are out of scope for a local-first tool.

🎭 Assets

All pixel-art assets in packages/client/public/assets/ were generated by Mateusz Pawelczuk, the original Age of Agents author, with PixelLab and are his own work — released here under the same MIT license as the code. Without any assets the game still runs on procedurally generated placeholders.

assets-manifest.json + scripts/download-assets.mjs are an optional helper for swapping in alternative third-party packs locally; those packs are never committed (some forbid redistribution) and are not needed to run the game.

🤝 Contributing

Issues and PRs are welcome. To get going: npm install, then npm run demo to see the realm, and npm test before opening a PR.

📜 License

MIT © Mateusz Pawelczuk (original Age of Agents) and AJ Caylor (Agent Hollow fork). Art assets generated with PixelLab, redistributed under MIT per PixelLab's Terms of Service.

🙏 Acknowledgements

Agent Hollow is a fork of Age of Agents, created by Mateusz Pawelczuk — the realm, the architecture and every sprite are his work. The original was inspired by AgentCraft. Built with PixiJS, React, Fastify and PixelLab.