Getting Started¶

Prerequisites¶

• Python 3.12+ -- Download
• uv -- Install uv
• Anthropic API key -- Get one here

Installation¶

Clone the repository and install dependencies:

git clone https://github.com/reubenjohn/token-world.git
cd token-world
uv sync

Configuration¶

Copy the environment template and add your API key:

cp .env.example .env

Edit .env and set your ANTHROPIC_API_KEY.

Running Tests¶

Verify everything is working:

uv run pytest

Basic Usage¶

Token World is under active development (simulation engine lands in Phase 05). The graph foundation, mechanic framework, spatial/temporal indices, and visualisation tooling are ready today.

Create a universe¶

uv run token-world create my-world
uv run token-world list

This scaffolds a universe folder with CLAUDE.md, .mcp.json, universe.db, mechanics/, and agents/.

Visualise the graph¶

Once a universe has state, render it as a Mermaid flowchart:

uv run token-world viz-graph my-world --node alice --depth 2

See the viz-graph guide for the full CLI reference (filters, output modes, styling).

Next Steps¶

• Read the Architecture Overview to understand how the system works
• Browse the viz-graph guide for graph inspection tooling
• Check out the pyproject.toml for project configuration details