How xiaoluolyg/god works
1. This repo is a bundled operator platform for agent-society simulations
It combines two major upstream codebases: AgentSociety for simulation and replay, and JiuwenClaw for agent runtime, tool use, and multi-channel operator interfaces. The top-level project (GOD) adds the glue, local startup scripts, packaged scenarios, map assets, and published docs/site content.
2. The user-facing surface is browser-first, with multiple frontends
There are two main React/Vite UIs:
- agentsociety/frontend: the “Control Room” for setup, map studio, agent studio, replay, experiments, and live interventions.
- jiuwenclaw/jiuwenclaw/channels/web/frontend: a richer operator console for chat, sessions, tools, config, logs, team state, and live interactions.
There is also a terminal UI under jiuwenclaw/jiuwenclaw/channels/tui/frontend for CLI-style operator workflows.
3. The core backend in AgentSociety owns the simulation-facing API
agentsociety/packages/agentsociety2/agentsociety2/backend is the main FastAPI service for:
- agent packs
- custom skills and packages
- experiment configs/packs
- maps and map studio
- live experiments
- replay access and public replay export
This is the API the browser setup flow and replay UI talk to for simulation lifecycle operations.
4. AgentSociety’s runtime model is built around experiments, agents, envs, skills, and replay storage
The package is organized as:
- agent/: agent configuration, prompts, persistence, concurrent execution, and agent context/person models
- env/: environment/router abstractions for simulation and benchmarking
- skills/: higher-level analysis, literature, paper, web research, hypothesis, and experiment tooling
- society/: workspace and CLI-style utilities for constructing studies and questionnaires
- storage/: replay writer, schemas, metadata, and operator command persistence
The key architectural boundary is that experiments are declarative inputs, while replay/storage are the runtime outputs.
5. Maps are first-class scenario packages, not just assets
The repository ships and validates map packages under agentsociety/custom/maps/, with templates and concrete maps like the_ville and pku. A map package includes:
- map.yaml metadata
- visuals/map.json and tiled assets
- optional characters/ and location_assets/
These maps are discovered by the backend and surfaced in setup; they define the spatial world that agent actions and replay rendering depend on.
6. Custom skills are the main extension mechanism for agent behavior
There are two skill systems:
- agentsociety/custom/skills/…: domain skills used by the simulation and content generation flow
- agentsociety/packages/agentsociety2/agentsociety2/skills/…: reusable higher-level research/analysis/experiment utilities
Each skill is a self-contained package with SKILL.md, a JSON manifest, and runnable scripts. The architecture treats skills as modular capabilities that can be generated, validated, imported, and executed independently of the core engine.
7. JiuwenClaw is the out-of-process agent runtime and tool ecosystem
The jiuwenclaw subtree is a full application stack of its own:
- server/: agent server, session management, skill manager, workspace, runtime adapters
- gateway/: channel routing, IM platform adapters, cron, heartbeat, message handling
- agents/harness/: prompt/rail/tool orchestration for agent execution
- common/ and extensions/: shared protocols, schema, security, and plugin hooks
This runtime is what lets agents execute outside the browser/backend process and connect through channels and protocols.
8. The runtime boundary is message-based and channel-aware
JiuwenClaw supports multiple ingress/egress channels: web, TUI, desktop, ACP, A2A, and several IM platforms such as WeChat, Feishu, DingTalk, Discord, Telegram, WhatsApp, and WeCom. The gateway normalizes inbound events, routes them to agent sessions, and sends responses back through the appropriate channel. This makes channel adapters the key integration boundary between external messaging systems and agent runtime state.
9. Agent execution is mediated by harnesses, rails, tools, and memory
In JiuwenClaw, agent behavior is not hardcoded in a single loop. It is composed from:
- harness layers for single-agent and team workflows
- rails for permissions, response shaping, user prompts, project memory, and stream events
- tools for browser, file, task, search, memory, audio/video, and phone-like actions
- memory systems for internal/external/project memory
This architecture separates policy/control from tool execution and keeps user-facing behavior configurable per agent or team.
10. Data flows are local-first and mostly file-backed
From the README and package layout, the main persistent artifacts are:
- experiment folders and map packages in the repo
- local runtime state such as session data, agent snapshots, logs, and replay stores
- published site data under docs/site/public-data
- generated site pages and docs under docs/site
The external dependency is typically only the configured OpenAI-compatible model endpoint; everything else runs locally.
11. Replay is a dedicated read model, separate from live execution
Replay data is written by the simulation/storage layer and then served to the Control Room and public site. The repo contains live replay APIs, public replay exporters, and static replay bundles under docs/site/public-data/replays/…. This indicates a clear split between:
- live state: ongoing simulation and operator interventions
- replay state: immutable or exported step history for review and sharing
12. Built-in scenarios are packaged as reproducible experiment folders
The quick_experiments/ tree and agentsociety/packages/agentsociety2/examples/ tree show that experiments are distributed as plain folders/scripts, not just database records. The setup wizard chooses one current experiment, and startup scripts operate against that selected experiment. This makes the experiment boundary portable, versionable, and easy to publish.
13. Docs and site content are part of the deliverable, not an afterthought
The repository includes:
- generated static documentation sites under docs/site
- source docs for both user and developer audiences
- localized content for English and Chinese
- scripts for publishing public site assets
For an architecture diagram, this is a distinct “published artifacts” lane fed from the codebase and data exports.
14. Operationally, startup is orchestrated by repo-level scripts
scripts/god.sh, scripts/god.cmd, and related build/validation scripts act as the top-level orchestration layer. They bootstrap dependencies, select the current experiment, bring up the local services, and open the browser-based control room. So the overall system is best drawn as a local workstation stack with coordinated Python services, React UIs, and a model endpoint.
Main entry points: app_agentserver.py Agent server · god.sh Start scripts · base.py Agent runtime · app.py Setup API
Components 21
GOD platform
Repo-level orchestration and bundled deliverables
- Start scripts · Repo-level bootstrap entrypoints for local workstation startup
scripts/god.sh - Publish site · Builds and validates public site assets and releases
scripts/publish_site_release_assets.py
AgentSociety
Simulation platform, control room, replay, maps, and custom skills
- Setup API · Simulation-facing API for packs, maps, experiments, replay, and imports
agentsociety/packages/agentsociety2/agentsociety2/backend/app.py - API routers · Route layer for setup, maps, experiments, live runs, replay, and package import
agentsociety/packages/agentsociety2/agentsociety2/backend/routers/experiments.py - Backend services · Pack registry, map generation, archive/import handling, and public replay export
agentsociety/packages/agentsociety2/agentsociety2/backend/services/replay_catalog.py - Agent runtime · Agent config, prompts, persistence, context, and concurrent execution
agentsociety/packages/agentsociety2/agentsociety2/agent/base.py - Env routers · Environment abstractions and router strategies for simulation and benchmarking
agentsociety/packages/agentsociety2/agentsociety2/env/router_react.py - Research skills · Higher-level analysis, literature, paper, web research, hypothesis, and experiment utilities
agentsociety/packages/agentsociety2/agentsociety2/skills/analysis/service.py - Society tools · Workspace, questionnaire, and study utilities for society-style workflows
agentsociety/packages/agentsociety2/agentsociety2/society/workspace.py - Replay storage · Replay writer, operator commands, metadata, and schema management
agentsociety/packages/agentsociety2/agentsociety2/storage/replay_writer.py - Map packs · Validated map packages with metadata, visuals, assets, and optional characters
agentsociety/custom/maps/the_ville/map.yaml - Custom skills · Domain skills with SKILL.md manifests and runnable scripts
agentsociety/custom/skills/care.basic/SKILL.md - Control Room · Browser UI for setup, map studio, agent studio, replay, experiments, and interventions
agentsociety/frontend/src/main.tsx
JiuwenClaw
Out-of-process agent runtime, gateway, harness, and operator consoles
- Agent server · Session management, skill manager, workspace, and runtime adapters
jiuwenclaw/jiuwenclaw/server/app_agentserver.py - Gateway · Normalizes inbound events and routes across channels and protocols
jiuwenclaw/jiuwenclaw/gateway/app_gateway.py - Harness · Prompt, rails, tools, memory, and team execution layers
jiuwenclaw/jiuwenclaw/agents/harness/common/prompt/prompt_builder.py - Web console · Browser operator console for chat, sessions, tools, config, logs, and team state
jiuwenclaw/jiuwenclaw/channels/web/frontend/src/App.tsx - TUI console · CLI-style operator workflow UI with commands, transcripts, and session tools
jiuwenclaw/jiuwenclaw/channels/tui/frontend/src/index.ts - Common + extensions · Shared schemas, wire formats, security, and extension hooks
jiuwenclaw/jiuwenclaw/common/e2a/wire_codec.py
Published artifacts
Static docs and site data exported from packages and scenarios
- Public data · Published maps, agent packs, experiments, and replay bundles
docs/site/public-data/experiments/index.json - Docs site · Generated documentation and localized site pages
docs/site/index.html
Connections 27
- Start scripts → Setup API: boots · Starts the simulation backend as part of the local stack
- Start scripts → Agent server: boots · Starts the out-of-process agent runtime/server
- Start scripts → Gateway: boots · Starts channel routing and message ingress/egress
- Start scripts → Control Room: opens · Launches the browser control room after services are ready
- Setup API → API routers: mounts · Exposes simulation and setup HTTP routes
- Setup API → Backend services: uses · Delegates pack, map, import, and replay operations
- API routers → Map packs: reads · Discovers and validates map packages
- API routers → Custom skills: imports · Scans custom skill packages for setup/runtime use
- Backend services → Replay storage: writes · Exports replay history and operator command records
- Agent runtime → Env routers: drives · Agent execution interacts with simulation environments
- Agent runtime → Research skills: invokes · Agents can call higher-level research and experiment skills
- Agent runtime → Replay storage: persists · Agent state and execution artifacts flow into replay/storage
- Society tools → Agent runtime: builds · Workspace and CLI tools construct agent-facing studies and outputs
- Map packs → Control Room: feeds · Map packages are surfaced in the Control Room setup and studio flows
- Replay storage → Public data: exports · Replay data is published as immutable public bundles
- Backend services → Public data: publishes · Agent packs, maps, experiments, and replays are exported to site data
- Control Room → Setup API: calls · Setup UI talks to the simulation-facing API
- Control Room → Public data: views · Replay and published scenario pages consume exported static data
- Agent server → Harness: orchestrates · Server coordinates harness execution, sessions, and tools
- Agent server → Common + extensions: depends on · Uses shared schemas, protocols, security, and plugin hooks
- Gateway → Common + extensions: normalizes · Converts platform messages into shared event and wire formats
- Gateway → Agent server: routes to · Forwards channel events into agent sessions and runtime state
- Harness → Common + extensions: uses · Harness layers rely on shared message and plugin contracts
- Web console → Agent server: connects · Web console streams session state and operator interactions
- TUI console → Agent server: connects · Terminal console drives sessions and commands through the server
- Publish site → Docs site: builds · Generates and validates the static documentation/site output
- Publish site → Public data: packages · Prepares public exports for site consumption and release