🌩️ 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.
🚀 Quick Start · Highlights · Features · How it works · Built-in Experiments · Roadmap · Contributing · 🌏 中文
Other generative-agent projects let you watch. GOD lets you reign.
One screen. Pause time. Question any soul. Rewrite the next step. Restart the world. The missing operator console for a society of agents — alive while you steer it.
| ⏯️ 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. |
Live control room — PKU map, step controls, targeted ask, and resident roster in one view.
git clone https://github.com/XiaoLuoLYG/GOD.git
cd GOD
./scripts/god.sh startThat's it. On first run, the script installs everything, opens a browser-based setup wizard, and waits for you. No .env editing, no command-line flags, no glue scripts.
The Setup Wizard — model config, experiment choice, and custom society creation from one browser flow.
| 🔌 1. Model Paste an OpenAI-compatible API key, base URL, and model name. |
🧭 2. Choose Open GOD Town, open PKU Trump Visit, or create your own. |
🧪 3. Scenario Describe your world — date, weather, vibes, rules. |
🤖 4. Generate The GOD agent drafts agent profiles and a step plan. |
✏️ 5. Edit Tweak personalities, relationships, locations, or steps. |
6. Launch Publish the experiment and step into the control room. |
Any OpenAI-compatible endpoint works. When the wizard hands off, the script prints a URL like:
http://127.0.0.1:5174/pixel-replay/god_town/1
Full walkthrough: Quickstart →
| Feature | What you get | |
|---|---|---|
| 🎬 | Replay control | Scrub a live or recorded run by step. Pause, jump, auto-play. |
| 💬 | Targeted ask | Send a natural-language question to one agent, a group, or the whole town. |
| 🎛️ | Real-time intervention | Inject instructions into the next step — the agents read them on their next turn. |
| 🪄 | No-code setup wizard | Browser-based: configure model + scenario, let GOD generate agents and steps, edit, then launch. |
| 🧼 | One-command reset | Wipe replay data and seed a clean society without leaving the terminal. |
| 🗺️ | Pixel town world | A live tiled map: locations, actions, messages, statuses — every step replay-friendly. |
| 🧱 | Single current experiment | .env stores local model/port settings; .god/current_experiment.json stores the one active experiment. |
flowchart LR
O["Operator"]:::operator
UI["Control Room"]:::surface
API["Live API"]:::core
RT["Agent Runtime"]:::runtime
TOWN["Pixel Town"]:::world
CFG[["Experiment Files"]]:::data
DB[("Replay Store")]:::data
O --> UI
UI <-->|"commands / updates"| API
API -->|"prompts"| RT
RT -->|"actions"| TOWN
TOWN -->|"frames"| DB
CFG -->|"scenario"| API
classDef operator fill:#fff7ed,stroke:#f59e0b,color:#7c2d12,stroke-width:2px;
classDef surface fill:#eef2ff,stroke:#6366f1,color:#312e81,stroke-width:2px;
classDef core fill:#ecfeff,stroke:#0891b2,color:#164e63,stroke-width:2px;
classDef runtime fill:#f0fdf4,stroke:#22c55e,color:#14532d,stroke-width:2px;
classDef world fill:#fefce8,stroke:#ca8a04,color:#713f12,stroke-width:2px;
classDef data fill:#fdf2f8,stroke:#db2777,color:#831843,stroke-width:2px;
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.
| Layer | What it does |
|---|---|
| 🎮 Control Room | React/Vite browser UI — replay, ask, intervention, status. |
| ⚙️ Backend | Local FastAPI service exposing live and replay APIs. |
| 🗺️ Pixel Town | Replay-friendly social world: locations, actions, messages, agent status. |
| 🤖 Agent Runtime | Out-of-process LLM agents reached over a local WebSocket. |
./scripts/god.sh start # start the full stack (idempotent)
./scripts/god.sh configure # open setup to switch defaults or create an experiment
./scripts/god.sh restart # stop everything cleanly, then start again
./scripts/god.sh new-run # wipe the current experiment run and start fresh
./scripts/god.sh status # ports, URLs, model status
./scripts/god.sh stop # stop everything
./scripts/god.sh tail # follow logs
./scripts/god.sh open # open the frontend pages in the default browserGOD ships two built-in experiments and treats them exactly like experiments you publish yourself. The setup wizard writes the selected experiment to .god/current_experiment.json; start, open, and new-run then act only on that current experiment.
.env is intentionally local-only and only stores model, API, port, and similar machine settings. It no longer decides the default experiment or map, so an old GOD_MAP_ID=pku cannot make GOD Town load the PKU map.
A late-spring Tuesday morning at 8:20. Sunny, 18°C, light breeze. A 200-person town with 10 residents who know each other but don't live in each other's pockets — a slice-of-life simulation, not a quest script.
➡️ Choose god_town in the Setup Wizard to make this the current experiment. It is bound to hypothesis_god_town/experiment_1 and the the_ville map.
➡️ See hypothesis_god_town/experiment_1/ for the full breakdown of locations, profiles, and interactions.
The Ville — all 10 residents going about a typical day across home, school, library, cafe, park, market, pharmacy, pub, and dorm.
| 🗺️ 10 Locations · 65 location-scoped interactions | ||||
| 🏠 Home cook · sleep · tidy · read · WFH · video-call |
🏫 School attend / teach class · grade · office hours |
📚 Library read · study · research · borrow / return |
☕ Hobbs Cafe light meal · coffee chat · cafe shift · meetup |
🌳 Johnson Park walk · meet · exercise · public announcement |
| 🛠️ Supply Store repair · restock · lend tools · customer service |
🛒 Market buy food · haggle · deliver · chat w/ regulars |
💊 Pharmacy buy medicine · refill · check BP · home visit prep |
🍻 Pub socialize · watch match · host small event |
🛏️ Dorm rest · self-study · common-room hangout · video call |
| 👥 10 residents — each with a real life | ||||
| 🧭 Alice · 34 Neighborhood coordinator |
🛠️ Bob · 45 Supply-store shopkeeper |
📖 Charlie · 39 High-school history teacher |
💊 Dana · 41 Pharmacy nurse |
☕ Elena · 36 Cafe owner |
| 🎒 Farah · 16 High-school student |
📮 George · 68 Retired postman |
💻 Hana · 28 Remote software engineer |
🦺 Ivan · 52 Public-safety volunteer |
🍅 Mei · 47 Market vegetable vendor |
Every resident carries a full profile: age, family, housing, economic status, health, daily routine, skills, needs, worries, secrets, social network, language style, quirks, short- & long-term goals.
A campus public-situation experiment on a stylized PKU map. Daily routines begin around gates, classrooms, library, lake, dining hall, dormitory, and Centennial Hall, then a high-attention visit event tests how residents notice, ask, gather, and react.
➡️ Choose pku_trump_visit in the Setup Wizard to make this the current experiment. It is bound to hypothesis_pku_trump_visit/experiment_1 and the pku map.
➡️ See hypothesis_pku_trump_visit/experiment_1/ for the full scenario, cast, operator notes, and replay data.
PKU campus map — gates, classrooms, library, Weiming Lake, Boya Pagoda, dining hall, dorm, and Centennial Hall, with named residents and the Trump-visit cast.
GOD now discovers map packages automatically from agentsociety/custom/maps/<map_id>/. To add a map, copy agentsociety/custom/maps/_template/, replace map.yaml, visuals/map.json, tileset PNGs, and optional characters/ or location_assets/, then run:
cd agentsociety
uv run python scripts/validate_map_package.py custom/maps/<map_id>The setup wizard will list valid packages without code changes. v1 supports Tiled JSON maps with PNG tilesets and a Collisions layer where 0 means walkable. The PKU campus package now ships in the repository at agentsociety/custom/maps/pku/. See docs/MAP_PACKAGES.md for the full package contract.
- 🗺️ Pluggable map packages — drop a folder under
agentsociety/custom/maps/<map_id>/, refresh the wizard, and a new world is selectable. Auto-discovered, validated, hot-swappable. Seedocs/MAP_PACKAGES.md. - 🏫 PKU campus map — the PKU map package is bundled as a first-class map alongside The Ville.
- 🪄 No-code setup wizard — a browser flow that turns a blank machine into a live society, with model setup, built-in experiment choice, and custom experiment publishing.
- 🧪 Scripted experiments — reproducible experiments ship as plain folders under
quick_experiments/<hypothesis>/<experiment>/; choosing or publishing one makes it the current experiment.
- 🤖 Pluggable agent runtimes — swap LLM runtimes and persona templates as cleanly as we now swap maps.
- 🧪 Multi-experiment orchestration — run experiments, control groups, and repeats side-by-side.
- 🗺️ Live map generation — maps that evolve with events, repairs, blockages, and crowds.
- 🌦️ Event-responsive worlds — weather, accidents, festivals, rumors, shortages.
- 🌐 Large-scale simulation — AgentSociety batching, sharded runs, sampled replay.
- 📊 Experiment evaluation — cross-run metrics, behavior diffs, intervention analysis.
- 📝 Operator workflow — per-step notes, tags, bookmarks, key-event summaries.
- 🌍 Hosted demo & scenario sharing — public demo, experiment and map templates.
Have an idea? Open an issue or PR.
Issues and pull requests are very welcome. To set up a dev environment:
./scripts/god.sh startThat installs Python and Node dependencies, brings up the full stack, creates a live session, and runs the first step so the control room opens on a populated town. From there, edit and reload.
Full guide: CONTRIBUTING.md → — branching, PR checklist, style, and how to ship a new map or experiment.
GOD stands on the shoulders of open research and open-source. It bundles two trimmed, integrated upstream checkouts:
- AgentSociety — large-scale generative-agent simulation framework.
- JiuwenClaw — out-of-process agent runtime.
And takes inspiration from Generative Agents and OASIS.
@article{piao2025agentsociety,
title = {AgentSociety: Large-Scale Simulation of LLM-Driven Generative Agents Advances Understanding of Human Behaviors and Society},
author = {Piao et al.},
journal = {arXiv preprint arXiv:2502.08691},
year = {2025}
}
@misc{park2023generativeagents,
title = {Generative Agents: Interactive Simulacra of Human Behavior},
author = {Joon Sung Park and Joseph C. O'Brien and Carrie J. Cai and Meredith Ringel Morris and Percy Liang and Michael S. Bernstein},
year = {2023},
eprint = {2304.03442},
archivePrefix = {arXiv},
primaryClass = {cs.HC},
url = {https://arxiv.org/abs/2304.03442}
}Released under the Apache-2.0 license. Upstream LICENSE and NOTICE files are kept inside the integrated runtime checkouts and apply to those subtrees.
Built with care. ⭐ a star helps GOD grow.