How to Play

What this is

Village of Shadows is Werewolf (a.k.a. Mafia) played by seven seats, where every seat except one is an AI agent — each running its own model, its own persona, and its own isolated context, making its own decisions through real tool calls rather than a script. The one exception is you: pick a seat on the setup page and you play alongside the agents as a genuine player, not just a spectator.

Below the game itself, once it’s running, an Agent Engineering Debug panel shows the live orchestration graph, per-agent token usage, and a running feed of every node transition, turn, and MCP tool call — so you can watch how the agents are actually reasoning and acting, not just what they end up saying.

The standard roles

Roles are dealt at random the moment you click Start Game — nobody, including you, picks or knows their role in advance. A 7-seat game always deals the same deck: 2 werewolves, 1 seer, 1 doctor, and 3 villagers.

The expanded role pack

Enable Expanded roles under World rules to replace the three ordinary villagers with roles whose behavior is enforced by the server, not merely suggested in a prompt.

• Hunter. When killed at night or by vote, chooses one living player to take down before the graph continues.
• Mayor. Participates normally, but every validated village vote counts twice.
• Jester. Has an independent objective and wins instantly if the village votes them out.

How a round plays out

1. Night. The living werewolves first conduct a bounded private negotiation, with an opening proposal and one possible revision each. The graph deterministically resolves their final target, then the doctor protects and the seer investigates. Nobody else sees what happened until dawn.
2. Resolution. If the werewolves’ target wasn’t protected by the doctor, that player dies and their role is revealed to everyone.
3. Day discussion. Every living player speaks once, in turn order — accuse, defend, share a suspicion. Everything said here is public.
4. Vote. Every living player votes for one other player to eliminate. Whoever gets the most votes is cast out and their role is revealed.
5. Win check, after every death. Villagers win the instant every werewolf is dead. Werewolves win the instant they equal or outnumber everyone left alive. Otherwise, night falls again and the round repeats. In the expanded pack, the Jester wins immediately when voted out.

Configuring a game

• Who is human? Pick your own host seat and optionally mark more seats as human. The setup creates private, revocable join links; each browser is cryptographically bound to one seat and receives only that character’s permitted state.
• Name is just what everyone calls that seat in the transcript and log.
• Personality is not cosmetic — it’s written directly into that agent’s system prompt every single turn (“You are {name}, a {personality} villager…”). A seat you set to “grumpy” or “sly” or “anxious” will actually behave differently, because the model is told to.
• Provider & Model (AI seats only) — pick mock to play instantly offline with no API key (it makes scripted-but-legal moves so you can try the whole app for free), or a real provider (Claude, OpenAI, Gemini, Ollama) if you’ve configured that provider’s API key in the backend’s .env — for Ollama, make sure the local server is running and the model is already pulled.
• You can mix and match freely — a game can have several different real providers and models seated at once, alongside mock seats, all playing the same game together.
• Open Agent laboratory on any AI seat to tune risk, honesty, aggressiveness, reasoning depth, memory and tool strategy, token limits, timeout, retry, and fallback behavior. Presets can be saved, duplicated, exported, and re-used; the immutable base role and safety prompt remains in control.
• World rules enable expanded roles, deterministic village events, opt-in cross-game relationships, a room name, and a server-enforced total token ceiling.

Optional village events

One server-selected event can alter each day without bypassing ordinary action validation:

• Silence skips exactly one speaker for that discussion.
• Secret ballot hides individual votes until the sealed tally opens.
• Forced testimony changes who must speak first.
• Discovered evidence adds an ambiguous public clue for every mind to interpret.

Selection is deterministic under checkpoint replay, so a branch begins from the same world before your changed decision alters it.

Available hosted AI models

These are the reasoning and tool-calling models suggested by the setup screen. You can still type a different model ID in the editable model field. Before a game is created, every selected model receives a real readiness message and must successfully call the test tool.

Once the game starts

• When it’s your turn, the panel under the feed will prompt you directly — the game genuinely waits for your answer, with no timer, before continuing.
• God view (top right) shows everyone’s true role at all times, which is the best way to watch how the werewolves are playing their deception. Turn it off to only know what your own character would know, for a more immersive game.
• Pause / Continue (top right) freezes the game between turns and resumes it exactly where it left off, whenever you want.
• Voice Council is an explicit opt-in. Choose lifelike neural narration or a no-cost device voice, select ceremonial, measured, or urgent pacing, and mute, skip, or replay. Neural speech is AI-generated; visible persisted captions remain authoritative.
• Scroll down for the Agent Engineering Debug panel — drag to pan and scroll to zoom the live orchestration graph, and watch the activity feed for exactly when each agent’s turn starts, when it opens an MCP session, which tools it calls, and when it commits its decision.

After the village falls silent

• Perspective reconstructs exactly what one agent knew, believed, remembered, and could legally do at a chosen event.
• Deception report separates persisted facts from interpretation, then follows claims, suspicion shifts, vote pivots, and ignored clues.
• Branch replay restores a human interrupt from a real LangGraph checkpoint, replaces one answer, and continues as a new immutable game.
• Share replay publishes a sealed read-only snapshot. Public links exclude private actions; God Mode links require an extra secret and can expire or be revoked.
• Model tournament rotates roles across autonomous games and compares wins, deception, voting, survival, latency, tokens, and estimated spend.
• Relationship archive lets you inspect, edit, or erase opt-in memories between recurring personas. Previous secret roles are never carried forward.

Comprehensive feature guides

The repository includes player-facing guides for every shipped enhancement, including where to find it, how to operate it, what its signals mean, controlled experiments to try, and conclusions the evidence does not support.

• Play the live council — negotiation, beliefs, notes, multiple humans, voices, and events.
• Configure the experiment — roles, Agent Laboratory, relationships, and resilience.
• Use the post-game laboratory — Perspective, deception, branches, and replays.
• Run model tournaments — fair setup, metrics, costs, and analytical pitfalls.
• Read observability correctly — graph nodes, context, memory, tools, validation, and God Mode.