🌩️ 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 · Scenarios · Developer Docs · Updates · 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 startWindows PowerShell: from the repo root, run .\scripts\god.cmd start.
That'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 replay 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. |
| ⌨️ | Command composer | Type /ask or /intervene, use @Name #id completions, and send operator commands without leaving the map. |
| 🪄 | No-code setup wizard | Browser-based: configure model + scenario, let GOD generate agents and steps, edit, then launch. |
| 🧬 | Agent Studio | Add or edit residents through a map-aware wizard for seed, identity, appearance, personality, routine, and review. |
| 🧭 | Map Studio | Generate or upload a map draft, calibrate locations and collisions, validate it, then publish it as a local map package. |
| 🧼 | 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.
GOD keeps three concepts separate:
- Experiment is the playable setup: map, agents, scenario context, and step plan.
- Replay is the viewable result of an experiment after it has been played.
- Runtime state is local machine data such as SQLite replay stores, logs, and agent snapshots; it is not part of an ExperimentPack and should not be committed.
| 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 local runtime state for the current experiment 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 browserOn Windows, replace ./scripts/god.sh with .\scripts\god.cmd.
GOD 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.
Supported feature updates:
- 2026-05-22 · Runtime localization · #26 — replay, setup, map metadata, locations, actions, statuses, emotions, group labels, and system event templates now switch cleanly between English and Chinese while preserving free-form agent content.
- 2026-05-23 · Control Room command UI · #27 — PixelReplay now uses a full-height map with a right-side rail, Summary/Chat/Residents/Live Console tabs, and a map-embedded
/ask+/intervenecommand composer with mention completion. - 2026-05-24 · Agent Studio wizard · #28 — Agent Builder and Setup drafts share a map-bound Studio flow for seed, identity, appearance, personality, daily setup, review, and structured agent metadata.
- 2026-05-25 · Strict sprite pipeline · #29 — Agent Studio can generate validated map-compatible sprites, preserve existing profile text, enforce clean IDs/config sync, and keep generated
Generated_Agent_*.pngfiles local by default. - 2026-05-26 · Agent runtime wiring · #30 — Agents now use the sames skill runtime consistently across AgentBuilder, setup drafts, imports, applies, and default experiment configs.
- 2026-05-27 · Map Studio · #31 — GOD now includes a Map Studio for generating or uploading local map drafts, configuring image generation, calibrating anchors/collisions, validating packages, publishing them, and returning to Setup with the new
map_idselected.
- 🗺️ 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 — browser flow for model setup, built-in experiment choice, custom experiment generation/editing, and launch.
- 🧪 Scripted experiments — reproducible experiments ship as plain folders under
quick_experiments/<hypothesis>/<experiment>/; choosing or publishing one makes it the current experiment. - 🎮 Control Room command rail — replay controls, resident roster, live console, targeted Ask, and Intervene now live in one map-first operator surface.
- 🧬 Agent Studio v1 — map-aware add/edit flow with structured profile metadata, ID validation, setup integration, and sprite generation support.
- 🧭 Map Studio v1 — prompt/reference-image map draft generation, anchor and collision calibration, package validation, publishing, and Setup handoff.
- 🌏 Bilingual runtime UI — English/Chinese UI and runtime-owned labels for setup, replay, maps, statuses, actions, and system events.
- 🔌 Agent skill-runtime path — the shipped JiuwenClaw agent adapter now uses the AgentSociety skill runtime as the canonical execution path.
- 🤖 Pluggable agent runtimes — swap LLM runtimes and persona templates as cleanly as we now swap maps.
- 🧪 Multi-experiment orchestration — run experiments, control groups, repeats, and ablations side-by-side.
- 🗺️ Live map generation — maps that evolve with events, repairs, blockages, and crowds.
- 🌦️ Event-responsive worlds — weather, accidents, festivals, rumors, shortages, repairs, blockages, and crowds that change agent behavior over time.
- 🌐 Large-scale simulation — AgentSociety batching, sharded runs, sampled replay, and performance-minded replay summaries.
- 📊 Experiment evaluation — cross-run metrics, behavior diffs, intervention effect analysis.
- 📝 Operator workflow — per-step notes, tags, bookmarks, key-event summaries.
- 🌍 Hosted demo & scenario sharing — public demo, experiment/map templates, and one-click import/export for community scenarios.
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.