Overview

GOD stands for Govern, Observe, Direct. It is a local-first operator console for running an agent society, watching it step by step, asking residents questions, and injecting instructions into the next live step.

What GOD adds

GOD is not only a simulation framework:

  • The setup wizard configures model settings, chooses built-in experiments, and publishes custom experiments.

  • PixelReplay shows the town, timeline, residents, chat, and live controls in one browser UI.

  • Agent Studio edits residents with map-aware identity, appearance, personality, routine, and review steps.

  • Map Studio generates or uploads map drafts, calibrates anchors and collisions, validates them, and publishes map packages.

  • scripts/god.sh owns the local startup lifecycle so a new contributor does not need to wire four services manually.

Runtime shape

The normal local stack is:

  1. Operator opens the control room in the browser.

  2. The React/Vite frontend calls the local FastAPI backend.

  3. The backend reads the current experiment from .god/current_experiment.json and experiment files under agentsociety/quick_experiments.

  4. The live experiment runner talks to JiuwenClaw over a local WebSocket.

  5. Pixel Town writes replay data so the frontend can scrub and inspect each step.

Primary repo areas

scripts/god.sh

One-command setup, start, restart, status, browser opening, and cleanup.

agentsociety/frontend

GOD control room, setup wizard, Agent Studio, Map Studio, and PixelReplay UI.

agentsociety/packages/agentsociety2

Backend routers, live experiment runner, map package services, replay services, and selected extension points.

agentsociety/quick_experiments

Built-in and user-published experiments.

agentsociety/custom/maps

Pluggable map packages.

jiuwenclaw

Integrated out-of-process agent runtime.