civ-v-llm-harness

Give an LLM a civilization. See what survives.

Game image from Civilization V on Steam.

A rival settles the river first. Your peaceful science plan now has a border problem. The model in that seat sees the same fogged map you would, knows only the civilizations it has met, and has to decide anyway.

This harness puts a language model in a real seat in Sid Meier's Civilization V. Challenge it in hotseat or over LAN, hand it your seat against the game's AI, or put several models in the same match.

It sees the world the way you do, in text. Every revealed tile comes back as terrain, yields, resources, what a worker could build there and who is standing on it. Unexplored land is a frontier it can go and look at, not a list of coordinates to memorize. It has to scout, settle, negotiate, fight and adapt, and it never gets more than a human in that seat would. Fogged tiles stay fogged. Unmet civilizations stay unknown. The AI's private plans stay private.

Most games bolt an LLM on as a chat layer. This one goes inside the game so a model plays by the same rules as everyone else at the table.

Want to play? Give an LLM of your choice the agent install guide and ask it to set up the harness and start a game. The guide has the commands and checks; this page is for you. Raw guide for your agent.

Requires the native Linux Steam build of Civilization V with Brave New World. Version 1.1.0, Lua runtime v212.

Quick links: What you get · What it looks like · What to expect · Ways to play · How it works · Honest limits · Documentation · Development · Authorship

What you get

• Information parity. Fogged tiles carry no live units, unmet civs do not exist, private AI state is unreadable. Every screen, hover and refusal reason a human reads is a tool result. docs/LIMITATIONS.md lists what is withheld and why.

• The whole game, not a demo. Units, cities, research, policies, religion, espionage, World Congress, trade routes, archaeology, ideology, great works, city-states, and the spaceship.

• Real diplomacy. Deals, demands, peace with terms, friendship, denouncement and leader conversations go through the game's own screens, with the AI's actual replies. Human-to-LLM trades work in hotseat and LAN.

• A digest, not a firehose. turn_digest says what happened since the model last looked: combats, captures, growth, leader messages, each linked to its notification.

• Three seats, one server. Solo, hotseat and LAN share the same tools; a multi-LLM HTTP mode runs one seat per API key.

• Recovery. end_turn quick-saves by default, load_latest resumes after a crash, and a supervisor can relaunch the game and rejoin a LAN game on its own.

• One call per turn. finish_turn ends the turn, waits (sending progress so the wait is not cut short), and returns the new turn's status, digest and the model's own notes. skip_quiet_turns lets uneventful turns pass; anything a human would look up for (combat, a leader at the door, an empty city) wakes the model.

• Batches and retries. do runs a list of orders in one call and stops at the first refusal; an action_id on any action makes a retried call a replay, never a second move.

• Knows its seat. Every status names the player the server is playing; if that is the wrong one (a hotseat save loaded under an auto seat), set_seat moves it to another human seat without a restart.

• A notebook. remember / recall keep the model's plan, threats and promises beside the game, per seat, across sessions and context loss, and the latest notes ride along with every new turn.

• Tested without the game. 559 regression tests run the shipped Lua under lupa and the Python layer against fake bridges. Live claims are logged per turn against saved states in saves/.

Related MCP server: llm-battle-mcp

What it looks like

The model plays through tool calls; you watch the game window. On its turn it checks what changed, inspects its cities and units, chooses actions the game permits, then ends the turn. In hotseat, the window passes back to you. The working loop looks like this:

finish_turn -> (status, digest, notes) -> overview / units / cities / known_world
-> act (check available_* first) -> turn_status until nothing blocks -> remember(plan) -> finish_turn

A real turn_status reply from a live solo game, turn 269, trimmed for width:

{"turn": 269, "my_turn": true, "mode": "single", "blocking_name": "NO_ENDTURN_BLOCKING_TYPE",
 "todo": {"promotions": [], "research_unset": false, "cities": [], "units": []},
 "pending_popups": [], "game_over": false, "notifications": {"live": 2, "held": 99}}

When something blocks the turn, blocking_name names it and blocking_hint points to the tool that clears it. Refused actions explain why and what to try instead.

What to expect

• Setup is one sitting. Your agent does the install; you handle two things in Steam if they are not already true: the game must be the native Linux build (not Proton), and the tuner must be enabled in the game's config. Cold start of the game is about two minutes.

• The game runs in a normal window on your desktop. Leave it alone during the LLM's turn. In hotseat you take your own turn in that window as usual.

• It is slow and it costs tokens. A developed empire means dozens of tool calls per turn. A game to victory is a long project; an evening is a few dozen turns.

• The LLM has no hidden game state. The raw Lua escape hatch is disabled unless you turn it on.

• The game crashes sometimes. The Linux port does, with or without the harness. Quick saves every turn and load_latest make it a pause, not a loss.

Ways to play

The install guide walks through each. Saved states in saves/ reproduce late-game diplomacy, peace terms, Venice puppets and a combat lab if you want to drop an LLM into something interesting on turn one.

How it works

LLM client  --stdio-->  harness.mcp_server  --unix socket-->  harness.tunerd  --TCP 4318-->  Civ5XP
                        (122 tools, game.py)                   (owns the one     (+ LD_PRELOAD shim,
                                                                tuner connection)  EnableTuner = 1)

Civilization V ships a debugging channel, FireTuner, that is a remote Lua console into the game's own UI contexts. The harness keeps that channel open in multiplayer with a small preload shim, injects a Lua runtime that ports the stock UI's own logic (combat previews, trade legality, hovers), and drives every screen the way a mouse would. Because the network only carries player commands in a lockstep simulation, a real game instance is the only faithful client; that is why the LLM gets one. docs/ARCHITECTURE.md has the long version.

Honest limits

• Linux only, native Steam build only, Brave New World only. No Windows, no macOS, no Proton.

• With the tuner enabled the game listens on every interface by default. The install guide binds it to loopback; do not skip that on a shared network.

• A few end-turn blockers (some World Congress votes, some free-choice popups) have no tool yet; the model is told to stop and ask you. docs/GAPS.md is the running audit.

• Movement-cost previews and path overlays are not readable: the engine calls that back them crash the game.

• No hosted CI by choice; the suite runs locally before every push.

Documentation

• docs/AGENT_INSTALL.md: the complete install brief for an agent.

• docs/PLAYBOOK.md: how a seat should play, turn by turn, with the blocker table.

• docs/ARCHITECTURE.md: layers, information boundary, game modes, repo layout.

• docs/LIMITATIONS.md: what the harness will not do, each item checked against the engine.

• docs/GAPS.md, docs/ROADMAP.md, CHANGELOG.md: live audit, plan, and the map from package versions to runtime versions.

• docs/DECK_HOWTO.md: running a seat on a Steam Deck.

• saves/README.md: the reproduction states and what each one shows.

Development

uv sync --group dev
scripts/check.sh            # 528 tests, no game needed; run before every push

The Lua runtime (harness/lua/runtime.lua) carries its own version counter, bumped on every change, because a running game keeps the old runtime until a newer number arrives. Commit subjects carry it as runtime vNNN.

Issues and milestones live on GitLab: https://gitlab.com/Tyler-Meador/civ-v-linux-mcp.

Authorship

This project was written by Claude, Anthropic's AI model, working in Claude Code under the direction of Ty Meador, who owns the game, ran every live session and decided what the harness should and should not do. Across 401 commits between 2026-09-15 and 2026-09-25, Claude Fable 5.1 co-authored 215, Claude Opus 5 133 and Claude Sonnet 5 10: the reverse engineering of the FireTuner protocol and the game binary, the shim, the Lua runtime, the MCP server, the tests, the documentation and this README. Ty's contribution is the design brief, the live verification against the running game, the judgement calls recorded in docs/GAPS.md, and the standard that the seat may see only what a human sees.

License

MIT. Sid Meier's Civilization V, its assets and the stock UI Lua quoted in docs/ belong to Firaxis Games and Take-Two Interactive and are not covered by this licence; you need your own copy of the game.