A universe simulator where LLM-powered agents inhabit a text-based world with procedurally generated mechanics.
Token World is a universe simulator where LLM-powered agents inhabit a text-based world and interact with an environment whose rules are procedurally generated on-the-fly.
The simulation engine -- itself an LLM agent -- interprets resident agent actions, maps them to existing mechanics or generates new ones as executable Python code, and returns grounded observations. All world state lives in a flexible knowledge graph (NetworkX) that evolves as new concepts emerge.
From a resident agent's perspective, the world feels fully real. Every observation is grounded in the knowledge graph state and mechanic execution -- no hallucinated state, no ungrounded generation.
- Knowledge Graph -- Schema-less property graph (NetworkX) where all world state lives. If it's not in the graph, it doesn't exist.
- Mechanics -- Python functions that define world rules. Generated by LLMs, executed deterministically. Each mechanic checks preconditions against the graph and applies side effects.
- Resident Agents -- LLM-powered inhabitants that perceive and act within the world through natural language.
- Simulation Engine -- Orchestrates the tick loop: interpret action, match/generate mechanic, execute, observe.
# Clone the repository
git clone https://github.com/reubenjohn/token-world.git
cd token-world
# Install dependencies (requires uv)
uv sync
# Run tests
uv run pytest
# Copy environment template
cp .env.example .env
# Edit .env with your Anthropic API key# Run tests with coverage
uv run pytest tests/ --cov --cov-report=term -v
# Lint
uvx ruff check .
# Format
uvx ruff format .
# Type check
uv run mypy src/
# Install pre-commit hooks (using prek)
prek installFull documentation is available at reubenjohn.github.io/token-world.
- Architecture Overview — system components + simulation loop diagrams
- Simulation Pipeline — detailed per-tick flow (classify → match → decide → execute → observe)
- Getting Started Guide
- Authoring Mechanics
- Graph Visualization
- Zero-Cost LLM Backend — route simulation LLM calls through your Claude subscription
v1.0 MVP — SHIPPED 2026-04-14 (release notes · retrospective)
10 phases delivered: knowledge graph, mechanic framework, operator-authored mechanics under inversion of control, simulation engine with grounded observations, resident agent with memory and playtesting, composable attention/consciousness mechanics (sleep + daydream + drunk + autopilot_travel), and a pluggable LLM backend supporting zero-cost UAT via claude -p.
1743 tests passing · CI green on master · tagged v1.0.
This project is licensed under the MIT License -- see the LICENSE file for details.