GOD Agent Society Control Room
A local control room for replaying, questioning, and steering language-agent society simulations.
Per-dimension scores and reasoning
Evidence shows: README explicitly states local-first, model endpoint is the only external service; SECURITY.md provides vulnerability reporting process; tests verify path escape protection. Deductions: no least-privilege design (e.g., sandboxing) found, user confirmation only in setup wizard, external effects (e.g., network requests) not explicitly restricted, rollback only via new-run command, dependency security lacks lockfile or vulnerability scanning.
Evidence shows: README and code structure are consistent, tests cover key modules, error handling is reflected in tests. Deductions: dependency availability not verified (e.g., external services), failure messages not fully documented.
Evidence shows: targets researchers and developers, provides multiple scenarios and maps, capability boundaries described in README, triggers clear (commands and UI), environment fit good (cross-platform). Deductions: no detailed scenario configuration guide, capability boundaries not fully cover all features.
Evidence shows: clear information architecture, detailed install notes, stable naming, rich examples, known limitations listed in Roadmap, Apache-2.0 license, version history and changelog present, maintenance responsibility clear. Deductions: no dedicated known limitations document, version history not exhaustive.
Evidence shows: output is usable control room interface, high marginal value (real-time control), cost-benefit reasonable (local run). Deductions: no performance benchmarks or cost analysis.
Evidence shows: README claims align with code and tests, tests cover multiple modules, facts and inferences distinguished in docs (e.g., prototype claim). Deductions: some claims (e.g., 'no-code setup') not fully verified, tests not cover all features.
- No least-privilege design found; review file access and network permissions in code.
- Dependency security lacks lockfile or vulnerability scanning; check dependency versions.
- External effects (e.g., network requests) not explicitly restricted; verify model endpoint configuration.
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
Collisionslayer underagentsociety/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
Collisionslayer.
- 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.git
cd GOD
./scripts/god.sh startOn 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.
FAQ
Does GOD itself have a usage cost?
What data leaves the machine?
Can I try it without an API key?
How do I clear a stale or failed run?
./scripts/god.sh new-run; it clears local runtime state for the current experiment and starts fresh.