Mythras GM · Claude Code & Codex
Run Your First Session
Claude as your Gamesmaster, running Mythras Imperative with a real dice engine and every wound, faction and journal entry persisted in a knowledge graph. This page takes you from nothing to an open scene — and tells you how to check each step actually worked.
Before You Start
Three things. Two of them you probably already have.
Native builds cover macOS and Linux on x86_64 or arm64, and Windows on x86_64. Anywhere else,
the engine can run its database under Docker instead — see /mythras-gm:setup.
Install, One Step at a Time
Install the engine explicitly and first. Campaigns declare it as a dependency, but do not rely on that resolving for you — when it silently doesn't, the campaign's own diagnostics go down with it, and you get a plugin that simply isn't there rather than an error.
-
Add the marketplace
One source holds the engine and every campaign.
/plugin marketplace add fourth-wall-gaming/mythras-gmConfirmThe marketplace lists four plugins:
mythras-gm,purewater,veilwrackandfirst-through. If you see fewer, stop here rather than continuing. -
Install the engine
This is the dice tower, the rules graph and the save file. Nothing else works without it.
/plugin install mythras-gm@fourth-wall-gamingConfirmmythras-gm appears in your installed plugins. Do not move on until it does.
-
Install a campaign
Pick one. Purewater is a Classic Fantasy port — a canal city, three days before a tournament.The Veilwrack is an original sky realm — winged peoples on floating bone-spires, and the wind is dying.First Through is science fiction written for a first-time player — instant doors between real stars, and only the young can use them. You can install both and keep two saves side by side.
/plugin install purewater@fourth-wall-gamingConfirmBoth mythras-gm and purewater are installed. Two plugins, not one.
-
Start a fresh session and read the first line
Both plugins check the game at session start, so quit Claude Code and open it again. The preflight tells you exactly where you stand — it never imports anything and never blocks the session, so whatever it says is safe to act on.
Confirm — one of these…installed but has not been imported into the database yet— expected on a first run. Continue to step 5.the mythras-gm engine is not installed— step 2 didn't take. Run it again.PREFLIGHT FAILED — uv is not installed— install uv, then start another session. -
Open the scenario
This imports the campaign, briefs you on Mythras if you're new to it, walks you through choosing or rolling a character, and opens the first scene. Run it once, ever.
/purewater:startConfirmYou are asked whether you've played Mythras before, and then offered characters. If instead the narration simply begins, something didn't import — see below.
-
Every session after that
One command, forever. The preflight will have already told you the clock and session number.
/mythras-gm:playConfirma game is in progress— with your campaign's clock and session number. Never run the start command again; it is only for a campaign that has not begun.
Playing in ChatGPT or Codex
The same plugin runs in Codex. One thing to settle first, because it decides where you can play at all: this cannot run in ChatGPT on the web or on your phone. The Gamesmaster needs a real dice engine and a real database on a real machine — a command line, a local TypeDB, and a startup check that runs before the first scene. None of that exists in a browser tab, plugin startup checks don't run in cloud-orchestrated ChatGPT Work, and installing a plugin on the web doesn't put its scripts on any machine.
So: the ChatGPT desktop app, or the Codex CLI. Both run locally, which is the whole requirement.
-
Add the marketplace
In the desktop app, open Plugins and add it. From a terminal:
codex plugin marketplace add fourth-wall-gaming/mythras-gmIf a dialog asks for a Git Ref or Sparse Paths, leave both blank. A ref pins the catalogue to one branch, and a sparse checkout would fetch the catalogue while leaving the engine behind.
Confirmcodex plugin marketplace listnames it. If it doesn't, the error it prints is the real one — act on that rather than on the install failing later. -
Install both plugins — the engine will not come along by itself
In Claude Code a campaign pulls the engine in as a declared dependency. Codex does not do that: its plugin format has no dependency field, so a campaign installed on its own is a campaign whose first act is to tell you the engine is missing, on a machine where nothing else is wrong.
codex plugin add mythras-gm@fourth-wall-gaming codex plugin add purewater@fourth-wall-gaming -
Approve the startup check
Codex will not run a plugin's startup check until you have reviewed it — open
/hooksand trust both. Until you do, the check never runs, so the database is never started and the skills have no engine to talk to. This looks exactly like a broken save file and is not one. -
Let it keep a save and fetch its database
Codex sandboxes what a session may write and whether it may reach the network. The game keeps its save outside your working folder and downloads its database once, so both need allowing in
~/.codex/config.toml:[sandbox_workspace_write] network_access = true writable_roots = ["~/.mythras-gm", "~/.claude/mythras-gm"]Or ask the agent to make that change for you — it can read and edit that file. Either way you need a fresh session afterwards, because a config change doesn't reach a running one.
-
Start a fresh session, then check before you play
Skills only appear in a session opened after an install. One command tells you whether this machine can run the game, and names what to do about anything that can't. It changes nothing — no installs, no downloads, no writes.
bash ~/.codex/plugins/cache/*/mythras-gm/*/scripts/verify-install.shConfirmEvery row
ok. Watch thecampaignrow in particular — that one is the campaign finding the engine, which is the part that differs between the two hosts.And the session should open with a
mythras-gm readyline naming an absolute path, plus a line from the campaign. If neither appears, don't start a game — nothing would be saved. -
Then play
There is nothing to type. Codex has no slash commands, so the entry points are skills: ask to play, or name the
purewater-startskill for a first run andmythras-playto resume. The steps are the same as above; only the way you reach them differs.
Where Your Save Lives
The files in a campaign plugin are a scenario seed, not a save. The moment you run the start
command, the database becomes the game — and the database is on disk, at
~/.claude/mythras-gm/typedb/data.
That path is the campaign, and it persists for as long as the disk does. Close the laptop, come
back in a month, pick up mid-scene. If you would rather keep it somewhere you actually back up,
set MYTHRAS_TYPEDB_HOME — the server binary, its log and the data directory all
move together, because a data directory that outlives its binary is just another way to lose
the save.
This is a local game. The engine is brought up by a SessionStart hook, and that
hook does not fire in hosted or disposable environments — so nothing creates the database,
and there is no save to come back to.
When Something Is Wrong, It Will Be Quiet About It
The characteristic failure here is not a crash. It's a database that isn't there, or a schema that never loaded, while the game carries on narrating over the top of it. Learn the tells.
- Nothing is printed at session start. Both plugins always say something; silence means neither hook ran.
- The GM narrates straight into a scene without offering you a character.
- A wound, a spent luck point or a journal entry from last session has quietly reverted.
- Dice results appear in the prose but no roll is reported.
One command answers all of them. It checks the install end to end and reports every stage as pass or fail, in order:
/mythras-gm:setup Every check reads true, ending in Ready. Any check that reads false is named, with the reason attached.
Three Campaigns, and a Word About Spoilers
And Then the Dragons Came: Purewater
A canal city where the Lake Lady's waters meet the sea. Baron Hanzo di Teufel has arrived for the Tourney with a champion nobody is allowed to see, and there are three days left before it all goes wrong.
4 entry points · 42 characters · 15 agendas on clocksThe Veilwrack: The Stilling
No ground — an endless sky above the toxic Undermist. The winged Alar live on the floating bone-spires of dead sky-leviathans, and Lanternfall's windlane began Stilling this season. Nobody has said the word aloud yet.
4 spires · 7 factions · 3 playable AlarFirst Through
Instant doors between real stars, and only the young can use them, so the whole traffic of human space rides on fifteen-year-olds. Written for ten- to fifteen-year-olds, with no pre-made characters — you build your own at the table in about twenty minutes.
6 cultures · 6 careers · Act One in one sittingDon't browse the campaign repositories. They are the published source of the scenario, so they hold the Gamesmaster's material — the secrets, the timeline and who everyone actually is. Much of it is marked GM-only, but not all of it, and a scenario is easy to spoil by accident. Every world here is built so that what you don't witness happens anyway, which only works if you haven't read ahead.
Purewater and First Through each publish a Players' Guide written for exactly this: everything your character already knows, and nothing your Gamesmaster needs. Read those instead — Purewater's and First Through's.
Love the System? Buy the Books
This runs on the Mythras Imperative SRD under the ORC License. The Design Mechanism publishes the full Mythras line — get the real thing and play it at a real table too.