Taru (Finnish: tale, saga, myth) is an instrument for discovering worlds and characters by playing them, with an LLM on one side of the table. Not a game engine: a space. The good stuff comes from the world and the characters.
Two modes, one folder of state:
- Mode A — you play a character; the model runs the world (
engine/GM.md). - Mode B — you run the world; the model inhabits a character (
engine/PLAYER.md).
The loop: scene → distill → back room → next scene. Scenes are pure fiction, no bookkeeping. Distill (engine/DISTILL.md) saves the verbatim transcript, fixes new canon, ages the threads, and regenerates the state card — the small artifact that lets scene 041 remember scene 003. Between scenes, the back room (engine/BACKROOM.md) reconciles the hidden world and preps the next director's notes behind the GM screen. Short scenes; long story.
Everything is plain Markdown, so this runs on any model: hand it engine/GM.md plus the world's state-card.md, seed.md, the active sheets, and the last scene's footer — that bundle is the engine. In Claude Code, open this folder and say scene in qelan (the commands live in CLAUDE.md; AGENTS.md is its identical twin for other agents).
engine/ the constitution — GM, player, distill, back room, worlds, settings
worlds/qelan the example play: Qelán (The Sealed Radiance) — seed, canon,
character sheets, and the verbatim transcripts of every scene
CLAUDE.md operating instructions (Claude Code); AGENTS.md is its twin
setup.sh makes a fork yours — see "Your own instance" below
CHANGELOG.md what changed between tagged versions
Seven scenes and one branch, played July 2026, Mode A. The transcripts are in worlds/qelan/scenes/, verbatim, each with a footer (summary, new canon, threads, open questions). Reading them in order is the best introduction to what this instrument does.
| Scene | Title | Notes |
|---|---|---|
| 001 | the man who walked out | bare play — no back room yet |
| 002 | the first night | bare play |
| 003 | the latch | first briefed scene; its Take A sits in scenes/branches/ — same opening played twice, once bare and once with the back room, to decide whether the back room earned its rent (it did) |
| 004 | the rain | |
| 005 | the fourth night | |
| 006 | qam | |
| 007 | the greying |
Conventions you'll see in the transcripts: ⭐ marks a line precious (preserved verbatim if the scene ever becomes prose); a line starting // is marginalia — the author thinking alongside the character, which the fiction never acknowledges; [table: …] is the one channel where the table itself may speak.
The GM's screen is not in this repo. worlds/qelan/gm/ — the hidden-world hypotheses, the arc in pencil, the director's briefings — is sealed while Hannu is still playing, and will be published as an afterword when book one cuts. What you see in worlds/qelan/ is exactly what the player's side of the table sees. (One small redaction beyond that: character sheets travel without their secret: line — that framing is the screen's.) The world's scripture — the worldbible, the Sahíric language document, and The Codex of Degrees — is mirrored in worlds/qelan/sources/. The true documents are the GM's physics: reading them is a Mode-A player's choice, and the game is better if the Codex (believed — what everyone in-world knows) is what you know.
The world's voice.md is worth special attention: it is the table's prose style, grown ruling by ruling from actual play — each ruling cites the margin note that earned it. The transferable core of those rulings has been folded back into engine/GM.md, so new worlds start with the voice this one had to learn.
Instances are meant to be sovereign: your table, your worlds, your hidden state, no upstream. The fastest path:
- Make your own repo from this one. On GitHub: Use this template → create your repo (private is sensible — your future
gm/folders hold your story's secrets). A plain fork or a clone pushed to a fresh repo works the same. - Make it yours:
./setup.sh "Your Name"— replaces the operator's name in the engine and operating instructions (never in the Qelán play record), so the table addresses you. The engine files are now yours to edit; they are the constitution, and the constitution is meant to be amended by its player. Adjust pronouns inengine/GM.md/engine/PLAYER.mdto taste. - Sit down. Open the folder in Claude Code and pick a door:
Door one — Qelán, from the beginning (the recommended first play). Say rebirth qelan. The world returns to the morning before its first scene and opens on the same image the played line began with: the Sealed One walking out of cracked Berzhár, with no memory (the seed marks this default — diegetically the story can't start earlier, since the waking burns away the memory of it; play begins where his remembering does). A fresh back room authors its own hidden world, so your saga and Hannu's share only their physics and their first breath — and diverge by the second turn. The scripture in worlds/qelan/sources/ keeps your Qelán the same world; everything the screen would hold is your table's invention.
Prefer to inherit the played history instead? Say prep, then scene in qelan to continue from scene 008 — or branch qelan from scene <NNN> to rewind anywhere between (engine/WORLD.md §Branching). Two players from the same transcripts will discover two different stories; that is the instrument working.
Door two — a world from your own pages. If you already have material — a draft, a worldbible, fragments of a novel — the engine is built to eat it. Say new world <name>, then write worlds/<name>/sources.md: a short table pointing at your documents (paths inside the repo or anywhere on disk), each marked with a status:
- true — scripture. Physics; play never contradicts it.
- believed — an in-world text. It binds what people think, not what is; the gap between believed and true is the GM's playground.
- draft — rough scenes, sketches, fragments. Quarry: a soft pre-plot the GM mines for places, people, and beats, and that play freely retcons. Playing through a draft is the point — what survives contact becomes canon.
Then say absorb sources — the table reads the targets and proposes updates to the seed, the penumbra, and the open questions; scene-shaped drafts become unplayed scene seeds. (worlds/qelan/sources.md is the worked example of the format.)
Door three — a world from nothing. Say new world <name>. The birth ritual (engine/WORLD.md) asks for four things — one image, one law, one wrongness, five tone words — and play begins from there. Character sheets are born in play; nothing else is required.
Honesty about the doors: the first is the proven one — the seven played scenes came through that table. The other two are untested by anyone but the author (Hannu suspects the sources door will open smoothly). If you take one, your play is data; he wants to hear about it either way.
Requirements: Claude Code (or any agent harness that reads AGENTS.md). No other dependencies — the folder is the game.
If you play, Hannu would love to hear how it went — open an issue on this repo, or bring him the tale directly.
Branch freely, at every scale:
- Instances are whole independent games — template/fork per person, never merged.
- Lines within an instance: git branches (or worktrees) fork a whole alternate continuity from any scene — Qelán's scene 003 was played twice this way, and the losing take was kept whole on its own branch.
- What-ifs: for a single-scene fork, a
worlds/<w>/branches/folder with its own copies of the mutable files is enough — seeengine/WORLD.md.
Stories don't merge; ideas do. When a branch dies, its good inventions are harvested with provenance into the world's ideas.md (the quarry), where future prep can respend them. If you and another player want to trade discoveries across instances, trade quarry, not canon.
Tagged releases (v0.1.0, …) with a human CHANGELOG.md. The engine keeps evolving at Hannu's table; updates are published here from the private working copy (with gm/ and other sealed material stripped). To take an engine update into your instance without disturbing your worlds: pull or cherry-pick changes under engine/, CLAUDE.md, AGENTS.md — worlds are never touched by upstream.
The Qelán scenes were played with Claude (Fable 5) in Claude Code; every scene's YAML frontmatter records the model, effort, and prep that drove it — plays are attributable to the minds at the table. The engine itself is model-agnostic by design: same folder, different mind is an experiment, and differences are data.