magehand — Local RAG Assistant for Tabletop Game Masters

Answers rules questions from your own books and keeps track of your campaign. Runs against a local model or a hosted one.

ROLE: Solo — design and engineering
PERIOD: 2026 – Present
RUNS FULLY OFFLINE: Local
STACK: Rust, RAG, Local LLMs (Ollama), OpenRouter, whisper.cpp, WebRTC

Source on GitHub

THE PROBLEM

Running a campaign means holding two things at once. The rules are thousands of pages you can't search while four people wait. Your own canon lives in scattered notes and in your head. A general chatbot is bad at the first, since it will invent a rule and sound sure about it, and useless at the second, since it has never read your notes.

WHAT I BUILT

Indexes your rulebooks and your campaign vault locally. Answers quote the passages they came from and cite them, so they're checkable.
Campaign state is a plain-markdown Obsidian vault that magehand reads and writes. If the tool disappears the notes are still notes.
Record a table ruling once and later answers lead with your version rather than arguing with it.
Player mode restricts retrieval to player-visible sources. A per-player secret ledger keeps one player's briefing from leaking another's.
Live mode transcribes game night locally and shows entity cards matched against your vault, with no model calls while you play. Afterwards a cleanup pass writes a draft. You read it and promote it. Nothing enters canon on its own.
A dashboard for the tablet behind the DM screen: open threads pinned at the top, rules and trigger cards as they happen, and one-tap actions that save a ruling or open a thread. Nothing writes to the vault without a tap.
Players join from a phone by scanning a QR code, with no app and no account. They get a live character sheet, spoiler-safe rules questions, their own secrets and the latest recap, a shared map, and a private line to the DM. Online play adds in-page voice, with one stream per player so the transcript is speaker-labelled by construction.
Runs against a local Ollama model or a hosted one through OpenRouter. The offline path is a real option, not a degraded one.

OUTCOME

Rules answers that quote the actual text and cite it, instead of sounding right.
Continuity that survives between sessions: open threads, debts, NPCs and an in-world calendar, all tracked.
Nothing enters canon without review, and the whole thing runs with no network.

SCREENSHOTS

A terminal running 'magehand ask does grappling stop opportunity attacks?'. The answer gives a ruling in three numbered cases, then a 'Reasoning & Section References' block where each point cites the exact rulebook file and section it came from. — `ask` gives a ruling, then the sections behind it, cited down to the file. You can go check it.

A terminal running 'magehand search opportunity attack', listing scored retrieval hits. Each result shows a relevance score, a RULEBOOK tag, the source file and section, and an excerpt of the matching passage. — `search` shows the raw retrieval behind an answer, scored and sourced. No model call, so it's instant.

The magehand DM dashboard in a dark theme: a party strip along the top with each character's hit points, armour class and conditions, a row of open thread chips beneath, then a feed of cards. A whisper from a player asking about a fake shard, a rules card answering whether grappling stops opportunity attacks with the house ruling beneath, and a trigger card for an open thread, each with Save ruling, Open thread or Dismiss buttons. — The dashboard mid-session. Whispers, rules disputes and thread triggers arrive as cards, and each has one tap to file it.

A join page headed 'Scan to join, one code per player', with four cards side by side, one per character, each holding a QR code and its capability URL. — One QR code per player. Scanning it is the login: no app, no account, and the link only opens that player's page.

A player's phone page for Mira Quickfingers on the Sheet tab: hit points 9 of 22 with large minus and plus buttons, a row of condition chips with poisoned highlighted, then class, level, armour class, speed, proficiency and ability modifiers each with their own plus and minus. — The sheet is the two dozen numbers that change at the table, with buttons big enough to hit mid-combat. Everything else stays prose in the vault.

The same phone page on the Ask tab. The player asked whether they can sneak attack with a thrown dagger while hidden. The answer explains the finesse and thrown properties, lists three SRD sources, and ends with a note to ask the DM to be sure. — A player's rules question, answered from player-visible sources only and footed with a reminder that the DM has the last word.

The Stuff tab: a 'Previously' recap paragraph, then a 'Just for you' section listing two dated secrets this character alone knows. — Recap plus this player's own secrets. The token scopes retrieval on the server, so nobody else's ever loads.

The DM tab on the phone: a private chat where the player says they plan to slip Halia a fake shard and asks if she can tell, and the DM replies that she will test it against her own piece. A whisper box and Send button sit beneath. — Whisper to the DM. Pass a note across the table without the table seeing it.

The DM dashboard's Map view: a hand-drawn dungeon floor plan with lettered tokens for characters, goblins and a hound, plus controls to upload a map, add a token and a hint that players move only their own. — The shared map. The DM drags anything, players drag only themselves.