agent-city-ai
Visualize Claude Code and omp AI coding agents as gangs in a 3D open-world city: a free, local agent dashboard with live cost tracking.
Package details
Install agent-city-ai from npm and Pi will load the resources declared by the package manifest.
$ pi install npm:agent-city-ai- Package
agent-city-ai- Version
0.1.5- Published
- Nov 22, 2026
- Downloads
- 301/mo · 301/wk
- Author
- talmogendorff
- License
- MIT
- Types
- extension
- Size
- 24.7 MB
- Dependencies
- 0 dependencies · 0 peers
Pi manifest JSON
{
"image": "https://raw.githubusercontent.com/Lulu-The-Narwhal/agent-city/main/docs/media/demo-npm.gif",
"extensions": [
"./dist/bridges/omp/package/agent-city.js"
]
}Security note
Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.
README
Agent City turns your AI coding agents (Claude Code, omp) into gangs in a 3D open-world city you can drive around — a local, free, open-source agent dashboard and visualizer.
Run npx agent-city-ai and every coding session becomes a gang in a real Miami Beach, with live per-session cost, on 127.0.0.1 only: no API keys, no telemetry.
Visualize Claude Code sessions
Every omp or Claude Code conversation is a gang named after its session; its main agent is the Gang Lord and its subagents are the members. Watch them work on the streets of South Beach, ask them what they are doing, and message them from an in-game phone.

▶ Play the demo city in your browser — no install; run npx agent-city-ai to see your own agents.
If Agent City made you smile, a ⭐ helps others find it.
AI agent dashboard as a game
Everything an agent dashboard shows is on the street: who is working, which tool and file, what failed, what it costs. Walk up to a Gang Lord and press E to talk, press P for the phone (ask, steer, follow up, abort), drive with W A S D, and press H for help.
Monitor AI coding agent cost
Live real spend of every omp session, per gang, per turn and for today, in the Ledger (L). It comes from omp's own usage reports, is read-only and is kept apart from in-game cash. Claude Code hooks do not carry cost, so Claude Code gangs show activity but no spend.
Run
npx agent-city-ai
This starts the agent-city daemon and the omp runner on your machine, serves the city on
http://127.0.0.1:4646/ and opens it in your browser. Ctrl+C stops everything.
Requirements: Node.js 20 or newer (or Bun). A browser with WebGL 2.
| Option | Effect |
|---|---|
--port <n> |
daemon port (default 4646, or $AGENT_CITY_PORT) |
--no-open |
do not open the browser |
-y, --yes |
answer yes to install/uninstall prompts |
Connect your agents
The city is empty until a runtime reports to it. Both commands show exactly what they will change and ask before writing; both back up any file they replace.
| Command | What it changes | Undo |
|---|---|---|
npx agent-city-ai install-omp |
copies one file, ~/.omp/agent/extensions/agent-city.js, which omp loads into every session (new sessions join; running ones after a restart); the omp package is the alternative |
npx agent-city-ai uninstall-omp deletes it (backup kept) |
npx agent-city-ai install-claude |
adds agent-city hooks to ~/.claude/settings.json (or $CLAUDE_CONFIG_DIR/settings.json); your other settings and hooks are kept; backup settings.json.<time>.agent-city.bak next to it |
npx agent-city-ai uninstall-claude removes only agent-city's entries (backup kept) |
npx agent-city-ai doctor |
nothing: checks Node, the port, the token, omp and Claude Code, and what is installed | — |
omp sessions can be messaged and aborted from the city's phone, and gangs can be recruited from it (the
runner starts omp for you). Claude Code sessions are watch-only. Game actions (driving, weapons, police)
never touch your agents; only the phone does, and only when you click.
If you start the city with --port, run omp with the same AGENT_CITY_PORT and pass the same --port to
install-claude.
Install as a Claude Code plugin
Instead of install-claude, you can connect Claude Code through its plugin system. In a Claude Code session:
/plugin marketplace add Lulu-The-Narwhal/agent-city
/plugin install agent-city@agent-city
From a shell, the same is claude plugin marketplace add Lulu-The-Narwhal/agent-city then
claude plugin install agent-city@agent-city. New sessions report to the city; running ones after a restart.
- The plugin registers the same hook events as
install-claudeand sends them to the city on127.0.0.1($AGENT_CITY_PORT, default 4646) with the token derived from~/.agent-city/token. It writes nothing tosettings.json, prints nothing on stdout, and never blocks or steers Claude. Claude Code sessions stay watch-only, with no cost data. - It needs
node(20 or newer) onPATHand the city started once withnpx agent-city-ai, which creates the token. If you run the city on another port, start Claude Code with the sameAGENT_CITY_PORT. - Use the plugin or
install-claude, not both. Whileinstall-claude's hooks are in your user settings the plugin stays silent, so no event is counted twice; runnpx agent-city-ai uninstall-claudeto switch to the plugin.doctorchecks onlyinstall-claude's hooks, so with the plugin itsclaude hooksline stayswarn. - Remove it with
/plugin uninstall agent-city@agent-city.
What the plugin runs and accesses
- Runs: one Node script,
plugins/agent-city/hooks/forward.mjs, withnodeon each hook event (3 s timeout). It has no dependencies and no install or build step. - Reads: the hook event on stdin,
~/.agent-city/token, and your Claude settings ($CLAUDE_CONFIG_DIR/settings.json, default~/.claude/settings.json), only to see whetherinstall-claude's hooks are already there. - Sends: one POST per event to
http://127.0.0.1:$AGENT_CITY_PORT/hooks/claude-code(default port 4646), and nothing to any other host. - Never: writes a file, prints to stdout, blocks or steers Claude, or exits non-zero. When it skips an event (city stopped, no token) it writes one line to stderr.
Install as an omp package
Instead of install-omp, you can install Agent City with omp's package manager:
omp plugin install agent-city-ai
- It installs this npm package and loads the same omp extension that
install-ompcopies, so sessions report the same events and live cost, and the phone works the same. New sessions join; running ones after a restart. - The package is tagged
pi-package, so the pi package gallery (pi.dev/packages) can list it. It is built and tested for omp; plain pi is not tested. - Use the package or
install-omp, not both. While~/.omp/agent/extensions/agent-city.jsexists the package stands by, so no session is counted twice; runnpx agent-city-ai uninstall-ompto switch to the package.doctorshows which one is active. - Remove it with
omp plugin uninstall agent-city-ai.
Install with your AI agent
Paste this into Claude Code, omp, Cursor or Codex:
Install Agent City for me: follow https://github.com/Lulu-The-Narwhal/agent-city/blob/main/docs/INSTALL-FOR-AGENTS.md
The agent install guide has
the agent check prerequisites, run doctor, show you each install prompt before anything is written, start the
city and verify it.
Use from any agent (MCP)
npx agent-city-ai mcp is a read-only MCP server on stdio: any coding agent
that speaks MCP can ask the running city which sessions are working, which are waiting for you, and what each
agent is doing right now. Add it to Claude Code with:
claude mcp add agent-city -- npx -y agent-city-ai mcp
Any other MCP client (Cursor, Codex, omp, Claude Desktop…) takes the same command in its JSON config:
{
"mcpServers": {
"agent-city": { "command": "npx", "args": ["-y", "agent-city-ai", "mcp"] }
}
}
| Tool | Returns |
|---|---|
city_status |
whether the city is running, how many gangs it holds, how many are working and how many are waiting for you |
list_gangs |
every gang (session), most recently active first: id, title, runtime, status (working, waiting, idle, failed, ended), member count, and cost in USD for omp sessions only |
get_gang |
one gang by id: the Gang Lord and its subagents with their status, current tool and the file, command or intent it works on, plus the questions waiting for you |
The server only reads what the city already shows: it never messages, answers, steers or stops an agent, and
it reads the daemon on 127.0.0.1 with your own ~/.agent-city/token. Start the city first (npx agent-city-ai);
pass --port <n> (or set $AGENT_CITY_PORT) if it runs on another port. Claude Code gangs carry no cost, because
Claude Code hooks do not report it. Gang text (titles, tasks, activity targets, questions) is written by the
sessions themselves, so treat it as untrusted input, not as instructions for your agent.
Privacy and cost
- Everything runs on your machine. The daemon binds
127.0.0.1only and refuses other hosts and origins. - No accounts, no telemetry, no API calls: the city (code, 3D models, textures, map data) is inside this package, nothing is downloaded at runtime, and agent-city sends nothing anywhere.
- Watching costs nothing: agent-city makes no model calls of its own. A message you send from the phone, or a gang you recruit, is an ordinary omp turn and is billed like anything you type into omp.
- What the city sees: session titles, working directories, models, tool calls, messages and cost, as reported by the omp extension and the Claude Code hooks. It is kept in the daemon's memory only and is gone when you stop it.
~/.agent-city/token(mode 600) authenticates the extension, the hooks and your browser tab to the daemon. The Claude Code hooks carry a token derived from it, not the token itself. Logs of the current run are in~/.agent-city/logs/.- Optional photoreal map: if you paste your own Cesium ion token in Settings, the browser streams Google Photorealistic 3D Tiles from Cesium ion with it. It is off by default; the default map is fully local.
Uninstall
npx agent-city-ai uninstall-omp
npx agent-city-ai uninstall-claude
rm -rf ~/.agent-city
Credits and licenses
- agent-city is MIT-licensed (
LICENSE), © Tal Mogendorff. - 3D models, textures and the HDRI are CC0 or CC BY 4.0; every asset, its author and its license are listed
in
dist/ASSET_CREDITS.md. - Map data © OpenStreetMap contributors, available under the Open Database License 1.0 (ODbL): see
ODBL_NOTICE.md. - Bundled npm packages and their licenses:
dist/THIRD_PARTY_NOTICES.md.
agent-city is an independent project inspired by open-world crime games. It is not affiliated with, endorsed by or connected to Rockstar Games or Take-Two Interactive, and uses no names, assets, fonts or audio from any commercial game.
Source and issues
- Source code: github.com/Lulu-The-Narwhal/agent-city
- Bugs and ideas: issues
FAQ
What is Agent City? Agent City is a free, open-source 3D open-world game that shows your AI coding agents (Claude Code and omp) as gangs in a real Miami Beach built from OpenStreetMap. Each session is a gang named after the session, and its main agent is the Gang Lord you can talk to face to face or by phone.
Is Agent City free?
Agent City is free and open source under the MIT license. You run it with npx agent-city-ai; there is no account,
subscription or paid tier.
Can I try Agent City without installing it?
Agent City has a browser demo you can play with no install: the demo city
runs on GitHub Pages with sample gangs and scripted Gang Lords. To see your own agents, run npx agent-city-ai.
Does Agent City need API keys? Agent City needs no API keys: it makes no model calls of its own and only reads what your omp and Claude Code sessions report to it. The optional photoreal map is the only feature that takes a key, your own Cesium ion token, and it is off by default.
Does Agent City send my code anywhere?
Agent City sends nothing anywhere: the daemon binds 127.0.0.1 only, there is no telemetry, and session data is
kept in memory and gone when you stop it. The city, 3D models and map data are bundled in this package, so
nothing is downloaded at runtime.
Which AI agents does Agent City support? Agent City supports omp with full control (message, steer, abort, recruit new gangs) and Claude Code in watch-only mode. Other agents are not supported yet.
How do I install Agent City?
Agent City installs with npx agent-city-ai, which starts the city on http://127.0.0.1:4646; then run
npx agent-city-ai install-omp and/or npx agent-city-ai install-claude so your sessions join. It needs Node.js
20 or newer (or Bun) and a browser with WebGL 2.
How do I install Agent City with Claude Code? Agent City can be installed by Claude Code itself: paste "Install Agent City for me: follow https://github.com/Lulu-The-Narwhal/agent-city/blob/main/docs/INSTALL-FOR-AGENTS.md" into a session. Claude Code then follows the agent install guide and shows you every change before it is written.
Can I install Agent City as a Claude Code plugin?
Agent City is a Claude Code plugin too: run /plugin marketplace add Lulu-The-Narwhal/agent-city, then
/plugin install agent-city@agent-city, and start the city with npx agent-city-ai. The plugin sends the same
watch-only events as install-claude; use one or the other (see
Install as a Claude Code plugin).
Can my coding agent ask Agent City what other sessions are doing?
Agent City ships a read-only MCP server: add it with claude mcp add agent-city -- npx -y agent-city-ai mcp (or the
same command in any MCP client's config) and your agent can list the running gangs, see which are waiting for you
and what each agent is working on. It cannot message, answer or stop any session.
Does Agent City work on Windows and Linux? Agent City is developed and played on macOS, and its CI runs on Linux. Windows and Linux play-testing is still open in issue #10; reports are welcome there.
How much does Agent City cost to run? Agent City costs nothing to run: watching your agents makes no model calls. A message you send from the in-game phone, or a gang you recruit, is an ordinary omp turn billed by your model provider like anything you type into omp.
Is Agent City affiliated with any game studio? Agent City is an independent open-source project and is not affiliated with, endorsed by or connected to any game studio or publisher. It uses no names, assets, fonts or audio from any commercial game.
Authors
- Tal Mogendorff (@Lulu-The-Narwhal): creator and maintainer.
