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.

Packages

Package details

extension

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.

npm version npm downloads CI status License: MIT GitHub stars

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.

agent-city demo: drive Miami Beach, talk to your Gang Lord, see live costs

▶ 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-claude and sends them to the city on 127.0.0.1 ($AGENT_CITY_PORT, default 4646) with the token derived from ~/.agent-city/token. It writes nothing to settings.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) on PATH and the city started once with npx agent-city-ai, which creates the token. If you run the city on another port, start Claude Code with the same AGENT_CITY_PORT.
  • Use the plugin or install-claude, not both. While install-claude's hooks are in your user settings the plugin stays silent, so no event is counted twice; run npx agent-city-ai uninstall-claude to switch to the plugin. doctor checks only install-claude's hooks, so with the plugin its claude hooks line stays warn.
  • 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, with node on 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 whether install-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-omp copies, 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.js exists the package stands by, so no session is counted twice; run npx agent-city-ai uninstall-omp to switch to the package. doctor shows 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.1 only 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

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

Star history

Star history of Lulu-The-Narwhal/agent-city