GOD Agent Society Control Room
A local control room for replaying, questioning, and steering language-agent society simulations.
What does this agent do, and when should you use it?
GOD, short for Govern, Observe, Direct, is a local-first control room for language-agent society simulations. It combines a React/Vite browser control room, a local FastAPI service, a pixel-town world, replay storage, and an out-of-process agent runtime connected over local WebSocket. Operators can inspect live or recorded replays step by step, ask an individual resident, a group, or the whole town questions, and inject instructions for the next step. An experiment packages a map, agents, scenario context, and a step plan, while a replay is the viewable result after that experiment runs. The project also supports ZIP import and export for Experiment, Map, and Agent packs, plus GitHub Pages browser replays that require neither local installation nor an API key.
Running ./scripts/god.sh start starts the local stack and opens a browser setup wizard on first run. The wizard accepts an OpenAI-compatible API key, base URL, and model name, then lets an operator select a built-in experiment or create a custom society; the selection is written to .god/current_experiment.json. The Control Room exchanges updates and commands with the Live API, which sends prompts to the out-of-process Agent Runtime; returned actions update the pixel town and its frames are stored in the Replay Store. Operators can pause, jump, or auto-play replay steps, issue targeted commands with /ask and /intervene, use @Name #id completions, and import or export Experiment, Map, and Agent packs.
- A simulation researcher needs to inspect resident actions one step at a time and test the effect of an instruction injected into the next step.
- An instructor or demonstrator wants to show recorded town simulations in a browser without requiring viewers to install software or supply model credentials.
- An experiment designer wants to use the setup wizard to draft a scenario, edit resident profiles and step plans, then publish the result as the current experiment.
- A map author needs to package a Tiled JSON map, PNG tilesets, and a `Collisions` layer under `agentsociety/custom/maps/<map_id>/` for automatic discovery.
- A local operator needs one command surface for changing configuration, restarting the stack, inspecting status and logs, or clearing state for the current experiment.
What are this agent's strengths and limitations?
- Combines replay controls, targeted questioning, next-step intervention, and a resident roster in one map-first operator interface.
- Runs local-first: the control room, backend, runtime bridge, experiment files, and replay store stay on the operator's machine; the selected model endpoint is the only external service.
- Accepts OpenAI-compatible APIs instead of documenting dependence on one model provider.
- Provides ZIP import and export for Experiment, Map, and Agent packs alongside browser-accessible public replays.
- Automatically discovers and validates map packages built with Tiled JSON, PNG tilesets, and a `Collisions` layer.
- Interactive runs require the operator to supply an OpenAI-compatible endpoint, API key, base URL, and model name.
- The project explicitly frames itself as a tool for inspecting language-agent societies, not as evidence that those societies are socially realistic.
- It maintains one current experiment through `.god/current_experiment.json`, rather than documented simultaneous experiment orchestration.
- Pluggable agent runtimes, control groups and repeat runs, and cross-run evaluation remain roadmap items.
- Local runtime state includes SQLite replay stores, logs, and agent snapshots that are not part of an ExperimentPack, adding migration and reproducibility work.
How do you install or deploy this agent?
You need Git, Python 3.11+, Node.js, and an OpenAI-compatible model endpoint. Run:git clone https://github.com/XiaoLuoLYG/GOD.gitcd GOD./scripts/god.sh start
On Windows PowerShell, run ./scripts/god.cmd start. The first start installs dependencies and opens the browser setup wizard; enter an API key, base URL, and model name, then select or create an experiment.
How do you use this agent?
After startup, configure the model in the browser wizard and choose god_town, pku_trump_visit, or a custom experiment. A Control Room URL follows the form http://127.0.0.1:5174/pixel-replay/god_town/1. Use the Control Room to pause, jump through, or auto-play steps; use /ask to question residents, groups, or the town, and /intervene to inject an instruction into the next step. Operational commands include ./scripts/god.sh configure, restart, new-run, status, stop, tail, and open.
How does this agent compare with similar options?
GOD is not presented as a replacement for AgentSociety or JiuwenClaw: it bundles trimmed upstream checkouts of both, using AgentSociety as a generative-agent simulation framework and JiuwenClaw as an out-of-process agent runtime. GOD adds the local operational surface for controlling, observing, and replaying an experiment.