"Your favorite character shouldn't live only in a chat window."
Take them into a full world: dice decide what succeeds, rules keep it honest, and what you live through together leaves marks. You adventure together, fail together, and see the story through to the end.
Neither of you knows the script — you create the story together.
Loreweaver is an open-source AI Game Master: you and your friends bring the characters — including the companion cards you already love — and the AI Keeper runs the table. It reads the module, remembers the world, plays every NPC and guards every clue — you just sit down and say what you do. What separates it from "chatting with an AI" is simple: the dice are real. Checks, damage, sanity — all rolled and resolved by code, and the AI's only job is to tell the result as a story. The AI tells the story. The code keeps the score.
Ships with Call of Cthulhu 7e and D&D 5e (SRD), speaks English and Chinese, and the server runs on your own machine.
Links: Homepage · Command manual · GitHub
Honestly: this project is young, built mostly by one person working with AI. The dice and rules core is the solid part, watched by a full offline test suite; the terminal client is comfortable now. Networked multiplayer and AI-GM reliability are still being polished — what works and what doesn't is spelled out in the roadmap.
Real session, real model, real dice — recorded in the terminal client. (There's also a session played in Chinese.)
Install the client, click the green button on the connect screen — "Host locally & play" — and that's it. There is no step two.
It downloads the server build for your OS (self-contained — no Python, no environment setup), starts it, issues your Keeper key, and drops you into the main menu as the Keeper. We've verified the whole path from clean installs of Windows 10/11, macOS (Apple silicon), and Linux.
No API key needed to taste it: with no model configured, a Keeper in an empty room sees Play sample adventure. A built-in scripted Keeper loads the included lighthouse scenario and drives the real dice/rules pipeline. The server rechecks that the room is empty before loading it, so a stale menu cannot overwrite a campaign. Add a provider on the model screen whenever you are ready; the live server switches immediately and restores that choice after restart.
Installing the client is one line. macOS / Linux:
curl -fsSL https://github.com/1A7432/loreweaver/releases/latest/download/install.sh | bashWindows (PowerShell):
irm https://github.com/1A7432/loreweaver/releases/latest/download/install.ps1 | iexTo keep the client and one-click server state out of your user profile, set the folders before installing. The connect screen also shows the current local server folder and lets you edit it before clicking Host locally & play:
$env:TRPG_HOME="D:\Loreweaver"
$env:TRPG_LOCAL_SERVER_HOME="D:\Loreweaver\server-state"
irm https://github.com/1A7432/loreweaver/releases/latest/download/install.ps1 | iexFor one-click hosting, put the server .env in the selected local server folder; data, keys, the
ticket, and the server binary/source cache live there too.
On Windows, run the TUI in Windows Terminal or WezTerm. If the screen does not look
like the screenshots — broken borders, wrong colors, bad Unicode, or mouse input not working —
you are probably in the legacy console host. Windows 11 machines can still open the old console
depending on how cmd.exe / PowerShell is launched or configured. Install/open
Windows Terminal
or WezTerm, then run loreweaver there.
Once installed:
loreweaver # start it, click the button
loreweaver update # upgrading is one line tooNeed a known older build? Pick a tag from GitHub Releases, then run the installer with TRPG_RELEASE_TAG=release-...; the client tarball and one-click local server binary will both come from that same release.
Release installers verify the client archive's SHA-256 before extracting it, and one-click hosting does the same for the server archive. The official npm registry is the default; TRPG_REGISTRY remains available when you deliberately want a mirror.
The server builds are also yours to take and run long-term on a machine of your own: GitHub Releases currently has loreweaver-server-* for Windows x64, macOS arm64, and Linux x64/arm64 — unzip and run, with a --doctor self-check built in.
Once you're hosting, your screen shows two things: a ticket (a p2p address) and a Keeper key. Rooms and invites live in the main menu under "Rooms & invites" — one invite code per friend.
On their side: install the client (the one-liner above), paste your ticket and their invite code, pick a nickname, done.
No domain, no TLS certificate, no port forwarding. Connections are p2p (Iroh — QUIC with NAT hole-punching, relay fallback, end-to-end encrypted); the ticket is stored locally and survives restarts — share it once, it works forever. There are no accounts: the invite code is the entrance ticket. Dropped connections reconnect on their own and pick up where they left off.
A Keeper key is an administrator credential for its room: it can read Keeper-only material and manage that room's invites, while model/provider settings affect the whole deployment. Give Keeper keys only to people you fully trust.
Existing tools come in two kinds: dice bots (SealDice, Avrae) — great dice, nobody runs the story; and character-card chat (SillyTavern) — lively talk, but no rules, no world, and you can never fail. Loreweaver fills in what both sides are missing:
| Real dice/rules | AI Game Master | Persistent world + story | AI party members | Self-hosted · p2p with friends | |
|---|---|---|---|---|---|
| Dice bots | ✅ | ❌ | ❌ | ❌ | ~ |
| Character-card chat | ❌ | ~ | ❌ | ~ | ~ |
| Loreweaver | ✅ | ✅ | ✅ | ✅ | ✅ |
(The "~" in the last column: dice bots self-host but play through QQ/Discord-style platforms; character-card chat self-hosts but is fundamentally single-player. Loreweaver's server runs on your own machine, and friends connect directly over p2p.)
Fair warning: how well the AI runs a table depends a lot on the model's capability. Models that follow instructions well roll honestly and stick to the module; weak ones tend to talk instead of roll and wander off script. See For developers for picking one.
- Four ways to make a character: roll one up, fill it in by hand (the UI blocks over-budget stats as you type), describe a persona and let the AI draft it, or drop in a SillyTavern card. Whichever path you take, the rules check the result — if the numbers don't validate, no amount of AI charm gets them through.
- Keyboard and mouse both work. A spinner shows when the KP is thinking, so you're never staring at a frozen screen; the top bar keeps the scene, in-game clock, round, a connection light, and token/cache spend in view; dropped connections reconnect on their own.
- Invites, model switching, module import, and KP-skill management are the Keeper's business — those screens only appear when you connect with a Keeper key.
- Looking for a command? The full reference — dice, checks, character sheets, Keeper commands — is the player command manual.
- The AI actually runs the game — it isn't just chatting. Rolling dice, reading character sheets, taking notes, advancing the clock: all real engine operations, via 60+ Keeper tools. Many OpenAI-compatible and native providers work; model capability still matters, and
deepseek-v4-prowith thinking is the current recommendation. - NPCs don't get X-ray vision. NPC and companion actors are assembled only from their own record and sheet, never from the Keeper pool. The main Keeper is different: it sees module secrets so it can run the mystery, and live-model leak resistance is measured rather than claimed as an architectural guarantee. Short a player? An AI companion can fill the seat with its own sheet and rolls.
- Ask for it, and it exists. New rule systems, new play styles, new modules: describe what you want on an admin screen and the KP authors, validates, and installs it on the spot. Everything it writes is a portable format (SillyTavern cards, worldbooks, SKILL.md, YAML rulepacks) — and your old collection walks right in through the same door. Details in docs/plugins.md.
- Romance keeps books too. With the romance KP skill enabled, affection and desire are actual numbers: when they move, they moved — tracked by code, not by the AI's mood.
- Both command dialects work. The Chinese SealDice style (
.ra 侦查,.st 力量50) and the English Avrae style (/roll 4d6kh3,adv/dis) drive the same dice engine. - Content filtering is off by default. Your private table plays how it wants; if you do enable it, it filters only the KP's output, never player input (see docs/deploy.md).
uv sync # environment + dependencies
# Optional mock-tested chat adapters (QQ/OneBot need no extra):
uv sync --extra discord --extra telegram --extra feishu
# Taste it offline first — no API key needed, built-in demo KP + real dice:
uv run python -m app --cli # try r 3d6+2 · /roll 4d6kh3 · .ra spot hidden · .setcoc 2
# Plug in a real model: copy .env.example to .env, add your key, run again:
uv run python -m app --cli
# (No uv? python3 -m venv .venv && . .venv/bin/activate && pip install -e ".[dev,anthropic,gemini]").env looks like this (DeepSeek shown; any OpenAI-compatible or native provider works the same way):
TRPG_LLM__PROVIDER=deepseek TRPG_LLM__API_KEY=sk-…
TRPG_LLM__CHAT_MODEL=deepseek-v4-pro TRPG_LLM__REASONING_EFFORT=high
Don't cheap out on the model. The KP does everything through tool calls: strong models (deepseek-v4-pro with thinking, GPT-4-class, Claude) roll real dice and stick to the module; bargain models love to say "you succeed" without ever rolling, and tend to derail the campaign. Switch models mid-game with
.model set <provider> [model]— no restart.
The terminal UI (the real experience):
uv run python -m app --serve # start the p2p server; prints a ticket + Keeper key
# in another terminal:
cd clients/tui && bun install && bun run devPaste the ticket and key into the connect screen. Or skip all of it: click "Host locally & play" and the client does the whole dance for you.
Most tables run p2p off a laptop. For a 24/7 server, pick a machine:
uv sync && uv run python -m app --serve # keep it alive with systemd — see docs/deploy.mdAt startup Loreweaver reads .env if you created one; it does not invent provider credentials. A missing keystore does cause the server to issue a Keeper key automatically (printed and saved to keeper-key.txt). Connect with it; invites and rooms are managed from the client after that. SQLite campaign data follows TRPG_DATA_DIR; the keystore follows --keys / TRPG_TUI_KEYS (default ./keys.toml). Full guide: docs/deploy.md.
| Entry | Status |
|---|---|
| Terminal · OpenTUI | ✅ Primary — the game lobby above; local or networked p2p (Iroh) |
| Discord bot | 🧪 Experimental — native commands, cards, attachments, panels, and voice |
| Official QQ bot | 🧪 Experimental — Markdown/Keyboard and rich-media with plain-text fallback |
| Telegram bot | 🧪 Experimental — polling, topics/replies, media, inline controls, and DMs |
| Feishu bot | 🧪 Experimental — supervised long connection, mentions/threads/replies, media, and plain-text card fallback |
| OneBot 11 | 🧪 Experimental — forward/reverse universal WebSocket, message segments, media, and DMs |
| CLI (headless) | ✅ Development / quick testing / offline demo |
Systems: D&D 5e SRD and CoC 7e ship as data-driven rulepacks (rulepacks/*.yaml) — adding a system requires no code changes. Every network adapter above can share the same cross-platform rooms, but all remain mock-tested Experimental until their real-platform checklist passes. OpenTUI remains the primary way to play; see the chat-platform setup and smoke checklist.
core/ deterministic engine infra/ store · config · i18n · llm · embeddings · vector · providers
agent/ AI-KP brain + tools gateway/ platform-independent: commands · ops · hub · runner · director
net/ Iroh p2p + session core adapters/ CLI · Discord · QQ · Telegram · Feishu · OneBot clients/ protocol · tui
The engine isolates all state behind a stable chat_key; RoomHub layers cross-transport realtime broadcast on top. Layer contracts, the iron rules (deterministic vs. generative, dice-first, information isolation), and how to add rulepacks / adapters / providers / tools / clients: AGENTS.md. Client wire format: docs/protocol.md.
uv run pytest -q # offline: FakeLLM + seeded dice, no network, no keys
uv run ruff check core infra agent gateway net adapters app.py scripts
uv run python scripts/i18n_lint.py # no hardcoded user-facing strings
cd clients/tui && bun install && bun test # clients (protocol · tui)More than 1,000 tests run fully offline and reproducibly. A self-play test drives the entire pipeline with a scripted Keeper (upload module → analyze → start → player actions → real dice checks → battle report). Dedicated red-line tests prove that Keeper-only data never enters the player knowledge pool and that NPC/companion actors are assembled only from their own scoped records. They do not prove that the main Keeper model will never repeat a secret it was shown.
Offline tests prove the pipeline; whether a real model behaves is a separate question, measured by a nightly real-model red-line eval. Scripted players run against the configured model and each turn is scored for secret leakage and missed dice-first behavior; threshold violations, provider failures, and authentication failures make the run red. Results are per model and per run, not a permanent guarantee: for example, the 2026-07-07 run measured one short-run leak in 24 turns and one missed roll in six checkable turns, while its long run measured zero of each; the next two scheduled runs failed before evaluation because the provider rejected the credential. The workflow skips when EVAL_LLM_API_KEY is absent and never blocks PRs. Push/PR CI covers Python 3.11/3.12 and the client packages fully offline.
PRs and issues welcome. Before submitting, get these green: uv run ruff check …, uv run python scripts/i18n_lint.py, uv run pytest -q (plus the relevant bun test). Respect the iron rules in AGENTS.md — above all: every user-facing string goes through i18n, and information isolation is never broken. Rules content must be openly licensed (SRD / Miskatonic Repository); bring your own modules at runtime. Where help is needed most is listed in the roadmap.
The roadmap states the ambition plainly: to be the Claude Code of RPGs — right down to the shared terminal-first aesthetic.
Self-hosting keeps the deterministic engine, campaign database, keys, and files under your control. It does not automatically make model traffic local. A remote LLM receives module text during analysis, the Keeper system prompt (including Keeper-only lore), relevant history, and the current player input. The standard app uses a local hash embedder; an explicitly wired remote embedding backend would also receive document chunks. Use a local endpoint such as Ollama or LM Studio if those prompts must stay on infrastructure you control. Iroh's end-to-end encryption protects OpenTUI player-to-server transport; it is a separate boundary from the model provider. Discord, QQ, Telegram, and Feishu traffic necessarily traverses those platform services, while OneBot follows the security of its configured WebSocket link; see the deployment trust model.
Provider API keys and OAuth grants are stored unencrypted in the local SQLite database so runtime configuration survives restart. New secret files and dedicated data directories are restricted to the local owner where the filesystem supports POSIX modes, but this is not a secret vault: protect the host account, backups, .env, keys.toml, keeper-key.txt, and *.db, and never commit them. See the full data-flow and deployment trust model.
There is no account-recovery or central identity service: a random key is the credential, binding its holder to one room with a player or Keeper role. Iroh already encrypts and authenticates the p2p connection; the operational risk is leaked keys or a compromised host, not a missing reverse proxy certificate. Revoke lost keys and treat every Keeper key as a trusted administrator for its room and for deployment-wide model configuration.
Found a vulnerability? Open a private security advisory on GitHub, not a public issue.
MIT — see LICENSE and NOTICE. Includes D&D 5e SRD 5.1 (CC-BY-4.0) material; Cthulhu content only within open / Miskatonic Repository licensing. The gateway/adapter layer derives from hermes-agent (MIT, © 2025 Nous Research); the dice engine is avrae/d20 (MIT); the Chinese command dialect, CoC success function, and skill alias table are rewritten with reference to SealDice (MIT); the terminal client is built on OpenTUI. No copyrighted adventure/module text ships in this repository.
Community link: LINUX DO — a community we call home.
The full plan: docs/roadmap.md. Further out: a living world engine (generative worlds, a causal timeline, setting consistency), story catch-up for late joiners, D&D Beyond character import, and end-to-end testing of the chat adapters against real platforms.