An unofficial, fan-made web app for running Blood on the Clocktower in-person. Storytellers manage the full game through an interactive digital grimoire, while players join live sessions from their own devices by syncing with the town square in real time to receive their character token and track the game state.
Grim.Demo.compressed.mp4
screen-20260707-141917-1783448090615.compressed.mp4
Both modes use a shared distribution engine that respects official team counts for 5–15 players and dynamically resolves complex setup roles and jinxes — for example, Legion restructures the entire evil team composition, Atheist removes the evil team entirely, Baron and similar roles adjust outsider counts automatically, and linked pairs like Choirboy ↔ King are enforced.
Classic manual storyteller mode:
- Custom Script Support — Upload custom
.jsonscript files to automatically load character lists, icons, and attributes. - Manual Assignment — Fully dictate player assignments, set Drunk/Marionette status, and adjust team composition.
- Interactive Grimoire — Responsive, circular layout showing alive status, dead votes, traveler characters, custom storyteller notes, and game phase states (Day/Night toggles).
Semi-randomized player preference draft:
- Preference Drafting — Add players and let them submit up to 4 preferred roles for Townsfolk, Outsider, Minion, and Demon teams.
- Randomized Assignment — Roles are assigned based on player preferences using the shared distribution engine above.
Players join from their own devices using a 4-letter room code:
- Character Token Reveal — Players receive their assigned character token on their device when the grimoire opens.
- Real-Time Sync — The town square layout, player statuses, and day/night phase stay in sync across all connected devices.
- Whale Buffet Preferences — In Whale Buffet mode, players submit their role preferences directly from their phone before assignment.
- Player Notes Tracker — Players can track character claims and alive/dead statuses from their own device throughout the game.
The app is installable as a standalone app via "Add to Home Screen" on Android and iOS, giving a full-screen native-app experience without the browser UI.
All state is persisted to localStorage, so refreshing the page won't lose your storyteller grimoire.
- Node.js 20+
- npm
Real-time session routing is powered by ntfy. A self-hosted ntfy instance is required for practical use — the public ntfy.sh server will rate-limit a game session almost immediately.
- Copy
.env.examplein the root of the project to a new file named.env:cp .env.example .env
- Set the URL to your self-hosted ntfy server:
VITE_NTFY_SERVER_URL=your-ntfy-server.example.com
- If you deploy using Docker or environment configurations, ensure
VITE_NTFY_SERVER_URLis defined in your environment during build time.
npm install
npm run devThe dev server starts at http://localhost:5173 with hot module replacement.
npm run build
npm run previewdocker compose up --buildThe app will be available at http://localhost:8080.
# Run detached
docker compose up --build -d
# Stop
docker compose downdocker build -t tiny-grimoire .
docker run -p 8080:80 tiny-grimoire- React 19 + TypeScript
- Vite — build tooling and dev server
- Tailwind CSS — styling
- Lucide React — icons
- Nginx — production static file serving (in Docker)
- The Pandemonium Institute — Creators of Blood on the Clocktower.
- botc-icons — Role icons are sourced from this community project and downloaded automatically at build time. They are not committed to this repository (
public/icons/is gitignored). This art is community/playtest work that remains the copyright of its respective artists and owners; it is not covered by this project's MIT license, and this project claims no rights to it.
This project is licensed under the MIT License.
This is an unofficial, fan-made tool, created and distributed free of charge. It is not affiliated with, endorsed by, or sponsored by The Pandemonium Institute.
Blood on the Clocktower, its characters, and its associated names and artwork are the property of Steven Medway and The Pandemonium Institute. This project's MIT license covers only its own source code — it grants no rights to any Blood on the Clocktower intellectual property. Character names, ability text, and role icons remain the property of their respective owners.