LazyD&D - Terminal-based D&D Panel System for Dungeon Master

A lazygit-inspired terminal UI for managing your D&D game sessions, built with Go and Bubble Tea.

LazyD&D Screenshot

Features

🎲 Dice Roller Panel - Roll any dice with simple commands (2d6, 1d20+5, etc.) + Critical Hit Detection ⚔️ Initiative Tracker Panel - Manage combat initiative for players and monsters 🎨 Color-Coded HP - HP display changes color based on health (green/orange/red) ✨ Spells Panel - Search and browse D&D 5e spells with fuzzy search 🐲 Monsters Panel - Search and view detailed monster stat blocks with fuzzy search 📝 Notes Panel - Track session notes, NPCs, quests with Markdown-style formatting ⚡ Encounter Builder - Pre-plan balanced encounters with CR calculator, auto-generator, and templates 💾 Campaign Save/Load - Save your game state and resume later 🔄 Auto-Save - Automatic saving every 5 minutes 🔗 Monster Integration - Link monsters to initiative with full action support 🏃 Instant Transitions - Lightning-fast panel switching with zero latency ❌ UI Error Messages - Clear error notifications displayed in the UI, not just terminal

Installation

Docker (Easiest)

Run with Docker (no installation needed):

docker run -it --rm ghcr.io/zingazzi/lazydnd:latest

Or build locally:

git clone https://github.com/zingazzi/lazydnd
cd lazydnd
./docker-build.sh
./docker-run.sh

See DOCKER.md for detailed Docker documentation.

Quick Install (Recommended)

One-line installer (Linux/macOS):

curl -sSL https://raw.githubusercontent.com/zingazzi/lazydnd/main/install.sh | bash

Or download and run the installer:

curl -O https://raw.githubusercontent.com/zingazzi/lazydnd/main/install.sh
chmod +x install.sh
./install.sh

Manual Installation

Download the latest release for your platform from the Releases page:

Linux (Intel/AMD):

curl -L -o lazydnd https://github.com/zingazzi/lazydnd/releases/latest/download/lazydnd-linux-amd64
chmod +x lazydnd
sudo mv lazydnd /usr/local/bin/

Linux (ARM):

curl -L -o lazydnd https://github.com/zingazzi/lazydnd/releases/latest/download/lazydnd-linux-arm64
chmod +x lazydnd
sudo mv lazydnd /usr/local/bin/

macOS (Intel):

curl -L -o lazydnd https://github.com/zingazzi/lazydnd/releases/latest/download/lazydnd-macos-amd64
chmod +x lazydnd
sudo mv lazydnd /usr/local/bin/

macOS (Apple Silicon):

curl -L -o lazydnd https://github.com/zingazzi/lazydnd/releases/latest/download/lazydnd-macos-arm64
chmod +x lazydnd
sudo mv lazydnd /usr/local/bin/

Windows: Download lazydnd-windows-amd64.exe from the Releases page and add it to your PATH.

Build from Source

git clone https://github.com/zingazzi/lazydnd
cd lazydnd
go build -o lazydnd
./lazydnd

Cross-Platform Build

Build executables for all platforms:

./build.sh

This creates executables in the build/ directory for:

Linux (amd64, arm64)
macOS (amd64, arm64)
Windows (amd64)

Configuration

LazyDnD uses a configuration file at ~/.config/lazydnd/config.json that allows you to customize:

Theme colors - Primary, border, highlight, error, and success colors
Save directory - Custom location for campaign saves
Auto-save settings - Enable/disable and interval
Dice roller - History size, minimum value, show individual rolls
Initiative tracker - Auto-sort, show HP/AC, round counter
Display - Help hints, compact mode, line wrapping
Backups - Enable/disable, location, maximum backups

Example: Custom save location

{
  "paths": {
    "save_directory": "~/Documents/DnD/LazyDnD",
    "backup_enabled": true,
    "max_backups": 15
  }
}

See CONFIGURATION.md for complete configuration documentation and examples.

Usage

Command Line Options

lazydnd           # Start the application
lazydnd --version # Print version number and exit
lazydnd --debug   # Enable debug logging to ~/.config/lazydnd/debug.log
lazydnd --help    # Show available options

Debug Mode: When enabled with --debug, the application logs all events to ~/.config/lazydnd/debug.log including:

Key presses and handlers
Multi-target operations
Condition additions/removals
Spell tracking events
State changes

Useful for troubleshooting issues. You can view the log in real-time with: tail -f ~/.config/lazydnd/debug.log

Fuzzy Search: Both Monsters and Spells panels now use intelligent fuzzy search that:

Handles typos and misspellings (e.g., "frbl" finds "Fireball")
Matches partial names in any order (e.g., "drag red" finds "Adult Red Dragon")
Automatically sorts results by match quality
More forgiving than exact substring matching
Just start typing to see suggestions!

Level/CR Filters:

CR Filter (Monsters Panel): Browse monsters by Challenge Rating with autocomplete:

Press f in the Monsters panel to open CR filter
Type a CR value as you type, monsters matching that CR appear instantly:
- Exact: 5 → shows all CR 5 monsters
- Range: 0-5 → shows CR 0 through 5
- Minimum: 10+ → shows CR 10 and above
- Fractional: 1/4, 1/2, 0.5 all work!
Use ↑↓ arrow keys to navigate the list
Press Enter to select a monster and view its full details
Press Esc to cancel and go back
Perfect for finding level-appropriate encounters quickly!

Spell Level Filter (Spells Panel): Browse spells by spell level with autocomplete:

Press f in the Spells panel to open level filter
Type a spell level, spells matching that level appear instantly:
- Exact: 3 → shows all 3rd-level spells
- Range: 0-2 → shows cantrips through 2nd-level
- Minimum: 5+ → shows 5th-level and higher
Use ↑↓ arrow keys to navigate the list
Press Enter to select a spell and view its full details
Press Esc to cancel and go back
Great for finding spells your character can cast!

Global Navigation & Controls

Panel Navigation

| Key | Action | |-----|--------| | 1-4 or F1-F4 | Jump directly to specific panel | | Tab | Cycle forward through panels | | Shift+Tab | Cycle backward through panels | | ↑ ↓ | Navigate lists and scroll content | | Esc | Cancel input or exit current mode | | ? | Show help popup with all keybindings | | q or Ctrl+C | Quit application |

Campaign Management

| Key | Action | |-----|--------| | Ctrl+S | Save campaign (quick save if already saved, or open save dialog) | | Ctrl+L | Load campaign (shows list of saved campaigns) | | Ctrl+N | Rename current campaign |

Campaign Features:

💾 Auto-Save: Campaigns automatically save every 5 minutes
📁 Save Location: All campaigns stored in ~/.lazydnd/
📊 Status Bar: Shows current campaign name and last save time
🔄 Full State: Saves entire initiative tracker with all monster links

Panel-Specific Features

🎲 Panel 1: Dice Roller

Keybindings: | Key | Action | |-----|--------| | Enter | Start dice input mode | | r | Reroll last command | | Type dice notation and press Enter | Roll dice |

Dice Notation Examples:

Simple Rolls: 1d20, 2d6, 3d8, 4d10
With Modifiers: 2d6+3, 1d20-1, 1d8+5
Multiple Dice: 2d8+3d6, 1d6-1d4, 2d8+3d6-1d4
Complex Expressions: 1d6+3+2d8-5, 2d6-1d4+3
Comma-Separated: 1d8+3, 3d6-1 (rolls multiple expressions)
Advantage/Disadvantage: 1d20 adv, 2d6 dis
Critical Damage: 2d8 crit, 3d6+5 crit (auto-doubles dice or max damage)

🎯 Critical Hit System:

Auto-Detection: Natural 20 on d20 rolls shows ★ CRITICAL HIT! ★ banner with 🎯 icon
Manual Crits: Roll critical damage with 2d8 crit, 3d6+5 crit, etc.
Monster Attacks: When a monster attacks and rolls nat 20, damage dice automatically double!
- Attack roll is checked first (1d20+modifier)
- If natural 20, damage dice are rolled as critical automatically
- Example: Goblin hits with nat 20 → damage rolls as 1d6 crit (2d6 or max+1d6)
Two Modes (configurable in ~/.config/lazydnd/config.json):
- "double" (default): Roll all damage dice twice (D&D 5e standard)
  - Example: 2d8 crit → rolls 4d8 total (2d8 + 2d8)
- "max": Maximum damage + one roll (popular house rule)
  - Example: 2d8 crit → 16 (max) + 1 roll of 2d8
Visual Celebration: Gold and dark red banner, target emoji 🎯
Enable/Disable: Set critical_hit_enabled: false in config to turn off

🔥 Preset Spell Macros (35+ Built-in): Just type the spell name and press Enter:

Cantrips: eldritch_blast, fire_bolt, toll_the_dead
Popular Spells: fireball, lightning_bolt, magic_missile, cure_wounds
High-Level: disintegrate, chain_lightning, finger_of_death 🎯 Custom Macros:
Create: my_attack=1d20+5
Execute: my_attack
Skill Checks: stealth, perception+5 (for selected character)
Group Initiative: group (rolls init for all monsters)

See PRESET_MACROS.md for full list!

Features:

✅ Minimum value of 1 (D&D rule)
✅ Standard D&D dice: d4, d6, d8, d10, d12, d20, d100
✅ Zocchi's dice: d3, d5, d7, d14, d16, d24, d30
✅ Roll history displayed
✅ Quick reroll with 'r' key

⚔️ Panel 2: Initiative Tracker

LazyD&D Attack

Keybindings: | Key | Action | |-----|--------| | p | Add player to initiative (name, initiative, AC) | | m | Add monster manually (name, HP, AC, initiative) | | Enter | Enter edit mode (navigate entries with ↑↓) | | n | Next turn (advance initiative) | | x | Reset combat (reset turn and round counters)

Lazydnd

Install / Use

README