Skip to content
Back to search

neural-initiative

SkillWorks with Claude CodeGitHubIncomplete

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 16 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/neuralinitiative/claude-dnd-skill with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/neuralinitiative/claude-dnd-skill'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/neuralinitiative--claude-dnd-skill/badge.svg)](/listings/neuralinitiative--claude-dnd-skill)

HTML

<a href="/listings/neuralinitiative--claude-dnd-skill"><img src="/api/listings/neuralinitiative--claude-dnd-skill/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Install it as a Claude Code plugin:

/plugin marketplace add neuralinitiative/claude-dnd-skill
/plugin install dm@neural-initiative

Then invoke it as **`/dm:dnd`** (plugin skills are namespaced `plugin:skill` — the `dm` plugin provides the `dnd` skill), or just describe what you want once a campaign is loaded. Update with `/plugin update dm`.

# Optional — install the display-companion dependencies (one-time).
# Core gameplay works without these; they power the live screen + audio.
pip3 install flask flask-cors numpy cryptography

> **Upgrading from a v1 standalone install?** As of v2.0.0 the skill is > plugin-only — the old `~/.claude/skills/dnd` standalone (`/dnd`) is replaced by > the plugin (`/dm:dnd`). **Your campaigns and characters are untouched** — they > live under `~/.claude/dnd/` (or `$DND_CAMPAIGN_ROOT`), entirely separate from > the skill code. Install the plugin above, then run the one-time helper to carry > over device pairings / TLS certs and retire the old install: > `python3 <plugin>/skills/dnd/scripts/migrate_v1_to_v2.py`. Full guide: > **[MIGRATING.md](MIGRATING.md)**.

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 21 lines
  1. {
  2. "name": "neural-initiative",
  3. "owner": {
  4. "name": "Neural Initiative",
  5. "url": "https://github.com/neuralinitiative"
  6. },
  7. "metadata": {
  8. "description": "Neural Initiative's Claude Code plugins.",
  9. "version": "1.0.0"
  10. },
  11. "plugins": [
  12. {
  13. "name": "dm",
  14. "source": "./",
  15. "description": "Dungeon Master assistant for persistent D&D 5e campaigns — campaign/character management, combat, NPCs, dice, an optional live display companion, and full session state across sessions.",
  16. "version": "2.7.0",
  17. "license": "AGPL-3.0-or-later",
  18. "keywords": ["dnd", "dungeons-and-dragons", "ttrpg", "5e", "dungeon-master", "game"]
  19. }
  20. ]
  21. }
README.md · README · 890 lines
  1. # Unofficial D&D Claude Dungeon Master
  2. ### *with Cinematic Display Companion — Couch Co-op Edition*
  3. > **Ruleset:** D&D 5e — **2014 (SRD 5.1)** by default; **2024 (SRD 5.2)** opt-in per campaign. Choose at `/dm:dnd new` time; legacy campaigns are auto-prompted to migrate (with backup) on first load. See the [Ruleset section](#ruleset) for mechanic differences and dataset details.
  4. <div align="center">
  5. <img src="skills/dnd/display/icons/logo_primary_fullcolor.png" width="280" alt="D20 Neural Core">
  6. </div>
  7. > Claude runs the game. You play. The TV shows the story. Your phone is your controller.
  8. An unofficial D&D 5e (2014 ruleset / SRD 5.1) Dungeon Master skill for [Claude Code](https://claude.ai/code) — persistent campaigns, full 5e mechanics, and an optional cinematic display companion that streams typewriter narration, dice rolls, and live character stats to any screen — TV via Chromecast, tablet, phone, or second monitor — while players submit their actions from a phone or tablet.
  9. Built for groups who want a real DM experience without needing one at the table.
  10. ![Cinematic Display Demo](screenshots/demo-v3.gif)
  11. ---
  12. ## What This Is
  13. You run `/dm:dnd load my-campaign` in Claude Code. Claude becomes your DM — rolling dice, voicing NPCs, tracking HP and XP, and running combat. If you have a TV or tablet nearby, the **cinematic display companion** puts the narration on screen in real time — typewriter effect, atmospheric backgrounds that shift with the scene, a dynamic sky canvas, and a live party stat sidebar. Open it on any device on your network and everyone at the table can follow along. Players submit their actions from their phones; Claude picks them up automatically and runs the next turn.
  14. There are two ways to play, and they serve different needs:
  15. **Improvised campaigns** — Claude generates the world from scratch and auto-creates a committed three-act narrative arc from the setting, factions, and threats it just built. The arc gives the story a defined shape without scripting what happens — beats are defined by consequence ("what changes") not by event, so Claude stays flexible on how each beat lands while committing to the fact that it must. The arc advances across sessions, can be revised when players redirect the story, and continues into a new arc when all six beats resolve. This is Claude as a full creative collaborator: world-builder, improv partner, and story architect in one.
  16. **Structured campaigns** — Use `/dm:dnd import` to drop in a pre-written source (official WotC modules, published third-party campaigns, or a custom DM-written document in PDF, markdown, DOCX, or plain text format). Claude reads and chunks the source, extracts the structure type (linear, hub-and-spoke, or faction-web), and builds all campaign files automatically — acts, chapters, key story beats, telegraph scenes, NPCs, factions, locations, and quest hooks. The campaign runs with enforced deterministic structure: required beats must land in each chapter, Claude telegraphs before delivering them, and steers with world pressure rather than walls when players drift. Drop in the Lost Mine of Phandelver and Claude will run it chapter by chapter with the same twelve DM standards applied to every scene.
  17. Both modes share the same DM engine. The [twelve applied behavioral standards](https://github.com/neuralinitiative/claude-dnd-skill/blob/main/SKILL.md#what-makes-a-great-dm--applied-standards) are enforced as hard constraints in every session regardless of which mode you're in — improvised or structured, the DM improvises within situations, lets choices matter, makes every NPC a person, and controls pace deliberately.
  18. It also manages a deep web of campaign data without overloading the LLM — coherent and complete, without burning tokens on context that isn't needed yet:
  19. - **DM instructions** — split across three files with staggered load timing; core rules always in the system prompt, script syntax and command procedures loaded once at session start
  20. - **Campaign data** — NPC roster indexed at load, full entries pulled only when a character becomes relevant; quest hooks and worldbuilding text in cold storage until called for
  21. - **Imported modules** — a published book is kept as a lazily-loaded corpus, not inlined: the act/chapter tree, quest/location bank, and per-chapter source text load on demand, so a long module runs chapter by chapter without sitting whole in context
  22. - **Session history** — archived as continuity summaries, not raw transcripts; full campaign history available for reference without front-loading token weight
  23. - **Compaction resilience** — a compact Live State Flags block in `state.md` anchors faction stances, player cover, and NPC dispositions; re-read at any claim to keep world continuity grounded in source files rather than Claude's increasingly lossy impression of them
  24. - **Autosave** — continuity (state flags, relationship graph, session tail) is checkpointed behind the scenes at scene boundaries and on a turn cadence, so a context compaction never loses your place; toggle with `/dm:dnd autosave on|off`, with an optional Stop hook for a deterministic per-turn backstop
  25. A campaign can run dozens of sessions deep — with coherent recall of past events, NPC attitudes, and long-tail consequences — without the context bloat that forces other implementations to summarize, forget, or reset.
  26. It is not an official Wizards of the Coast product. It uses Claude as the DM engine. It takes the rules seriously and the storytelling even more seriously.
  27. ---
  28. ## Using a different LLM?
  29. This skill is built specifically for Claude Code. If you want to run the same framework on a different model — local inference, OpenRouter, or any OpenAI-compatible endpoint — check out [open-tabletop-gm](https://github.com/neuralinitiative/open-tabletop-gm), the model-agnostic version extracted from this repo. It trades some Claude-specific integration depth for broader model support and includes a probe tool for benchmarking narration quality across models.
  30. If you'd rather skip the install entirely and play in a browser, [neuralinitiative.ai](https://neuralinitiative.ai) is the hosted version — same design DNA, sign in with Google, top up an account balance, play. Trades self-hosting (and lower per-session cost) for zero setup and a more refined GUI.
  31. If you're on Claude Code, you're in the right place.
  32. ---
  33. ## Features
  34. - <img src="skills/dnd/display/icons/scroll.png" height="18"> **Persistent campaigns** — state, NPCs, quests, and characters survive across sessions in plain markdown files
  35. - <img src="skills/dnd/display/icons/dragon.png" height="18"> **Two campaign modes** — improvised (Claude generates world + dynamic arc) or structured (import pre-written material and enforce its beats)
  36. - <img src="skills/dnd/display/icons/crystal_ball.png" height="18"> **Dynamic narrative arc** — auto-generated at `/dm:dnd new` from the world's threat, factions, and setting; three acts, six beats defined by consequence not event; arc tracked across sessions, revised when players redirect the story, continued into a new arc when complete
  37. - <img src="skills/dnd/display/icons/spellbook.png" height="18"> **Campaign relationship graph** — typed-edge graph alongside the markdown campaign files, with verbatim source-anchors on every edge; `scene-context` query auto-pulled at `/dm:dnd load` to surface who-knows-whom in the current scene without re-reading full NPC files; designed to hold long-session continuity when context compaction strips files out of scope. Background research and the A/B replay study that motivated it: [`docs/research/graph/`](docs/research/graph/)
  38. - <img src="skills/dnd/display/icons/pack.png" height="18"> **Campaign import** — `/dm:dnd import` accepts PDF, markdown, DOCX, or plain text; extracts structure type, acts, chapters, key beats, telegraph scenes, NPCs, factions, and quest hooks; builds all campaign files automatically and keeps the full source as a lazily-loaded corpus so even a long module loads chapter by chapter
  39. - <img src="skills/dnd/display/icons/helmet.png" height="18"> **Portable characters** — bring your character into any campaign; level up, grow your stat tree, and carry your inventory and loot — or start fresh each time
  40. - <img src="skills/dnd/display/icons/attack.png" height="18"> **Full D&D 5e mechanics** — initiative, attacks, saving throws, spell slots, XP, levelling up, short/long rests
  41. - <img src="skills/dnd/display/icons/chat.png" height="18"> **Atmospheric DM** — dark fantasy tone, distinct NPC voices, hidden rolls, a world that reacts to choices
  42. - <img src="skills/dnd/display/icons/crystal_ball.png" height="18"> **Cinematic display companion** — typewriter narration on your TV, scene-reactive backgrounds, dynamic sky canvas, live party sidebar; cast, mirror, or open on any screen on your network
  43. - <img src="skills/dnd/display/icons/location.png" height="18"> **Dynamic sky canvas** — sun arc, moon, twinkling stars, and cloud density rendered in real time from world time data; transitions with time of day and weather
  44. - <img src="skills/dnd/display/icons/focus.png" height="18"> **Player input from the companion UI** — players submit actions from phone/tablet with a one-tap send and a live *Your move → Sent → ✓ DM has your move → narrating* status strip; Claude picks them up automatically in autorun mode
  45. - <img src="skills/dnd/display/icons/attack.png" height="18"> **Enforced roll handling** — choose at game start whether players roll their own d20s (DM calls for the roll and waits) or the DM rolls openly; per-character override from the phone; the DM never silently auto-rolls a PC
  46. - <img src="skills/dnd/display/icons/scroll.png" height="18"> **Reading controls** — per-player text-size stepper (legible across the room from a Chromecast) and a narration-length slider that sets the DM's per-turn word budget
  47. - <img src="skills/dnd/display/icons/timer.png" height="18"> **Autorun / taxi mode** — Claude drives the turn loop without DM input; a pie countdown shows the next auto-fire window
  48. - <img src="skills/dnd/display/icons/shield.png" height="18"> **LAN party support** — serve the companion over your local network; every device in the room sees the same display
  49. - <img src="skills/dnd/display/icons/shield.png" height="18"> **TLS / HTTPS** — self-signed cert generation included; required for full browser feature support over LAN
  50. - <img src="skills/dnd/display/icons/location.png" height="18"> **17 scene types** — auto-detected from narration keywords — tavern, dungeon, ocean, crypt, arcane, glacier, and more
  51. - <img src="skills/dnd/display/icons/spellbook.png" height="18"> **Clickable character sheets** — tap any sidebar card to open a full character sheet modal (attacks, features, inventory); works on phones and tablets via LAN
  52. - <img src="skills/dnd/display/icons/spellbook.png" height="18"> **SRD spell/feature lookup** — click any spell or feature name in a character sheet to view its full description; bundled 5e dataset with supplemental entries for non-SRD content (Xanathar's, Tasha's, subclass features); wikidot fallback link shown for anything not in the local data
  53. - <img src="skills/dnd/display/icons/crystal_ball.png" height="18"> **DM Help button** — click the ◈ button on the display for an on-demand contextual hint or warning; generated from the current scene without per-turn token overhead
  54. - <img src="skills/dnd/display/icons/potion.png" height="18"> **Tutor / learning mode** — enable per-session for automatic hint blocks after every scene, decision point, and roll; ideal for players new to D&D
  55. - <img src="skills/dnd/display/icons/chat.png" height="18"> **Spoken narration** — tap the speaker on any narration block to hear it read aloud. With a Google AI Studio key in `GEMINI_API_KEY` it uses Gemini TTS, and each clip is cached on disk so replaying a block makes no second request; without one it falls back to the browser's own speech synthesis, so narration audio works with no key, no account setup and no cost. The fallback is not necessarily offline — Chrome and Edge synthesize their best voices on the vendor's servers — but nothing is configured, billed, or sent to Gemini
  56. - <img src="skills/dnd/display/icons/focus.png" height="18"> **Browser-side sound effects** — 12 SFX types synthesized on demand via numpy and played through Web Audio API; works on any device with the tab open, including phones over LAN
  57. - <img src="skills/dnd/display/icons/dragon.png" height="18"> **Couch co-op** — multiple characters, shared display, turn order visible to everyone in the room
  58. - <img src="skills/dnd/display/icons/attack.png" height="18"> **Combat tracker** — auto-rolled initiative, `▶` turn pointer, HP bars, inline dice math sent to display
  59. - <img src="skills/dnd/display/icons/dagger.png" height="18"> **Helper scripts** — dice rolling, ability scores, combat, character stat derivation, conditions/tracker, calendar, SRD data sync, SRD lookup, supplemental data builder
  60. ---
  61. ## How It Works
  62. ```
  63. Claude Code CLI ──→ /dm:dnd commands ──→ campaign files (~/.claude/dnd/)
  64. state.md · world.md · npcs.md
  65. session-log.md · characters/
  66. Display pipeline (autorun mode):
  67. Players (phone/tablet) ──→ Companion UI ──→ Flask SSE server (localhost:5001)
  68. ↓
  69. autorun_wait.py
  70. ↓
  71. Claude processes turn
  72. ↓
  73. send.py / push_stats.py ──→ TV display
  74. ```
  75. The Flask server receives narration text, player actions, dice results, and character stats via HTTP POST. It broadcasts everything in real time to connected browsers via Server-Sent Events. The browser renders narration as a typewriter effect over a scene-reactive gradient background with a live character sidebar. In autorun mode Claude polls for player submissions and processes each turn automatically.
  76. ---
  77. ## Prerequisites
  78. - [Claude Code](https://claude.ai/code) CLI installed
  79. - Python 3.10+
  80. - `pip3 install flask flask-cors numpy cryptography` (display companion; numpy required for sound effects, cryptography for LAN TLS)
  81. - `pip3 install pymupdf` (campaign import from PDF — column-aware extraction so multi-column modules segment into chapters correctly; falls back to poppler's `pdftotext` if absent)
  82. ---
  83. ## Installation
  84. Install it as a Claude Code plugin:
  85. ```
  86. /plugin marketplace add neuralinitiative/claude-dnd-skill
  87. /plugin install dm@neural-initiative
  88. ```
  89. Then invoke it as **`/dm:dnd`** (plugin skills are namespaced `plugin:skill` — the `dm` plugin provides the `dnd` skill), or just describe what you want once a campaign is loaded. Update with `/plugin update dm`.
  90. ```bash
  91. # Optional — install the display-companion dependencies (one-time).
  92. # Core gameplay works without these; they power the live screen + audio.
  93. pip3 install flask flask-cors numpy cryptography
  94. ```
  95. > **Upgrading from a v1 standalone install?** As of v2.0.0 the skill is
  96. > plugin-only — the old `~/.claude/skills/dnd` standalone (`/dnd`) is replaced by
  97. > the plugin (`/dm:dnd`). **Your campaigns and characters are untouched** — they
  98. > live under `~/.claude/dnd/` (or `$DND_CAMPAIGN_ROOT`), entirely separate from
  99. > the skill code. Install the plugin above, then run the one-time helper to carry
  100. > over device pairings / TLS certs and retire the old install:
  101. > `python3 <plugin>/skills/dnd/scripts/migrate_v1_to_v2.py`. Full guide:
  102. > **[MIGRATING.md](MIGRATING.md)**.
  103. ---
  104. ## Versioning & updates
  105. The skill tracks releases via a top-level `VERSION` file and per-release notes in [`CHANGELOG.md`](CHANGELOG.md). The current version is in `VERSION`; significant changes — new commands, new mechanics, behavior changes — get a CHANGELOG entry.
  106. **To check for updates:**
  107. ```bash
  108. /dm:dnd update --check # shows local vs. remote version + commit diff, no pull
  109. /dm:dnd update # pulls if you're behind (fast-forward only; refuses on dirty tree)
  110. ```
  111. **Plugin installs update through the plugin manager** — run `/plugin update dm` instead. `/dm:dnd update` detects a plugin install and points you there rather than git-pulling under the manager's tracked state.
  112. The `--check` output includes both sides' version strings so you can see at a glance whether you've fallen behind. After updating, restart Claude Code so the new `SKILL.md` and command procedures load.
  113. The skill follows [semantic versioning](https://semver.org/): `MAJOR.MINOR.PATCH`. Breaking changes that require campaign-data migration bump MAJOR; new opt-in features bump MINOR; bug fixes bump PATCH. Active campaigns continue to work across MINOR/PATCH bumps without action.
  114. ---
  115. ## Quick Start
  116. **Improvised campaign** — Claude builds the world and generates a narrative arc:
  117. ```
  118. /dm:dnd new my-campaign # generates world seed, factions, NPCs, dynamic story arc
  119. /dm:dnd character new # create a character
  120. /dm:dnd load my-campaign # start a session
  121. ```
  122. **Structured campaign** — import a pre-written or published module:
  123. ```
  124. /dm:dnd import my-campaign path/to/module.pdf # extract structure and build campaign files
  125. /dm:dnd load my-campaign # start a session — Claude enforces the arc
  126. ```
  127. Once loaded, type naturally — no `/dm:dnd` prefix needed. The DM interprets everything as in-game action.
  128. ---
  129. ## Campaign Commands
  130. | Command | Description |
  131. |---------|-------------|
  132. | `/dm:dnd new <name>` | Create a new campaign — generates world seed, NPCs, starting location, and dynamic narrative arc |
  133. | `/dm:dnd import <name> <source>` | Import a pre-written campaign from PDF, markdown, DOCX, or plain text; extracts structure and builds all campaign files |
  134. | `/dm:dnd load <name>` | Load an existing campaign and enter DM mode |
  135. | `/dm:dnd save` | Write session events to log, update state and character files |
  136. | `/dm:dnd end` | Save session, append recap, stop display companion |
  137. | `/dm:dnd abandon` | Exit without saving — discards all unsaved changes from this session |
  138. | `/dm:dnd list` | List all campaigns with last session date and count |
  139. | `/dm:dnd recap` | In-character 3–5 sentence recap of the last session |
  140. | `/dm:dnd world` | Display world lore |
  141. | `/dm:dnd quests` | Show active quests and open threads |
  142. | `/dm:dnd arc status` | Show the current narrative arc, completed beats, and steering notes |
  143. | `/dm:dnd arc advance <beat>` | Mark a beat complete and update arc tracking (dynamic arcs only) |
  144. | `/dm:dnd arc revise` | Revise outstanding beats when a player choice significantly redirects the story |
  145. | `/dm:dnd arc new` | Generate a new arc from the consequences of a completed one |
  146. | `/dm:dnd autorun on [seconds]` | Enable autorun mode — Claude drives the turn loop automatically |
  147. | `/dm:dnd autorun off` | Return to manual mode |
  148. | `/dm:dnd tutor on` | Enable tutor / learning mode for this session |
  149. | `/dm:dnd tutor off` | Disable tutor / learning mode |
  150. | `/dm:dnd data sync` | Rebuild bundled SRD dataset from upstream sources (only needed for new upstream content) |
  151. | `/dm:dnd data status` | Show current dataset record counts and upstream SHA |
  152. | `/dm:dnd update` | Pull latest skill changes from `origin/main` (refuses on dirty tree, fast-forward only) |
  153. | `/dm:dnd update --check` | Show local-vs-remote version and commit-diff without pulling |
  154. | `/dm:dnd path [<new>\|reset]` | View or relocate campaign storage via `DND_CAMPAIGN_ROOT` |
  155. | `/dm:dnd graph init` | Initialize the campaign relationship graph (proposes seed nodes + edges; asks for approval) |
  156. | `/dm:dnd graph scene-context --place <id> [--present id1,id2]` | Focused subgraph for the current scene; primary in-session query |
  157. | `/dm:dnd graph add-edge --from <id> --to <id> --type T --since N` | Record a relationship shift mid-session |
  158. | `/dm:dnd graph close-edge --id <id> --at-session N` | Mark an edge as ended (alliance broke, NPC moved away, etc.) |
  159. | `/dm:dnd graph extract [--last-session-only]` | Run a Haiku pass over session-log to propose new edges (review-then-apply) |
  160. ---
  161. ## Narrative Arc System
  162. Both campaign modes use the same six-beat three-act structure tracked in `state.md`. The arc type determines how it's populated and enforced.
  163. ### Structural foundations
  164. The dynamic arc draws from several overlapping frameworks in story structure and tabletop adventure design:
  165. - **Three-act structure** — the classical division of setup, confrontation, and resolution, present in dramatic theory from Aristotle through modern screenwriting. The six beats are two per act, giving each phase a complicating turn rather than a flat arc through it.
  166. - **Dan Harmon's Story Circle** — an 8-step story engine (derived from Campbell's Hero's Journey) that emphasizes a character crossing into an unfamiliar situation, finding something, paying a price to take it, and returning changed. The Midpoint Shift and All Is Lost beats are direct reflections of this — the moment the story reveals its actual shape, and the cost the protagonist must pay before they can act on it.
  167. - **Beats as consequences, not events** — the key adaptation for tabletop play. In a scripted story, a beat is a scene ("the hero finds the letter"). In a tabletop arc, a beat is a consequence ("the party realizes the threat was built to outlast any single person"). Dozens of different scenes could deliver the same consequence. This gives the DM genuine flexibility while keeping the story's shape committed.
  168. - **Hub-and-spoke adventure structure** — used by the structured arc type for non-linear published modules. Players approach each spoke location in any order; each spoke has its own chapter beats; the central convergence point doesn't open until all required spokes resolve. This matches how most well-designed published campaigns are actually constructed and lets Claude enforce beats at chapter granularity without forcing a linear path.
  169. ### Improvised (type: dynamic)
  170. Generated automatically at `/dm:dnd new` from the world's threat, factions, and Three Truths. Beats are defined by `what_changes` — the narrative consequence that must land — not by a specific event. This gives the DM flexibility on *how* each beat arrives while committing to *that* it must.
  171. | Act | Beat | What it marks |
  172. |-----|------|---------------|
  173. | 1 | Inciting Incident | The threat becomes personal |
  174. | 1 | Complication | The problem is bigger than it first appeared |
  175. | 2 | Midpoint Shift | What the party thought they were doing changes |
  176. | 2 | All Is Lost | A genuine setback — something fails or collapses |
  177. | 3 | Final Confrontation | The decisive moment the campaign turns on |
  178. | 3 | Resolution | What's different about the world and characters after |
  179. Arc beats are tracked at `/dm:dnd end` and marked complete via `/dm:dnd arc advance`. When a major player choice redirects the story, `/dm:dnd arc revise` updates outstanding beats to fit the new direction. When all six beats resolve, `/dm:dnd arc new` generates a new arc from the consequences of the first — same world, new story question.
  180. ### Structured (type: structured)
  181. Populated by `/dm:dnd import` from the source material. Acts contain chapter-level key beats, telegraph scenes (setup scenes that naturally constrain choices toward each beat), and branching notes. Claude telegraphs before delivering any required beat, steers with world pressure rather than hard walls when players drift, and marks beats complete as each chapter resolves.
  182. The two arc types are mutually exclusive per campaign and fully compatible with all other systems — combat, XP, NPC attitudes, and display all behave identically regardless of arc type.
  183. ---
  184. ## Character Commands
  185. | Command | Description |
  186. |---------|-------------|
  187. | `/dm:dnd character new` | Create a character — guided point buy or rolled stats |
  188. | `/dm:dnd character sheet [name]` | Display a character sheet |
  189. | `/dm:dnd level up [name]` | Level up a character — applies class features, HP roll |
  190. ### Character Creation
  191. The creation flow walks through:
  192. 1. Name, race, class, background
  193. 2. **Point buy** (validates against 27-point budget) or **rolled** (3 arrays of 4d6kh3 to choose from)
  194. 3. Racial bonuses applied by `character.py calc --race <race> [--subrace <subrace>]` — the script applies them and shows base / race / final, so the step is computed rather than remembered; an unknown race refuses instead of silently applying nothing. In a 2024 campaign the increase comes from the background instead: `--background <name> --background-asi STR=2,CON=1` (or `+1/+1/+1`), checked against the background's three abilities
  195. 4. Derived stats calculated from the boosted scores by the same call
  196. 5. Starting equipment assigned by class + background
  197. 6. Sheet written to `characters/<name>.md`
  198. ---
  199. ## Combat System
  200. ```
  201. /dm:dnd combat start
  202. ```
  203. 1. Identifies all combatants, collects DEX mods, HP, AC
  204. 2. Auto-rolls initiative for **every combatant** including PCs — results sent to display
  205. 3. Tracks HP, conditions, turn order across rounds
  206. 4. Resolves NPC/monster attacks inline with full dice math:
  207. ```
  208. Goblin attacks: d20(14) + 4 = 18 vs AC 16 — hit! 1d6(3) + 2 = 5 piercing
  209. ```
  210. 5. PC attack/skill/save rolls follow the campaign's roll mode (see [Dice & Roll Handling](#dice--roll-handling)) — under the default `players` mode the DM calls for each PC roll by name and waits; under `auto` it rolls them openly. The DM always resolves NPC/monster rolls.
  211. ### Combat Display
  212. During combat the sidebar shows a live turn order with a `▶` pointer:
  213. ```
  214. — COMBAT — Round 2
  215. ▶ Aldric
  216. Skeleton
  217. Mira
  218. ```
  219. The pointer advances after each turn. HP bars update in real time when damage is taken. Combat ends with `--turn-clear`.
  220. ---
  221. ## Dice & Roll Handling
  222. How a player's own d20s (attacks, checks, saves, death saves) get rolled is chosen **at game start** and stored as `roll_mode` in `state.md → ## Session Flags`. Both `/dm:dnd new` and `/dm:dnd load` ask **"Dice rolls?"** so you confirm it each session.
  223. | Mode | Behavior |
  224. |------|----------|
  225. | **`players`** (default) | The DM calls for each PC d20 **by name and waits** for the player's result — it never rolls a player's character for them. If a roll doesn't come back (e.g. the physical-dice phone server is down) the DM asks for the number out loud rather than silently auto-rolling. |
  226. | **`auto`** | The DM rolls PC d20s openly with full math shown inline (`Piper — Perception: d20+5 = 18`), no waiting. Good for solo or fast play. |
  227. **Initiative is always DM-rolled** for every combatant (PCs and NPCs) regardless of mode, as are all NPC/monster rolls.
  228. **Per-player override** — a player can flip just their own character via the phone **Settings → Rolls** toggle. That POSTs to `/roll-pref`, and the DM honors a `[[<Char> roll mode: …]]` directive for that character, overriding the campaign default. Precedence: **per-character toggle > campaign `roll_mode`**.
  229. > This replaces the older always-"players roll their own" assumption: the DM no longer falls back to an auto-rolled `[auto]` result for a PC when the dice server is unavailable. Roll handling is now explicit and enforced.
  230. ---
  231. ## NPC System
  232. ```
  233. /dm:dnd npc Osk # portray an existing NPC or generate a new one
  234. /dm:dnd npc attitude Osk friendly # shift attitude on the 5-step scale
  235. ```
  236. Every NPC gets: role, stat block, demeanor, motivation, secret, and a speech quirk. Attitudes shift on a 5-step scale: `hostile → unfriendly → neutral → friendly → allied`. Changes are logged with reason and date in `npcs.md`.
  237. ### Companions
  238. ```
  239. /dm:dnd companion add Osk # the NPC joins the party — gets its own sheet and its own subagent
  240. /dm:dnd companion status # opinions of each PC, current personal goal, last memories
  241. /dm:dnd companion leave Osk # the NPC leaves (or splits off for a while)
  242. /dm:dnd companion mode Osk dm # hand it back to the DM (sheet and journal kept)
  243. /dm:dnd companion off # disable agent-played companions for this campaign
  244. ```
  245. **Opt-in:** when an NPC joins the party, the DM asks the player whether it should become an autonomous
  246. companion. Nothing is promoted without the player's choice.
  247. An NPC who travels with the party is played by a dedicated **`companion` subagent** instead of the DM. The
  248. subagent only ever sees the companion's own sheet and what the companion perceives in each scene — never the
  249. DM's secrets — so it can misjudge, object, pursue its own goals and surprise the table. The DM still rolls and
  250. decides every outcome. Each companion keeps an opinion of every PC and a journal of what mattered to it, both
  251. persisted in `campaigns/<name>/companions/<Name>.md` across sessions.
  252. ---
  253. ## Resting
  254. ```
  255. /dm:dnd rest short # 1 hour — spend Hit Dice, recharge some features
  256. /dm:dnd rest long # 8 hours — full HP, half your Hit Dice back (all in 2024), all spell slots; nothing for a character at 0 HP
  257. ```
  258. Long rests advance the in-world clock in `state.md`.
  259. ---
  260. ## Cinematic Display Companion
  261. An optional local web server (`display/dnd-display-app.py`) that renders DM narration on any screen — TV, tablet, phone, or second monitor. Cast it, mirror it, or open it on any device on your local network.
  262. ### Setup
  263. ```bash
  264. pip3 install flask flask-cors numpy cryptography
  265. ```
  266. ### Starting the Display
  267. The display starts automatically when you answer **y** at the `/dm:dnd load` prompt. Or start it manually:
  268. ```bash
  269. # Local only (Mac/same machine) — HTTP, no cert setup
  270. bash ${CLAUDE_SKILL_DIR}/display/start-display.sh
  271. # LAN mode — HTTP, accessible to phones/tablets on your network
  272. bash ${CLAUDE_SKILL_DIR}/display/start-display.sh --lan
  273. # LAN mode with TLS — for public or untrusted networks
  274. bash ${CLAUDE_SKILL_DIR}/display/start-display.sh --lan --tls
  275. ```
  276. Then open `http://localhost:5001` in your browser. HTTP is the default — no certificate warnings. For LAN devices use the IP URL printed at startup (e.g. `http://192.168.1.x:5001`). Use `--tls` only when the network is public or untrusted.
  277. ### Viewing Options
  278. Open the display URL in a browser, then choose how to show it:
  279. | Option | How |
  280. |--------|-----|
  281. | **TV — Cast tab** | Chrome → three-dot menu → Cast → Cast tab; select your Chromecast or smart TV |
  282. | **TV — Screen mirror** | macOS: Control Centre → Screen Mirroring → Apple TV / AirPlay receiver |
  283. | **iPad / tablet** | Start with `--lan`, open `http://<your-ip>:5001` in Safari or Chrome; works in landscape |
  284. | **Second monitor** | Open `http://localhost:5001` in a browser window and drag it to the second display |
  285. ### TLS / HTTPS (optional)
  286. HTTP is the default. Use `--tls` only when the network is public or untrusted. When `--tls` is passed to `start-display.sh`:
  287. - A self-signed cert is auto-generated (10-year validity) if `cert.pem` is not already present
  288. - A plain HTTP server starts on `:8080` to serve `cert.pem` for download
  289. - Per-platform install instructions are printed to the terminal (iOS, Android, Mac)
  290. For iOS: open `http://<your-ip>:8080/cert.pem` in Safari → tap Allow → Settings → General → VPN & Device Management → install profile → Certificate Trust Settings → enable full trust.
  291. ### Player Input from the Companion UI
  292. ![Player input panel — staging an action from a phone](screenshots/screenshot-player-input.png)
  293. Players open the companion in their phone browser. Each device binds to a party character, and the input view shows that player's turn flow as a plain **status strip** so they always know where their turn stands:
  294. ```
  295. Your move → Sending… → Sent to the DM → ✓ The DM has your move → The DM is narrating… → Your move
  296. ```
  297. 1. **Type and send** — staging is **one tap**. The action sends to the DM immediately (auto-ready) — no separate Stage / Mark Ready step. **Skip** passes the turn without typing.
  298. 2. **Sent → received** — the strip flips to *Sent to the DM*, then to a **`✓ The DM has your move`** toast the moment the DM actually picks the action up off the queue (not just when it's staged), then *The DM is narrating…*, then back to *Your move*. This closes the loop so a player can always tell whether their turn is in.
  299. The panel shows a **"Next Turn"** countdown pie clock that loops at the configured autorun interval.
  300. **Device approval defaults to trusting any device on your LAN** — convenient for a casual home network. Set `DND_REQUIRE_APPROVAL=1` to restore the per-device approve/deny gate for public or untrusted networks.
  301. ### Player Settings (phone)
  302. Each device has a **Settings** view with controls that tune the experience for that player or the whole table:
  303. | Control | What it does |
  304. |---------|--------------|
  305. | **Text Size** (`A−` / `A+`, click the % to reset) | Scales the reading column via a font-size multiplier (font size, not page zoom) so narration stays legible across the room from a Chromecast. Persists per-browser (`localStorage`), applied anti-FOUC. |
  306. | **Narration** slider (250–2500 words) | Sets the word-count target the DM aims for each turn. POSTs to `/narration-pref`; the next queued action carries a `[[Narration length…]]` directive the DM honors as a hard per-turn budget. Quick "keep turns short" knob for time-pressed tables. |
  307. | **Rolls** toggle (shown when the device is bound to a PC) | Flips that character between *Players* (you roll your own d20s) and *Auto-roll* (the DM rolls them openly), overriding the campaign default for that one character. See [Dice & Roll Handling](#dice--roll-handling). |
  308. | **Sound Effects** toggle | Enables browser-side SFX (see [Sound Effects](#sound-effects)). |
  309. ### Autorun Mode
  310. Autorun is the primary way to run sessions with the companion UI. Once enabled, Claude drives the turn loop without requiring the DM to press Enter between each turn.
  311. ```
  312. /dm:dnd autorun on # enable — 60s default countdown
  313. /dm:dnd autorun on 45 # enable with 45-second countdown
  314. /dm:dnd autorun off # return to manual mode
  315. ```
  316. The countdown is configurable per-campaign by setting `autorun_interval: N` in `state.md → ## Session Flags`. To interrupt autorun from the Claude Code CLI, press **Ctrl+C** during the wait.
  317. **N-player threshold** — by default autorun fires when all known players are ready. For multi-device groups you can require only N players:
  318. ```bash
  319. python3 ${CLAUDE_SKILL_DIR}/display/push_stats.py --autorun-threshold 2 # fire when 2 ready
  320. python3 ${CLAUDE_SKILL_DIR}/display/push_stats.py --autorun-threshold 0 # reset to player count
  321. ```
  322. ### DM Help & Tutor Mode
  323. There are two ways to surface hints and warnings on the display — an on-demand button and a per-session automatic mode.
  324. **DM Help button (◈)** — a **◈ DM Help** button sits in the bottom-right corner of the display at all times. Click it and within a few seconds a contextual hint or warning is generated from the current scene and pushed to the display — no CLI command needed, no per-turn token overhead. The button reads the last 8 display blocks and current campaign state, calls Claude in non-interactive mode, and sends the result as a hint block via the normal SSE pipeline. Shows "Thinking…" while in flight; resets automatically when the block arrives. Multiple simultaneous clicks only trigger one execution.
  325. Hint blocks are **collapsed by default** — click or tap the header to expand. Warnings use an amber border:
  326. - **DM Hint** (◈, collapsible) — skills worth attempting, visible options, what each path might cost
  327. - **Warning** (⚠, amber border) — flags irreversible choices before the player commits
  328. ![Tutor mode intro hint](screenshots/tutor-hint-intro.png)
  329. Hints can surface contextual NPC and situation knowledge the DM would naturally flag:
  330. ![Tutor hint with NPC context](screenshots/tutor-hint-npc.png)
  331. Warnings use an amber border to distinguish high-stakes choices:
  332. ![Tutor warning block](screenshots/tutor-warning.png)
  333. **Tutor mode (per-session)** — for new players who want continuous guidance, enable automatic hint blocks after every scene, decision point, and roll — no button needed. Adds ~10–20% token overhead per turn. Use the DM Help button instead for on-demand hints without the ongoing cost.
  334. ```
  335. /dm:dnd tutor on # enable for this session
  336. /dm:dnd tutor off # disable
  337. ```
  338. Tutor mode is session-scoped — does not persist to the next `/dm:dnd load` unless set again.
  339. The two are independent — the ◈ button is always available regardless of whether tutor mode is on.
  340. ---
  341. ### Scene Detection
  342. The server scans narration text for keywords and crossfades the background gradient and particle type to match the current environment. Scenes change automatically as the story moves.
  343. | Scene | Trigger Keywords | Particles |
  344. |-------|-----------------|-----------|
  345. | Tavern | inn, hearth, ale, tallow, barkeep | embers |
  346. | Dungeon | corridor, torch, portcullis, dank | dust |
  347. | Ocean / Docks | dock, harbour, wave, tide, ship | ripples |
  348. | Forest | tree, canopy, moss, thicket, grove | leaves |
  349. | Crypt | tomb, undead, skeleton, burial | smoke |
  350. | Arcane | ritual, rune, sigil, incantation | sparks |
  351. | Mountain | glacier, frost, blizzard, ridge | snow |
  352. | Cave | stalactite, grotto, echo, drip | mist |
  353. | Night | midnight, moon, constellation | stars |
  354. | City / Town | market, cobble, district, crowd | rain |
  355. | Swamp | swamp, bog, marsh, mire | mist |
  356. | + 6 more | mine, castle, ruins, desert, fire, temple | — |
  357. Scene transitions crossfade over ~2.5 seconds. Detection runs over a 20-chunk rolling window, and a challenger has to beat the scene already on screen by 2 points to take the room, with the incumbent carrying a bonus of 1 so it can hold its ground once its own keywords scroll out of the window. Before that margin existed a single keyword was enough to change the background, and two plausible scenes would trade it back and forth on a one-point edge. Keywords are matched as whole words, so `ward` no longer fires inside "deputy warden".
  358. ### Dynamic Sky Canvas
  359. A canvas layer rendered above the scene background shows a live sky that reacts to `world_time` data pushed via `push_stats.py`:
  360. - **Time of day** — sun arcs from dawn (lower-left) through midday (top-center) to dusk (lower-right); switches to crescent moon + twinkling stars at night; twilight shows an orange horizon
  361. - **Weather** — calm: 2 light clouds; overcast: 5 heavy dark clouds, dimmed sun; rainy: dense cloud cover, muted palette; stormy: near-black sky; clear night: full star field
  362. - **Clouds** — 5 cloud objects each built from 8 overlapping circles; drift slowly and wrap
  363. Push world time data after loading a campaign and after any rest or time advance:
  364. ```bash
  365. python3 ${CLAUDE_SKILL_DIR}/display/push_stats.py --world-time \
  366. '{"date":"7 Deepmonth 1312 CR","day_name":"Starday","time":"morning","season":"Deep Winter","weather":"overcast"}'
  367. ```
  368. Valid `time` values: `dawn`, `morning`, `midday`, `afternoon`, `evening`, `dusk`, `night`
  369. Valid `weather` values: `calm`, `clear`, `overcast`, `rainy`, `stormy`
  370. ### Sound Effects
  371. Narration text is scanned server-side for 12 SFX trigger categories. When a match is found, the browser fetches a synthesized WAV file and plays it via Web Audio API — no server audio output, works on any device with the tab open.
  372. ```
  373. impact · sword · arrow · shout · thud · magic · coins · door · low_hum · fire · breath
  374. ```
  375. SFX synthesis uses numpy — if numpy is not installed the feature degrades silently. Enable via the **Sound Effects** toggle in the top-right of the display.
  376. | Narration text | SFX |
  377. |----------------|-----|
  378. | "...strikes the shield..." | impact |
  379. | "...draws her blade..." | sword |
  380. | "...looses an arrow..." | arrow |
  381. | "...he roars across the dock..." | shout |
  382. | "...collapses to the floor..." | thud |
  383. | "...arcane energy crackles..." | magic |
  384. | "...coins spill across the table..." | coins |
  385. | "...the door creaks open..." | door |
  386. | "...the altar hums with energy..." | low_hum |
  387. | "...the torch flares..." | fire |
  388. | "...a sharp exhale..." | breath |
  389. The browser caches each WAV after first fetch. SFX trigger naturally alongside the typewriter animation since both are driven by the same narration chunks.
  390. ### Live Character Sidebar
  391. ![NPC dialogue block and character sidebar with faction panel](screenshots/screenshot-npc-dialogue.png)
  392. A fixed left sidebar shows live stats for all party members, updated automatically as play progresses.
  393. ```bash
  394. # Push full stats on campaign load (clears stale characters from previous campaigns)
  395. python3 ${CLAUDE_SKILL_DIR}/display/push_stats.py --replace-players --json '{
  396. "players": [{
  397. "name": "Aldric", "race": "Human", "class": "Fighter", "level": 2,
  398. "hp": {"current": 14, "max": 18}, "xp": {"current": 220, "next": 300},
  399. "ac": 17, "initiative": "+1", "speed": 30,
  400. "hit_dice": {"remaining": 2, "max": 2, "die": "d10"},
  401. "ability_scores": {
  402. "str": {"score": 16, "mod": "+3"}, "dex": {"score": 12, "mod": "+1"},
  403. "con": {"score": 15, "mod": "+2"}, "int": {"score": 10, "mod": "+0"},
  404. "wis": {"score": 11, "mod": "+0"}, "cha": {"score": 13, "mod": "+1"}
  405. }
  406. }]
  407. }'
  408. # Partial updates during play
  409. python3 ${CLAUDE_SKILL_DIR}/display/push_stats.py --player Aldric --hp 10 18
  410. python3 ${CLAUDE_SKILL_DIR}/display/push_stats.py --player Aldric --xp 270 300
  411. python3 ${CLAUDE_SKILL_DIR}/display/push_stats.py --player Aldric --conditions-add "Poisoned"
  412. python3 ${CLAUDE_SKILL_DIR}/display/push_stats.py --player Aldric --slot-use 2
  413. # Or bundle stat changes directly with a narration send (no separate push_stats.py call needed):
  414. python3 ${CLAUDE_SKILL_DIR}/display/send.py \
  415. --stat-hp "Aldric:10:18" \
  416. --stat-condition-add "Aldric:Poisoned" \
  417. --stat-slot-use "Aldric:1" << 'EOF'
  418. The goblin's blade catches Aldric across the ribs...
  419. EOF
  420. # Combat turn order
  421. python3 ${CLAUDE_SKILL_DIR}/display/push_stats.py \
  422. --turn-order '{"order":["Aldric","Skeleton","Mira"],"current":"Aldric","round":1}'
  423. # Advance turn pointer
  424. python3 ${CLAUDE_SKILL_DIR}/display/push_stats.py --turn-current "Skeleton"
  425. # Combat ended
  426. python3 ${CLAUDE_SKILL_DIR}/display/push_stats.py --turn-clear
  427. # World time clock
  428. python3 ${CLAUDE_SKILL_DIR}/display/push_stats.py --world-time \
  429. '{"date":"7 Deepmonth 1312 CR","day_name":"Starday","time":"morning","season":"Deep Winter","weather":"overcast"}'
  430. ```
  431. ![Character sidebar card](screenshots/sidebar-card.png)
  432. ### Clickable Character Sheet
  433. Click or tap any character card in the sidebar to open a full character sheet modal — attacks, features, and inventory at a glance. Works on desktop and on phones/tablets connected via LAN.
  434. ![Character sheet modal](screenshots/character-sheet-modal.png)
  435. Include the `sheet` field when pushing stats on `/dm:dnd load` to populate the full sheet:
  436. ```bash
  437. python3 ${CLAUDE_SKILL_DIR}/display/push_stats.py --replace-players --json '{
  438. "players": [{
  439. "name": "Aldric",
  440. ...
  441. "sheet": {
  442. "attacks": [
  443. {"name": "Longsword", "bonus": "+5", "damage": "1d8+3", "type": "Slashing", "notes": "Versatile (1d10)"}
  444. ],
  445. "features": [
  446. {"name": "Second Wind", "text": "Bonus action: regain 1d10+level HP. Short/long rest recharge."}
  447. ],
  448. "inventory": ["Longsword", "Chain Mail", "Shield", "Explorer'\''s Pack", "15 gp"]
  449. }
  450. }]
  451. }'
  452. ```
  453. If `sheet` is omitted, the modal still opens but shows only the stats visible in the sidebar. Close with **Esc**, clicking outside the panel, or the ✕ button.
  454. Clicking a spell or feature name inside the sheet opens a description modal sourced from the bundled SRD dataset. Scaling progressions (e.g. Sneak Attack damage) automatically collapse to the character's current level. If a spell or feature isn't in the core SRD dataset, a link to the relevant page on D&D 5e Wiki is shown instead. To extend the local dataset with non-SRD content from a character file:
  455. ```bash
  456. python3 ${CLAUDE_SKILL_DIR}/scripts/build_supplemental.py --character ~/.claude/dnd/campaigns/<name>/characters/<charname>.md
  457. ```
  458. This fetches descriptions from dnd5e.wikidot.com for any missing entries and writes them to `data/dnd5e_supplemental.json`. Run it once after creating or importing a character. A pre-built supplemental covering Circle of Spores, Thief archetype features, and several Xanathar's spells ships with the skill.
  459. The sidebar:
  460. - Shows compact dual-column cards for parties of 2+ (full ability grid for solo play)
  461. - HP bars shift green → yellow → red as HP drops
  462. - XP bar fills toward next level
  463. - Active conditions displayed per character
  464. - Spell slot pips track remaining charges
  465. - Fades in automatically on first stats push
  466. - Persists across Flask restarts (`stats.json`)
  467. - Cleared automatically on `/dm:dnd new` (fresh campaign)
  468. ### Replay Buffer
  469. The server buffers the last 60 text chunks to disk (`text_log.json`). Reconnecting browsers (Chromecast drop, tab refresh) replay the full session history automatically — no narration is lost.
  470. ---
  471. ## Scripts Reference
  472. All scripts live in `${CLAUDE_SKILL_DIR}/scripts/`.
  473. ### `dice.py` — All dice rolls
  474. ```bash
  475. python3 scripts/dice.py d20+5
  476. python3 scripts/dice.py 2d6+3
  477. python3 scripts/dice.py d20 adv # advantage
  478. python3 scripts/dice.py d20+3 dis # disadvantage + modifier
  479. python3 scripts/dice.py 4d6kh3 # keep highest 3 (ability score roll)
  480. python3 scripts/dice.py d20 --silent # integer only (for hidden rolls)
  481. ```
  482. Say what a d20 is for with `--vs check|save|attack|death`: only an attack roll is labelled `CRITICAL HIT` / `FUMBLE`, a death save reports its own nat 20 / nat 1 rules, and a check or save just notes the natural roll. `--dc N` adds `PASS` / `FAIL`; `--effects <name> -c <campaign>` adds the modifiers `tracker.py` holds (Bless's +1d4).
  483. ```bash
  484. python3 scripts/dice.py d20+5 --vs save --dc 14
  485. python3 scripts/dice.py d20+6 --vs attack --dc 15 --effects Aldric -c <campaign>
  486. ```
  487. ### `ability-scores.py` — Character creation
  488. ```bash
  489. python3 scripts/ability-scores.py roll # 3 arrays to choose from
  490. python3 scripts/ability-scores.py pointbuy # print cost table
  491. python3 scripts/ability-scores.py pointbuy --check STR=15 DEX=10 CON=15 INT=8 WIS=11 CHA=12
  492. python3 scripts/ability-scores.py modifiers STR=15 DEX=10 CON=15 INT=8 WIS=11 CHA=12
  493. ```
  494. ### `combat.py` — Initiative and attack resolution
  495. ```bash
  496. # Roll initiative for all combatants and print tracker
  497. python3 scripts/combat.py init '[
  498. {"name":"Aldric","dex_mod":1,"hp":18,"ac":17,"type":"pc"},
  499. {"name":"Skeleton","dex_mod":2,"hp":13,"ac":13,"type":"npc"}
  500. ]'
  501. # Reprint tracker from saved state
  502. python3 scripts/combat.py tracker '<state_json>' <round_num>
  503. # Resolve a single attack
  504. python3 scripts/combat.py attack --atk 5 --ac 13 --dmg 1d8+3
  505. # Paralyzed or unconscious target within 5 ft: any hit is a critical hit
  506. python3 scripts/combat.py attack --atk 5 --ac 13 --dmg 1d8+3 --crit
  507. ```
  508. `init` outputs a `STATE_JSON:` line — save this to `state.md` under `## Active Combat` for persistence between turns.
  509. ### `build_supplemental.py` — Extend the SRD dataset with non-SRD content
  510. Run after creating or importing a character to fetch descriptions for spells and features not in the core SRD:
  511. ```bash
  512. # Scan a character file and fetch anything missing
  513. python3 scripts/build_supplemental.py --character ~/.claude/dnd/campaigns/<name>/characters/<charname>.md
  514. # Scan all characters in a campaign at once
  515. python3 scripts/build_supplemental.py --campaign <campaign-name>
  516. # Add a specific entry by name
  517. python3 scripts/build_supplemental.py --add "Toll the Dead" spell
  518. python3 scripts/build_supplemental.py --add "Halo of Spores" feature
  519. # See what's currently cached
  520. python3 scripts/build_supplemental.py --list
  521. # Preview what would be fetched without writing
  522. python3 scripts/build_supplemental.py --campaign <name> --dry-run
  523. ```
  524. Fetches from `dnd5e.wikidot.com` with a polite request delay. Uses Python stdlib only — no extra dependencies. Writes to `data/dnd5e_supplemental.json`, which `lookup.py` merges at load time.
  525. ---
  526. ### `character.py` — Stat derivation and levelling
  527. ```bash
  528. # Full stat block from raw scores
  529. python3 scripts/character.py calc --class fighter --level 2 \
  530. STR=16 DEX=12 CON=15 INT=10 WIS=11 CHA=13 \
  531. --proficient STR CON Athletics Intimidation Perception Survival
  532. # 2024 rules: the background's ability increase, validated against the background
  533. python3 scripts/character.py calc --class fighter --level 1 --background soldier \
  534. --background-asi STR=2,CON=1 STR=15 DEX=13 CON=14 INT=8 WIS=12 CHA=10 \
  535. --armor chain-mail --shield # Armor Class from the SRD armor record
  536. # Level-up — also lists the choices the level owes (ASI, subclass, invocations,
  537. # pact boon, fighting style) and retroactive HP when CON rose
  538. python3 scripts/character.py levelup --class fighter --from 2 --hp-roll 8 --con-mod 2
  539. # Rests — Hit Dice spent on a short rest, what a long rest restores
  540. python3 scripts/character.py hitdie --die d10 --con-mod 2 --hp 9 --max-hp 20 --remaining 2
  541. python3 scripts/character.py rest long --level 2 --hd-remaining 0 --hp 9 --max-hp 20
  542. # XP tracking
  543. python3 scripts/character.py xp --level 2 --gained 150
  544. ```
  545. ---
  546. ## File Layout
  547. ```
  548. ${CLAUDE_SKILL_DIR}/
  549. ├── SKILL.md # Skill definition and DM instructions
  550. ├── SKILL-scripts.md # Script and tool syntax reference
  551. ├── SKILL-commands.md # /dm:dnd command procedures
  552. ├── README.md # This file
  553. ├── data/
  554. │ ├── dnd5e_srd.json # Bundled 5e SRD dataset (1467 records — spells, features, equipment, monsters, races)
  555. │ └── dnd5e_supplemental.json # Non-SRD content (Xanathar's, subclass features, etc.)
  556. ├── scripts/
  557. │ ├── dice.py
  558. │ ├── ability-scores.py
  559. │ ├── combat.py
  560. │ ├── character.py
  561. │ ├── tracker.py
  562. │ ├── calendar.py
  563. │ ├── lookup.py # SRD + supplemental query API
  564. │ ├── build_srd.py # Fetches upstream 5e data and builds dnd5e_srd.json
  565. │ ├── sync_srd.py # Checks upstream SHAs; rebuilds only on new commits
  566. │ └── build_supplemental.py # Fetches non-SRD entries from wikidot for a character or campaign
  567. ├── display/
  568. │ ├── dnd-display-app.py # Flask SSE server
  569. │ ├── audio.py # SFX synthesis and browser trigger (numpy)
  570. │ ├── autorun_wait.py # Blocking wait for autorun mode (TCC-safe, pure python)
  571. │ ├── check_input.py # Non-blocking player input queue poll (mid-turn check)
  572. │ ├── send.py # Direct send for narration/dice/player actions
  573. │ ├── push_stats.py # Character and combat stat updates
  574. │ ├── setup_tls.py # Self-signed TLS cert generator for LAN mode
  575. │ ├── start-display.sh # One-command display startup
  576. │ ├── dm_help.py # On-demand DM hint generator (◈ button)
  577. │ ├── wrapper.py # PTY wrapper (legacy — autorun preferred)
  578. │ ├── requirements.txt
  579. │ └── templates/
  580. │ └── index.html # Browser frontend
  581. └── templates/
  582. ├── character-sheet.md
  583. ├── state.md
  584. ├── world.md
  585. ├── npcs.md
  586. └── session-log.md
  587. ~/.claude/dnd/campaigns/<name>/
  588. ├── state.md # Current location, party status, active quests, arc tracking
  589. ├── world.md # World lore, setting details, adventure nodes
  590. ├── npcs.md # NPC index with stat blocks and attitudes
  591. ├── session-log.md # Session history and recaps (last 2 sessions; older archived)
  592. ├── session-log-archive.md # Full session history archive
  593. ├── session_tail.json # Last session's display tail — replayed on load
  594. └── characters/
  595. ├── Aldric.md
  596. └── Mira.md
  597. ```
  598. ---
  599. ## DM Philosophy
  600. The skill is designed around a set of hard constraints, not aspirational notes:
  601. - **Improvise over script** — the world is a sandbox; player choices always find a "yes, and..."
  602. - **Consequences are real** — NPCs remember conversations; factions shift; failure is possible
  603. - **Economy of description** — two sharp sensory details beat a paragraph of exposition
  604. - **Every NPC is a person** — even minor characters get a verbal tic, a contradiction, a goal
  605. - **Hidden rolls stay hidden** — Perception, Insight, and Stealth roll silently; only the outcome is narrated (but results always appear on the display)
  606. - **The arc bends, never breaks** — when players redirect the story, beats revise to fit the new direction; the committed shape is a guide, not a cage
  607. - **Calibrates to this specific player across sessions** — DM Style Notes accumulate table-specific patterns from calibration feedback; what lands for this party, what splits the table, what to lean into; read at every session load and updated at every end
  608. - **The world moves between sessions** — factions act while the party is occupied; NPCs pursue their own goals; doors that were kicked in stay broken; the player arrives to a world with weight, not a scene that was paused waiting for them
  609. ---
  610. ## Ruleset
  611. Each campaign declares its ruleset on the `state.md` header line: `**Ruleset:** 2014` (SRD 5.1) or `**Ruleset:** 2024` (SRD 5.2). `/dm:dnd new` asks for the ruleset at creation time; `/dm:dnd load` reads the field on every session. Legacy campaigns (predating the field) default to **2014** and are offered a one-time migration with a timestamped backup.
  612. ### 2014 dataset (default)
  613. `data/dnd5e_srd.json` — built from `5e-bits/5e-database` (`main` branch, 2014 SRD) and `foundryvtt/dnd5e` (`master` branch). 1,467 records: 319 spells, 237 equipment, 362 magic items, 15 conditions, 334 monsters, 9 races, 4 subraces, 187 features.
  614. ### 2024 dataset (opt-in)
  615. `data/dnd5e_srd_2024.json` — built from `5e-bits/5e-database` (`src/2024/en/`), `foundryvtt/dnd5e` (`packs/_source/spells24/`, `packs/_source/actors24/`, `packs/_source/classfeatures24/`). All foundry content is CC-BY-4.0, with `_source` and `_license` provenance preserved on every record. Approximately 1,420+ records: 341 native 2024 spells, 376 native 2024 monsters, 8 weapon mastery properties, 9 species, 24 subspecies, 17 origin/general/fighting-style feats, 4 backgrounds, plus equipment / magic items / features. Build with `python3 scripts/build_srd.py --ruleset 2024` (one-time, ~3 min).
  616. ### Mechanic differences applied at the table
  617. | Mechanic | 2014 | 2024 |
  618. |---|---|---|
  619. | Subclass timing | varies by class (1/2/3) | level 3 universally |
  620. | ASI source | race | background |
  621. | Origin feat | n/a | granted at level 1 by background |
  622. | Weapon mastery | n/a | 8 properties (Vex, Topple, Sap, Cleave, Graze, Nick, Push, Slow) |
  623. | Exhaustion | 6-level table with varied effects | 1 stack = -2 to all d20 rolls (cumulative); death at level 6 |
  624. | Stealth disadvantage on heavy armor | yes | yes (unchanged) |
  625. | Healing word range | 60 ft | 60 ft (unchanged) |
  626. Combat resolution, dice rolling, initiative, AC/HP derivation, XP tables, cantrip damage scaling, and rest recovery are identical between editions and require no per-ruleset branching in the engine.
  627. ### Backwards compatibility
  628. Existing campaigns continue to load unchanged. The first time a legacy campaign is loaded under the new code path, `migrate_ruleset.py` detects the missing `**Ruleset:**` field and prompts the DM. The migrator:
  629. - Backs up `state.md` to `state.md.backup-pre-ruleset-<timestamp>` before any write
  630. - Injects the chosen ruleset into the header line
  631. - Is idempotent — re-running on a migrated campaign is a clean no-op
  632. - Has a `--check` mode for non-mutating detection (used by `/dm:dnd load`)
  633. Character files inherit ruleset from their campaign at runtime via `paths.campaign_ruleset()`; no per-character migration is required. The display companion auto-detects the campaign's ruleset and surfaces it as a small badge in the world-clock cluster.
  634. If you want to switch a legacy campaign to 2024, run the migrator manually:
  635. ```bash
  636. python3 scripts/migrate_ruleset.py <campaign-name> --ruleset 2024 --yes
  637. ```
  638. Note: switching an in-progress 2014 campaign to 2024 mid-arc is not recommended — character builds (origin feats, background ASIs, weapon mastery for martial classes) were locked in under 2014 rules. The migrator simply stamps the field; rebuilding characters under 2024 is a separate manual exercise.
  639. ---
  640. ## License
  641. [AGPL-3.0-or-later](LICENSE). Copyright (c) 2026 Neural Initiative LLC.
  642. Self-hosting and modification are explicitly welcome — fork, run, change as you like. The AGPL specifically protects against re-hosting this as a closed-source SaaS without sharing modifications back. For most users this distinction never matters.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.