🏰 Age of Agents

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

Every Claude Code or Codex 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.

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

✨ What is this?

Age of Agents (npm package age-of-agents) 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, or OpenCode 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.

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

Run it instantly, no install:

npx age-of-agents          # watches ~/.claude, ~/.codex & ~/.opencode sessions, prints the URL
npx age-of-agents --demo   # calm demo mode (fake sessions)
npx age-of-agents --open   # also open the browser

Or install globally (commands age-of-agents and the shorter aoa):

npm i -g age-of-agents
aoa --open

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/agentsmill/age-of-agents
cd age-of-agents && npm install
npm run demo     # server (demo) + client (Vite) → http://localhost:5173
npm run dev      # visualize your real sessions

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

🎨 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 age-of-agents CLI:

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 Age of Agents or sent anywhere.
• Installing the optional Claude Code hooks modifies ~/.claude/settings.json (a fast event channel). Demo mode touches nothing of yours.

🎭 Assets

All pixel-art assets in packages/client/public/assets/ were generated by the author with PixelLab and are the author's 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. Art assets generated with PixelLab, redistributed under MIT per PixelLab's Terms of Service.

🙏 Acknowledgements

Inspired by AgentCraft. Built with PixiJS, React, Fastify and PixelLab.