{"id":49006476,"url":"https://github.com/t11z/tavern","last_synced_at":"2026-04-18T20:13:01.088Z","repository":{"id":348869392,"uuid":"1200179540","full_name":"t11z/tavern","owner":"t11z","description":"An AI Game Master for tabletop RPG campaigns — open source, self-hosted, and cheaper than a coffee.","archived":false,"fork":false,"pushed_at":"2026-04-03T13:04:00.000Z","size":6060,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-03T13:33:45.625Z","etag":null,"topics":["5e","ai","claude","discord-bot","dnd","fastapi","game-master","llm","open-source","python","react","self-hosted","srd","tabletop-rpg"],"latest_commit_sha":null,"homepage":"https://t11z.github.io/tavern","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/t11z.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-03T05:51:32.000Z","updated_at":"2026-04-03T12:17:02.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/t11z/tavern","commit_stats":null,"previous_names":["t11z/tavern"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/t11z/tavern","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/t11z%2Ftavern","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/t11z%2Ftavern/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/t11z%2Ftavern/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/t11z%2Ftavern/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/t11z","download_url":"https://codeload.github.com/t11z/tavern/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/t11z%2Ftavern/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31982836,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T17:30:12.329Z","status":"ssl_error","status_checked_at":"2026-04-18T17:29:59.069Z","response_time":103,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["5e","ai","claude","discord-bot","dnd","fastapi","game-master","llm","open-source","python","react","self-hosted","srd","tabletop-rpg"],"created_at":"2026-04-18T20:12:59.646Z","updated_at":"2026-04-18T20:13:01.049Z","avatar_url":"https://github.com/t11z.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🍺 Tavern\n\n**An AI Game Master for tabletop RPG campaigns — open source, self-hosted, and cheaper than a coffee.**\n\n\u003e A solo session runs ~$0.28 in API usage. Four players for three hours: ~$0.70.\n\u003e No subscription. No platform fees. Just your Anthropic API key and `docker compose up`.\n\nTavern is a self-hosted, SRD 5.2.1-compatible RPG engine powered by Claude as your Game Master. It handles the rules. Claude handles the story. Play in your browser, on your phone at the table, or in a Discord voice channel with friends.\n\n---\n\n## ✨ Features\n\n- 🎲 **Full SRD 5e rules engine** — combat, spells, conditions, and character progression implemented in code, not in prompts\n- 🧠 **Claude as Game Master** — narrative, NPC behaviour, and world reaction powered by Claude\n- 🎭 **Two ways to play** — browser-based web client or Discord bot with voice support\n- 💾 **Persistent campaigns** — state survives across sessions via PostgreSQL\n- 👥 **Solo and multiplayer** — play alone or with a group in real-time\n- 📱 **Table mode** — shared display on a laptop, each player on their phone\n- 💸 **Cost-efficient** — prompt caching and mixed model routing keep API costs minimal\n- 🐳 **One-command setup** — a single `docker compose up` is all it takes\n- 🌍 **Community worlds** — import custom world presets or use the included Shattered Coast setting\n\n---\n\n## 🚀 Quickstart\n\n### Prerequisites\n\n- [Docker](https://docs.docker.com/get-docker/) and Docker Compose\n- An [Anthropic API key](https://console.anthropic.com/)\n\n### Run\n\n```bash\ngit clone https://github.com/t11z/tavern\ncd tavern\ncp .env.example .env\n# Add your ANTHROPIC_API_KEY to .env\n# Optionally add DISCORD_BOT_TOKEN for Discord integration\ndocker compose up\n```\n\nOpen [http://localhost:3000](http://localhost:3000) and start your adventure.\n\n---\n\n## 🎮 How to Play\n\n**In your browser**: Open the web client, create a campaign, build a character, and play. Solo or invite friends via join code.\n\n**At the table**: Open the shared display on a laptop or TV. Each player joins on their phone by scanning a QR code. Claude narrates through the speakers.\n\n**On Discord**: Add the Tavern bot to your server, start a campaign in a text channel, and play — Claude narrates as the GM.\n\nSetup:\n1. Create a Discord application at [discord.com/developers/applications](https://discord.com/developers/applications) and add a bot user.\n2. Enable the **Message Content** privileged intent under *Bot → Privileged Gateway Intents*.\n3. Copy the bot token and add it to your `.env` file: `DISCORD_BOT_TOKEN=your-token-here`\n4. Run `docker compose up` — the `discord-bot` service starts automatically alongside the API.\n5. Invite the bot to your server using the OAuth2 URL (scopes: `bot`, `applications.commands`; permissions: `Send Messages`, `Manage Threads`, `Read Message History`).\n\nSee [`docs/game-design/discord-bot.md`](docs/game-design/discord-bot.md) for the full command reference and gameplay guide.\n\n---\n\n## 🏗️ Architecture\n\nTavern is a headless game server with a client-agnostic API. The web client and Discord bot are two reference clients — both first-class, both maintained by the core team.\n\nThe server separates two concerns:\n\n| Layer | Responsibility |\n|---|---|\n| **Rules Engine** | Deterministic SRD logic — dice, combat, spells, conditions |\n| **Narrator** | Claude handles narration, NPC behaviour, world reaction |\n\nClaude never sees raw rulebook text at runtime. It receives a structured state snapshot — character status, scene context, a rolling session summary — and responds as a narrator. The numbers come from your code.\n\n**Cost optimisations built in:**\n- Prompt caching for static context (system prompt, character sheet)\n- Haiku for low-complexity responses, Sonnet for narration\n- Rolling summary instead of full conversation history\n\nSee `docs/adr/` for the full set of architecture decision records.\n\n---\n\n## 🛠️ Tech Stack\n\n- **Backend**: Python 3.12+ / FastAPI\n- **Databases**: PostgreSQL 16+ (application data) · MongoDB via [5e-database](https://github.com/5e-bits/5e-database) (SRD data)\n- **Web Client**: React (Vite)\n- **Discord Bot**: Python (discord.py)\n- **LLM**: Anthropic API (provider-abstracted)\n- **Deployment**: Docker Compose\n\n---\n\n## 📦 SRD Data\n\nTavern's game data — spells, monsters, classes, species, equipment, and more — comes\nfrom the [5e-bits/5e-database](https://github.com/5e-bits/5e-database) project, a\ncommunity-maintained SRD 5.2.1 dataset served as a MongoDB container.\n\nNo manual import step is required. `docker compose up` starts the SRD database\nalongside everything else. The data is ready to query immediately.\n\n**Custom content**: GMs can add homebrew monsters, modify SRD creatures, and create\ncustom spells and items through the API. Custom content is reusable across campaigns.\nPer-campaign overrides let you tweak SRD entries for a specific campaign without\naffecting others.\n\n---\n\n## 📜 License \u0026 Attribution\n\nTavern is licensed under the [Apache License 2.0](LICENSE).\n\nThis work includes material from the System Reference Document 5.2.1 (\"SRD 5.2.1\") by Wizards of the Coast LLC, available at https://www.dndbeyond.com/srd. The SRD 5.2.1 is licensed under the Creative Commons Attribution 4.0 International License, available at https://creativecommons.org/licenses/by/4.0/legalcode.\n\nThis product is *5E compatible*.\n\n---\n\n## 🤝 Contributing\n\nContributions welcome. Architecture decisions are documented in `docs/adr/`. Please read them before proposing changes — accepted ADRs are binding constraints.\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n### SRD Content Contributions\n\nTavern's SRD data comes from [5e-bits/5e-database](https://github.com/5e-bits/5e-database).\n\nIf you find an error in the SRD data (wrong spell damage, incorrect monster AC, missing\nclass feature):\n\n1. Check the [5e-database issues](https://github.com/5e-bits/5e-database/issues) to see\n   if it's already reported.\n2. If not, open an issue or PR in the 5e-database repository. Fixes there benefit the\n   entire ecosystem, not just Tavern.\n3. Once the fix is released in a new 5e-database version, we bump the image tag in our\n   `docker-compose.yml`.\n\n**Custom content contributions** (community monsters, homebrew items, world-specific\ncreatures) are welcome. These live in the Instance Library and can be submitted as data\nfiles. See the custom content API documentation for the expected document format.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ft11z%2Ftavern","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ft11z%2Ftavern","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ft11z%2Ftavern/lists"}