DM20 Protocol

Create a new D&D campaign.

The rules_version parameter selects which edition of the D&D 5e rules to use for this campaign. '2024' uses the revised 2024 rules, '2014' uses the original 5th edition rules.

The interaction_mode parameter controls how the DM communicates:

• classic: Text-only, no voice dependencies required.

• narrated: DM responses delivered as TTS audio + text via WebSocket.

• immersive: Narrated + player STT input from browser.

Interaction mode and model profile are independent axes — any combination is valid.

Get information about the current campaign.

Returns campaign information including name, description, counts of various entities, and current game state.

List all available campaigns.

Load a specific campaign.

Delete a campaign permanently. This cannot be undone.

Create a new player character.

When a rulebook is loaded, auto-populates the character with saving throws, proficiencies, starting equipment, features, HP, spell slots, and more from the class, race, and background definitions. Requires a rulebook to be loaded (use load_rulebook source="srd" first).

Without a rulebook, returns an error message asking to load one first.

Level up a character by one level.

Increments level, calculates HP increase, adds class features, updates spell slots for casters, handles ASI at appropriate levels, and manages subclass selection. Requires a rulebook to be loaded.

Multiclass: if class_name is a class the character doesn't have yet, this acts as a multiclass dip — adding that class at level 1.

Get detailed character information. Accepts character name, ID, or player name.

Update a character's properties.

Supports scalar field updates, ability score changes, and list add/remove operations for conditions, proficiencies, languages, and features. List parameters accept JSON arrays (e.g. '["poisoned","prone"]') or comma-separated strings (e.g. 'poisoned,prone').

Update properties for multiple characters at once by a given amount.

Add an item to a character's inventory.

Equip an item from inventory to an equipment slot.

Moves the item from the character's inventory to the specified equipment slot. If the slot is already occupied, the current item is automatically unequipped back to inventory first.

Unequip an item from an equipment slot back to inventory.

Moves the equipped item back to the character's inventory and clears the slot.

Remove an item from a character's inventory.

Removes the specified quantity of an item. If quantity is greater than or equal to the item's current quantity, the item is removed entirely.

Use a spell slot, decrementing available slots for the given level.

Validates that the character has slots at this level and that at least one is still available. Returns remaining slot count.

Add a spell to a character's spells known list.

Remove a spell from a character's spells known list.

Perform a long rest for a character.

Resets spell slots, restores hit dice (half of total, minimum 1), clears death saves, and optionally restores HP to maximum.

Perform a short rest for a character.

Optionally spend hit dice to regain hit points. Each hit die rolled adds 1dX + CON modifier HP (minimum 1 per die).

Record a death saving throw result.

Tracks successes and failures. At 3 successes, the character stabilizes (HP set to 1, death saves reset). At 3 failures, the character dies.

List all characters in the current campaign.

Returns a list of all player characters with their basic information.

Delete a character from the current campaign. Accepts character name, ID, or player name.

Create a new NPC.

Get NPC information.

List all NPCs in the current campaign.

Returns a list of all non-player characters with their basic information.

Create a new location.

Get location information.

List all locations in the current campaign.

Returns a list of all locations with their basic information.

Create a new quest.

Update quest status or complete objectives.

List quests, optionally filtered by status.

Returns a list of quests with their basic information and status.

Update the current game state.

Get the current game state.

Start a combat encounter.

End the current combat encounter.

Advance to the next turn in combat.

Resolve a combat action via the pipeline, apply results, and return a formatted outcome.

Supports weapon attacks (melee/ranged) and saving throw spells. Automatically applies damage to the target's HP, triggers concentration checks, and reports the full mechanical outcome. This is additive -- it does not replace manual roll_dice workflows.

Return encounter suggestions with monster compositions based on party size, level, and difficulty.

Uses the D&D 5e encounter building rules (DMG Chapter 3) to calculate XP budgets and suggest balanced encounters. When rulebooks are loaded, suggests specific monsters.

Render the current tactical map as ASCII art.

Shows positions of all combat participants on a grid. Returns 'No tactical map active' if no positions are set or no combat is active.

Apply an ActiveEffect to a character (SRD condition or custom effect).

For SRD conditions (blinded, charmed, deafened, exhaustion, frightened, grappled, incapacitated, invisible, paralyzed, petrified, poisoned, prone, restrained, stunned), uses the standard condition template.

For custom effects, creates a new ActiveEffect with the provided modifiers.

Remove an active effect from a character by ID or name.

If an exact effect ID is provided, removes that specific instance. If a name is provided, removes all effects with that name.

Add notes for a game session.

Generate structured SessionNote from a raw session transcription.

This tool accepts either raw transcription text or a path to a transcription file, then generates a comprehensive structured summary including events, NPCs encountered, quest updates, and combat encounters. The tool leverages campaign context (characters, NPCs, locations, quests) to enrich the summary.

For large transcriptions (>200k characters ≈ 50k tokens), the tool automatically chunks the input into overlapping segments for processing.

Args: transcription: Raw text or file path containing session transcription session_number: Session number for this recording detail_level: Amount of detail in the generated summary speaker_map: Optional mapping of generic speaker labels to character names

Returns: Prompt for LLM to generate SessionNote

Get all session notes.

Add an event to the adventure log.

Get events from the adventure log.

Load a rulebook into the current campaign.

List all active rulebooks in the current campaign.

Remove a rulebook from the current campaign.

Search for rules content across all loaded rulebooks.

Works without a campaign loaded (uses global rulebook manager). When a campaign is active, its rulebook manager takes priority.

Examples: - search_rules(query="fire", category="spell") - Find spells with 'fire' in name - search_rules(class_filter="ranger", category="spell") - All ranger spells - search_rules(query="cure", class_filter="ranger", category="spell") - Ranger spells with 'cure' in name

Get full class definition from loaded rulebooks.

Works without a campaign loaded (uses global rulebook manager). When a campaign is active, its rulebook manager takes priority.

Get full race definition from loaded rulebooks.

Works without a campaign loaded (uses global rulebook manager). When a campaign is active, its rulebook manager takes priority.

Get spell details from loaded rulebooks.

Works without a campaign loaded (uses global rulebook manager). When a campaign is active, its rulebook manager takes priority.

Get monster stat block from loaded rulebooks.

Works without a campaign loaded (uses global rulebook manager). When a campaign is active, its rulebook manager takes priority.

Validate a character against loaded rulebooks.

Roll dice with D&D notation.

Calculate experience points for an encounter.

Open the library folder where users can drop PDF and Markdown rulebooks.

Creates the library/pdfs/ directory if it doesn't exist, then opens it in the system file manager (Finder on macOS, file manager on Linux).

Returns the absolute path to the folder with instructions on next steps.

Scan the library folder for new PDF/Markdown files and index them.

Scans the library/pdfs/ directory for PDF and Markdown files, extracts table of contents from new or modified files, and saves indexes for quick searching.

Returns a summary of files found and indexed.

List all sources in the library with their content summaries.

Returns a formatted list of all PDF and Markdown sources in the library, showing their index status and content counts.

Get the table of contents for a specific library source.

Returns the full hierarchical table of contents extracted from the PDF or Markdown source, with page numbers and content types.

Args: source_id: The source identifier (use list_library to see available sources)

Search across all indexed library content.

Searches TOC entries by title across all indexed PDF and Markdown sources. Can filter by content type (class, race, spell, etc.).

Args: query: Search term (case-insensitive, searches in titles) content_type: Filter by content type (default: all) limit: Maximum results to return (default: 20)

Ask a natural language question across all your rulebooks.

Uses keyword expansion with D&D concept synonyms and TF-IDF scoring to find relevant content across all indexed PDF and Markdown sources.

Examples: - "What options do I have for a melee spellcaster?" - "Find a class good for a dragon-themed character" - "What healing spells are available?" - "Show me tanky fighter options" - "Classes with nature magic"

Args: query: Natural language question or search query limit: Maximum number of results to return (default: 10)

Returns: Formatted search results grouped by source

Extract content from a PDF source and save as CustomSource JSON.

Extracts the full content definition from a PDF source based on the table of contents entry. The extracted content is saved to the library/extracted/{source_id}/ directory in CustomSource JSON format, ready to be loaded by the rulebook system.

Examples: - extract_content("tome-of-heroes", "Fighter", "class") - extract_content("phb", "Elf", "race") - extract_content("phb", "Fireball", "spell")

Args: source_id: The source identifier (use list_library to see available sources) content_name: Name of the content to extract (as shown in TOC) content_type: Type of content (class, race, spell, monster, feat, item)

Returns: Success message with path to extracted file, or error message

Enable a library source for the current campaign.

Adds a library source to the campaign's enabled content. You can enable the entire source or filter by content type and specific items.

Examples: - enable_library_source("tome-of-heroes") - Enable all content - enable_library_source("tome-of-heroes", content_type="class") - Enable all classes - enable_library_source("tome-of-heroes", content_type="class", content_names=["dragon-knight"]) - Enable specific class

Disable a library source for the current campaign.

Removes a library source from the campaign's enabled content. The source will no longer be available for use in this campaign.

Args: source_id: The source identifier (use list_enabled_library to see enabled sources)

List all library sources enabled for the current campaign.

Returns a formatted list of all library sources that have been enabled for use in the current campaign, including any content filters.

Configure the Claudmaster AI DM settings for the current campaign.

Call with no arguments to view current configuration. Provide specific fields to update only those settings (partial update). Set model_profile to switch all model settings at once (quality/balanced/economy). Set interaction_mode to switch how the DM communicates (independent of model_profile). Set reset_to_defaults=True to restore all settings to their default values.

Start or resume a Claudmaster AI DM session.

End or pause a Claudmaster AI DM session, saving all state.

Get the current state of a Claudmaster AI DM session.

Process a player action in the current Claudmaster session.

Discover D&D adventures by theme, keyword, level range, or storyline.

Search and browse official D&D 5e adventure modules from the 5etools index. Results are grouped by storyline and presented without spoilers.

Empty query with no filters returns a summary of all available storylines.

Keyword mapping examples:

• "vampire", "gothic", "horror" → Ravenloft

• "school", "magic school" → Strixhaven

• "dragon", "cult" → Tyranny of Dragons

• "heist" → Keys from the Golden Vault, Waterdeep

• "space" → Spelljammer

Load a D&D adventure module and integrate it with your campaign.

This tool orchestrates the complete adventure loading workflow:

1. Downloads and parses adventure content from 5etools (or uses cached version)

2. Creates a new campaign or uses the current one

3. Binds the module to the campaign for progress tracking

4. Auto-populates Chapter 1 entities (locations, NPCs, starting quest) to begin play

The tool respects spoiler boundaries: only Chapter 1 content is revealed. Later chapters remain hidden until you progress through the adventure.

Examples:

• load_adventure("CoS") - Load Curse of Strahd into current campaign

• load_adventure("LMoP", "Lost Mine Campaign") - Create new campaign for Lost Mine of Phandelver

• load_adventure("SCC-CK", populate_chapter_1=False) - Load Strixhaven intro without auto-population

Common adventure IDs:

• CoS: Curse of Strahd

• LMoP: Lost Mine of Phandelver

• HotDQ: Hoard of the Dragon Queen

• PotA: Princes of the Apocalypse

• OotA: Out of the Abyss

• ToA: Tomb of Annihilation

• WDH: Waterdeep: Dragon Heist

• WDMM: Waterdeep: Dungeon of the Mad Mage

• BGDIA: Baldur's Gate: Descent into Avernus

Use the discover_adventures tool to search for more adventures by theme or level range.

Export a character to a Markdown sheet file.

Generates a beautiful Markdown character sheet with YAML frontmatter in the campaign's sheets/ directory. The sheet can be viewed in any Markdown editor, with optional Meta-Bind support for Obsidian.

Regenerate all character sheets for the current campaign.

Useful after bulk changes or to ensure all sheets are up to date.

List pending player edits from character sheet files.

Shows changes detected from player-edited Markdown sheets that are waiting for DM approval.

Approve or reject pending player edits from a character sheet.

When approved, changes are applied to the character's JSON data. When rejected, the sheet is regenerated from the current server data, overwriting the player's edits.

Export campaign content as a portable compendium pack.

Creates a JSON pack file containing selected campaign entities (NPCs, locations, quests, encounters). Supports selective export by entity type, location filter, or full campaign backup.

The pack is saved to the packs/ directory inside the data folder.

Import a compendium pack into the current campaign.

Loads a CompendiumPack JSON file and imports its entities (NPCs, locations, quests, encounters) into the active campaign. Handles name conflicts via the chosen conflict mode. Regenerates all entity IDs and re-links cross-references.

Use preview=true for a dry-run that shows what would happen without changing anything.

List all available compendium packs in the packs directory.

Scans the packs/ directory for JSON pack files and returns their names, descriptions, entity counts, and file paths.

Validate a compendium pack file without importing it.

Checks the pack for schema conformance, version compatibility, entity count consistency, and required fields. Returns a detailed validation report.

Query what the party knows about the world.

Searches the party's collective knowledge — facts they have learned through NPC interactions, observation, investigation, reading, and other means. Returns matching facts with details on how they were learned.

Use with no arguments to list all known facts. Provide a topic to search for specific knowledge. Optionally filter by source or acquisition method.

Import a public D&D Beyond character into the current campaign.

Provide a D&D Beyond character URL (e.g., https://www.dndbeyond.com/characters/12345678) or just the numeric character ID. The character must be set to Public on D&D Beyond.

Import a character from a local JSON file into the current campaign.

Currently supports D&D Beyond JSON format. Save the JSON from your browser's developer tools (Network tab -> character request -> Response).

DM can send private messages to individual players via this tool.

Messages are stored in the session coordinator and can be retrieved by the recipient player. Only visible to the specified recipient.

Start the Party Mode web server for multi-player sessions.

Launches a background HTTP server that allows multiple players to connect via their phones or browsers. Automatically generates authentication tokens and QR codes for each player character in the current campaign.

Returns connection URLs and QR code file paths for each player.

Stop the Party Mode web server and disconnect all players.

Gracefully shuts down the server and closes all WebSocket connections.

Get the current status of the Party Mode server.

Shows server info, connected players, and action queue stats.

Pop the next pending player action from the Party Mode queue.

Returns the action details (player_id, action_id, text, timestamp) and remaining queue count, or reports that the queue is empty.

Resolve a player action and broadcast the response to connected players.

After processing a player action (rolling dice, narrating outcome, updating state), call this tool to push the response to the WebSocket broadcast queue.

Signal to players that the DM is preparing the next narrative.

Call this immediately after party_pop_action to give players instant visual feedback (animated dots + message) while you think and generate the response. The indicator disappears automatically when you call party_resolve_action.

Retrieve a pre-generated narrative variant for a combat turn.

If the prefetch engine has a cached variant for this turn, returns a refined narrative instantly (no main-model call needed). On cache miss, falls back to full generation with the main model.

Call this right after party_thinking, before writing your own narrative. If 'cached' is true in the response, use 'narrative' as your starting point and adjust only the details that differ from actual game state.

Kick a player from the Party Mode session.

Disconnects their WebSocket, revokes their token, and deactivates them in the PC registry. They will need a new token to rejoin.

Generate a new token and QR code for a player, invalidating their old token.

Use when a player needs a new connection link (lost QR code, security concern, or after being kicked and readmitted).

Check if a newer version of dm20-protocol is available.

Compares the installed version with the latest on GitHub. Returns update status, current/latest versions, and upgrade command if needed. Call this at session start to notify the user about available updates.

Fetch the latest release notes from the CHANGELOG.

Returns the most recent changelog entries (Unreleased + last released version) from the GitHub repository. Use this to show users what's new.