Settlement: a village strategy game where you can see why every agent did what it did

Most multi-agent demos show you what the agents did. I wanted to see why.

Settlement is a village strategy game and a small AI simulation lab. You give six residents a shared objective (grow the village, prepare for a raid, restock supplies) and watch them claim jobs, gather, build and upgrade. Then you click any resident and read their decision, their route and their memories.

Play it in the browser, no signup, no API key: https://settlement-village.vercel.app

A real recording of the live site: one click on Grow the village, then the decision log.

How the agents cooperate

The six residents bid for exclusive jobs using role suitability, distance and bounded experience. When a workplace or resource changes, they replan. Campaign residents use deterministic game AI, so there are no model calls and nothing to pay for.

Try this: choose Village orders → Grow the village, start it, then open View plan to see the dependencies, the waiting reasons and the actual spending. Give a working resident a 20-tick rest and watch another one take over the job.

The growth plan has a spending ceiling and protected reserves. In a fresh village it authorizes at most 1,560 gold and 1,240 timber and keeps 250 gold, 200 timber and 150 food back.

Test your own agent

The part I care about most: it's also a testbed for external agents.

npx settlement-testbed --agent http://127.0.0.1:8765/decide --name my-agent

Point it at an HTTP endpoint, and it evaluates your agent, compares it with built-in policies, and records the answers so anyone can verify, replay or share the results. There are twelve scenarios, attacks and honest controls, based on manipulation tactics from published agent-safety studies, each citing its sources.

Optional Claude decisions exist for explicit steps in local-worker research experiments. They're off unless you configure them.

Run it locally

git clone https://github.com/Lingikaushikreddy/Settlement-Village.git
cd Settlement-Village
npm ci
npm run dev

Needs Node 24+. TypeScript, MIT licensed, CI on every push.

Repo: https://github.com/Lingikaushikreddy/Settlement-Village
npm: https://www.npmjs.com/package/settlement-testbed

If you like games where agent decisions are visible, a star helps me find out whether anyone else does.