Lorekit

LoreKit𓂃🪶🎲

Open-source TTRPG game engine for AI agents. Tracks everything needed to run full campaigns — characters, sessions, story arcs, regions, and more.

Play via the terminal TUI, or embed lorekit in your own app (Discord bot, web client) using the GameSession Python API or the HTTP server. Under the hood, lorekit starts an MCP server and spawns an AI agent as the GM — the client just sends player messages and renders the responses.

All mechanical crunch is handled deterministically by the [cruncher](cruncher/) engine so the AI never has to guess numbers. The GM agent reads guidelines/GM_GUIDE.md and runs the adventure; NPCs are spawned as independent agents with their own context and memory.

Packages

This repo ships two Python packages:

| Package | Path | Description | |---------|------|-------------| | cruncher | cruncher/ | Standalone, zero-dependency TTRPG rules engine. Pure computation — formulas, stacking, character building, stat derivation, dice. | | lorekit | src/lorekit/ | Full MCP game engine. Session management, characters, combat orchestration, NPC agents, narrative tracking, semantic search. Includes providers, orchestrator, config, and an optional HTTP server. Depends on cruncher. |

System packs (systems/) are data, not code — they ship separately from both packages.

Requirements

• Python 3.13+
• Claude Code — the AI CLI tool used by lorekit to run the GM agent (support for Codex and Gemini CLI is planned)
• Optional: starlette + uvicorn for the HTTP server (pip install lorekit[server])

Setup

uv sync

# or
python3.13 -m venv .venv
source .venv/bin/activate
pip install -e cruncher/ -e .

Configuration lives in ~/.config/lorekit/config.toml. On first run, lorekit creates the database automatically.

Development

uv sync --extra dev
pre-commit install

# or
pip install -e ".[dev]"
pre-commit install

Testing

pytest                       # all 1010 tests
pytest tests/unit/           # fast — single-module tests
pytest tests/integration/    # cross-module interaction tests

Playing

Before playing, create ~/.config/lorekit/config.toml:

[agent]
provider = "claude"
model = "opus"

TUI (terminal interface):

make tui

Or directly: npx tsx examples/tui/src/index.tsx

The TUI starts lorekit serve, which manages the MCP server and GM agent. The TUI communicates via HTTP+SSE. The GM agent reads guidelines/GM_GUIDE.md and takes it from there.

HTTP server (for web clients or custom frontends):

make serve

Python API (embed lorekit in your own application):

from lorekit.orchestrator import GameSession

session = GameSession()
await session.start()
async for event in session.send("I search the room for traps"):
    print(event.content)

Project Structure

lorekit/
├── cruncher/                 Pure rules engine (pip install lorekit-cruncher)
│   └── src/cruncher/
│       ├── formulas.py       Expression parser + evaluator
│       ├── stacking.py       Modifier stacking resolution
│       ├── system_pack.py    SystemPack loader (JSON → dataclass)
│       ├── engine.py         Derived stat computation (topo-sorted)
│       ├── build.py          Data-driven character construction
│       ├── dice.py           Tabletop dice notation
│       └── types.py          CharacterData, error types
│
├── src/lorekit/              Full game engine (pip install lorekit)
│   ├── server.py             MCP server — 51 tools for the GM agent
│   ├── providers/            Agent provider abstraction
│   │   ├── base.py           StreamChunk, GameEvent, AgentProcess, AgentProvider
│   │   └── claude/           Claude CLI provider (JSONL parser, process management)
│   ├── config.py             Platform-aware TOML configuration
│   ├── orchestrator.py       GameSession — public Python API
│   ├── http_server.py        HTTP + SSE server (optional, requires lorekit[server])
│   ├── rules.py              DB glue: load → cruncher → write back
│   ├── combat/               Action resolution, conditions, turn lifecycle
│   ├── encounter.py          Zone-based positioning, movement, initiative
│   ├── rest.py               Rest rules orchestration
│   ├── character.py          Character CRUD
│   ├── db.py                 SQLite schema, migrations, utilities
│   ├── npc/                  NPC agent subsystem
│   │   ├── memory.py         Park+ACT-R memory scoring
│   │   ├── combat.py         NPC combat decision orchestration
│   │   ├── reflect.py        LLM-driven reflection generation
│   │   ├── prefetch.py       Deterministic context assembly
│   │   └── postprocess.py    Response parsing + state extraction
│   ├── narrative/            Session & story state
│   │   ├── session.py, story.py, timeline.py, journal.py
│   │   ├── time.py           Narrative clock
│   │   └── region.py         Hierarchical regions
│   └── support/              Persistence & search
│       ├── checkpoint.py     Branching save/load with compression + deltas
│       ├── export.py         Human-readable session export
│       ├── recall.py         Hybrid semantic + keyword search
│       └── vectordb.py       sqlite-vec embeddings
│
├── systems/                  Game system packs (JSON, separate licensing)
│   ├── pf2e/                 Pathfinder 2e Remaster (ORC)
│   └── mm3e/                 d20 Hero SRD 3e (OGL 1.0a)
│
├── guidelines/               Agent guidelines (GM, NPC, shared)
├── tests/                    1010 tests (unit/ + integration/)
├── examples/                 Reference client implementations
│   └── tui/                  Terminal UI (TypeScript/React/Ink)
├── Makefile                  Common tasks (tui, serve, test, lint)
└── ~/.config/lorekit/        Default data location (db, config.toml)

Game Systems

LoreKit ships with two system packs under systems/:

| Directory | System | License | |-----------|--------------------------|----------| | pf2e | Pathfinder 2e Remaster | ORC | | mm3e | d20 Hero SRD (3e) | OGL 1.0a |

System packs are pure JSON. The rules engine is domain-agnostic: it only knows variables, formulas, tables, and constraints. All domain logic lives in the system pack files and the data-driven build engine.

Each pack ships a test_config.json alongside system.json so the parametrized test harness can exercise the full combat flow, rest, initiative, HUD, and encounter templates for that system. Packs without a config trigger a pytest warning.

System data is NOT covered by the project's Apache 2.0 license. Each system's data is governed by its own license, found in the LICENSE file within that system's directory.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: matluz1
• Source: matluz1/lorekit
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.