GOD: Real-Time Control Room for Agent Societies

TL;DR

TL;DR: GOD (Govern, Observe, Direct) is an Apache-2.0 real-time operator console for generative-agent societies that lets you pause time, ask any agent a question, inject instructions into the next step, and reset the world, all from a browser-based control room.

Source and Accuracy Notes

• Project page: xiaoluolyg.github.io/GOD
• Source repository: github.com/XiaoLuoLYG/GOD
• License: Apache-2.0 (verified via GitHub API license.spdx_id)
• Python: 3.11+, React 18, Vite 6
• Source last checked: 2026-06-16

What Is GOD?

GOD is a local-first operator console for societies of LLM-driven agents. Where most generative-agent projects let you watch a society run, GOD lets you steer it. The opening line of the README captures the design intent: “Be like a god to a town of agents. Pause time. Whisper to a soul. Bend the next step. Reset the world — all from a single click.”

The technical scope is a React 18 control room, a Python 3.11+ backend, and a runtime bridge that calls any OpenAI-compatible LLM endpoint. The world is a pixel-art town with locations, actions, messages, statuses, and per-step replay frames. Experiments are stored in .env (model, port) and .god/current_experiment.json (one active experiment).

Repo-Specific Setup Workflow

Step 1: Install and start

git clone https://github.com/XiaoLuoLYG/GOD.git
cd GOD
./scripts/god.sh start

Windows PowerShell:

.\scripts\god.cmd start

The script installs everything, opens a browser-based setup wizard, and waits for you. There is no .env editing, no command-line flags, and no glue scripts.

Step 2: Configure the model

The setup wizard prompts for an OpenAI-compatible API key, base URL, and model name. Any OpenAI-compatible endpoint works — OpenAI, Anthropic via gateway, local Ollama, OpenRouter, or a private deployment.

Step 3: Choose an experiment

The wizard hands off with built-in experiments (GOD Town, PKU Trump Visit) and a custom society creator. The flow is: model, choose experiment, scenario description, agent generation, edit, launch.

Step 4: Open the control room

The script prints a URL like:

http://127.0.0.1:5174/pixel-replay/god_town/1

The control room shows the pixel town map, step controls, targeted ask, and the resident roster in one view. The full walkthrough is in QUICKSTART.md.

Deeper Analysis

Operator model

The README positions GOD as “the missing operator console for a society of agents.” Five primitives make up that operator model:

• Pause time. Stop, scrub, fast-forward, auto-play any live step.
• Whisper to anyone. Ask one resident, a group, or the whole town, mid-run.
• Bend the next step. Inject instructions and watch agents react in real time.
• No-code setup. Configure model, scenario, and agents from a browser wizard.
• Reset reality. One command wipes a stale run and re-seeds a clean world.

These five primitives turn a generative-agent simulation from a recording into a steerable system. The targeted ask primitive in particular is interesting: you can question a single agent and use the answer as a steering signal without leaving the map.

Replay control

The replay store keeps per-step frames for every experiment. The replay control surface lets you scrub a live or recorded replay by step, pause, jump to a specific step, or auto-play. The replay store is local, so the same experiment can be replayed, branched, or reset without involving the model endpoint.

Agent Studio and Map Studio

Agent Studio is a map-aware wizard for adding or editing residents. The fields include seed, identity, appearance, personality, routine, and a review step. Map Studio generates or uploads a map draft, calibrates locations and collisions, validates the map, and publishes it as a local map package. The two studios together make the platform self-contained: you can run GOD without an external asset pipeline.

Single-experiment mode

GOD enforces “one current experiment” through .god/current_experiment.json. The .env file holds local model and port settings. The split is intentional: it makes the active experiment the unit of versioning, sharing, and replay, rather than a global state that drifts over time.

Local-first

GOD is intentionally local-first. The control room, backend, runtime bridge, experiment files, and replay store all run on your machine. The model endpoint is the only external service you choose. The implication is that you can use GOD with a local Ollama model and a closed experiment, or you can use GOD with a hosted provider and a public experiment, and the rest of the platform stays the same.

Practical Evaluation Checklist

• [ ] Do you want to study, demo, or teach multi-agent social simulation?
• [ ] Do you need a steerable simulation rather than a passive recording?
• [ ] Is “pause, ask, intervene, reset” the operator model you want?
• [ ] Do you need an OpenAI-compatible endpoint (OpenAI, Anthropic via gateway, Ollama, OpenRouter)?
• [ ] Will you author experiments through the no-code wizard, or do you need raw config files?
• [ ] Do you need replayable per-step frames for review or branching?
• [ ] Is local-first operation (control room + backend + replay store on your machine) a real requirement?
• [ ] Do you need the Agent Studio or Map Studio to author residents and worlds?

Security Notes

GOD is local-first, so the bulk of the platform is on your machine. The risk surface is the model endpoint, the experiment files, and the replay store. The model endpoint behaves the way any LLM endpoint behaves: a key with rate limits, billing exposure, and a prompt surface. The README is clear that the model endpoint is the only external service you choose, so keep that key out of version control and rotate it on a schedule.

The experiment files (.god/current_experiment.json) can contain prompts, agent profiles, scenarios, and step plans. If you author sensitive scenarios, treat them as collaboration artifacts and keep them in private repositories. The replay store is local, but it can capture the full transcript of every experiment, including any data you typed into the wizard.

The script scripts/god.sh start installs dependencies and starts the stack. If you run it in a shared environment, review the script before executing it the way you would any other bootstrap script.

FAQ

Q: Is GOD affiliated with any generative-agent research lab? A: No. GOD is an independent open-source project. The README positions it as the missing operator console for a society of agents, not as a fork of any specific simulation platform.

Q: Does GOD support local models? A: Yes. Any OpenAI-compatible endpoint works. The setup wizard takes an OpenAI-compatible base URL, model name, and API key, so Ollama, OpenRouter, a private gateway, or OpenAI itself all work.

Q: Can I run GOD on Windows? A: Yes. The project ships scripts/god.cmd for Windows PowerShell, and the README documents the install path alongside the god.sh Linux path.

Q: What is the difference between GOD Town and PKU Trump Visit? A: GOD Town is the canonical demo society used to illustrate the platform. PKU Trump Visit is a real-world scenario built on a pixel map of Peking University. Both are part of the built-in experiment library.

Q: Can I keep multiple experiments active at the same time? A: No. GOD enforces a single current experiment through .god/current_experiment.json. Switching experiments is a one-command reset that wipes replay data and reseeds a clean world.

Conclusion

GOD is a focused project with a clear design thesis: generative-agent simulations should be steerable, not just watchable. The five operator primitives, the replay store, and the local-first architecture back that thesis. If you study, demo, or teach multi-agent social simulation and you want a control room that lets you pause time, ask any agent a question, intervene in the next step, and reset the world, GOD is worth a serious look. If you just want a passive recording of an agent society, a different tool will fit better.

Related reading: GitHub Trending tools, Developer tools, Voltagent, Modulus, Cardboard.