Govern, Observe, Direct (GOD) provides a real-time control room for agent societies, enabling users to actively steer and manage simulations. It addresses the limitation of passive observation in other generative agent projects by offering an intuitive interface for governing, observing, and directing agents, making it ideal for researchers and power users exploring agent-based systems.

How It Works

GOD employs a local-first architecture, running the control room, backend, agent runtime, and data stores on the user's machine, with only the LLM endpoint being external. It utilizes a React/Vite browser UI for interaction, a FastAPI backend, a "Pixel Town" for visualizing agent actions and statuses, and an out-of-process runtime for LLM agents. This approach simplifies setup and provides direct, real-time manipulation capabilities.

Quick Start & Requirements

To start, clone the repository (git clone https://github.com/XiaoLuoLYG/GOD.git), navigate into the directory (cd GOD), and run the start script (./scripts/god.sh start). The script handles all installations on the first run. A primary requirement is an OpenAI-compatible API key, base URL, and model name. The setup wizard guides users through model configuration, experiment selection, and society creation via a browser interface. Links to official documentation can be found in docs/MAP_PACKAGES.md and CONTRIBUTING.md.

Highlighted Details

• Replay Control: Pause, scrub, fast-forward, and auto-play live or recorded simulation steps.
• Targeted Ask: Send natural-language queries to individual agents, groups, or the entire town mid-simulation.
• Real-time Intervention: Inject instructions that agents will process in their next turn.
• No-code Setup Wizard: A browser-based flow for configuring models, scenarios, and generating agents without manual scripting.
• Pixel Town World: A live, replay-friendly tiled map visualizing agent locations, actions, and statuses.
• Pluggable Map Packages: Easily add custom maps by placing them in the agentsociety/custom/maps/ directory.

Maintenance & Community

The project is actively under development, with a roadmap detailing completed and upcoming features such as pluggable agent runtimes and multi-experiment orchestration. While specific community channels like Discord or Slack are not listed, the CONTRIBUTING.md file provides guidance for developers. The project acknowledges inspiration from AgentSociety and Generative Agents.

Licensing & Compatibility

GOD is released under the Apache-2.0 license, which is generally permissive for commercial use and integration into closed-source projects. Upstream license and notice files are maintained within integrated components.

Limitations & Caveats

Several advanced features remain "Not Yet Done" according to the roadmap, including pluggable agent runtimes, multi-experiment orchestration, live map generation, and large-scale simulation capabilities. The project relies on external OpenAI-compatible API endpoints for its core LLM functionality.