Wolfcha: an AI Werewolf table where one human fills the remaining seats

The scheduling problem Wolfcha actually solves

Werewolf needs eight to twelve people in the same room at the same time. That is the real constraint, not the rules. The rules fit on an index card. Getting nine adults to hold a thirty-minute conversation with hidden roles and no one dropping out is the part that fails, and it fails most often for people who want to play regularly rather than once at a party. Wolfcha takes one human seat and fills the rest with LLM-controlled players. The README states the premise directly: choose your role, enter an 8 to 12 seat game, and the AI handles every other personality, secret, accusation, and vote. The target user is someone who wants the deduction loop without the logistics, and secondarily someone who wants to watch how language models behave when they have something to hide. The spectator mode in the feature list points at that second audience explicitly.

Two layers per AI player: personality and hidden role

The design detail worth noticing is that each AI carries two separate things. The README describes a stable personality layered over a hidden game role, and separates that from table-aware memory. Personality is the surface: how a player talks, how aggressive or conciliatory they are. Role is the secret: villager, werewolf, seer, and so on. Keeping these apart matters because a model that only knows its role tends to play the role rather than the person, and a model that only knows its personality has no reason to lie. The memory layer is what makes the game cohere across rounds. According to the README, players follow speeches, votes, deaths, and changing suspicions, and they accuse, defend, bluff, follow, or hold back according to their faction goal. That is a claim about what the prompts are fed, not about how well it works. The repository does not publish transcripts, so the quality of that memory is something you would have to judge by playing.

The round loop: night, speech, vote, consequences

The README lays the loop out in four steps. Night falls, and werewolves choose a target while special roles act on private information. Then every surviving player speaks, explaining, suspecting, misdirecting, or pushing a read. Then the group votes, turning conversation into a decision. Then new deaths and revealed information reshape the next round. This is standard Werewolf, and the interesting part is the second step, because it is where an LLM has to produce something that sounds like a read rather than a summary. The playable roles listed are Villager, Werewolf, White Wolf King, Seer, Witch, Hunter, Guard, and Idiot. The README notes that conversations are generated in real time, so the same setup can produce a very different table. That is a property of sampling, not a guarantee of variety. Nothing in the material describes how votes are tallied, how ties resolve, or what happens if a model returns malformed output, so treat the loop as described rather than as specified.

Getting it running locally

The README gives a short setup path. Requirements are Node.js and pnpm. Then: git clone https://github.com/oil-oil/wolfcha.git, cd wolfcha, pnpm install, cp .env.example .env.local, pnpm dev, and open http://localhost:3000. That is the whole documented procedure. The critical line is the one about configuration: the README says to configure the providers you need in .env.local and that the available variables are documented in .env.example. So the actual list of config keys lives in a file the README does not reproduce, and the article cannot invent it. What the material does tell you is which providers are in play. The project description names DeepSeek, Qwen, and Gemini among the LLMs, and the sponsors section credits TokenDance with core game flow, roleplay, and summaries, and DashScope with AI capability support. DashScope is Alibaba's model service, which lines up with the Qwen mention. If you plan to self-host, .env.example is the first file to read, before you run pnpm install, because it tells you how many separate provider accounts a full table needs.

Where the documentation stops being useful

The README is a landing page, not a manual. It tells you the game exists, what it looks like, and how to start the dev server. It does not tell you how a game state is represented, how player memory is stored or truncated between rounds, how prompts are assembled, or what happens when a provider rate-limits you mid-game. For a project whose entire behaviour depends on model output, the absence of any prompt or schema documentation is the main gap. There is also a concrete problem in the metadata. The repository is listed as Apache-2.0, while the README's license section links to an MIT LICENSE file. Those are different licences with different patent and notice requirements, and the README and the repository metadata disagree. That is not a nuance to wave away. Anyone intending to reuse the code should open the LICENSE file at the repository root and treat what is actually in that file as the answer, rather than either the README text or the metadata field.

When a single-model agent is the better choice

The obvious alternative is writing your own Werewolf harness against one model provider, or adapting an existing agent framework to run the table. The difference in approach is control over the prompt and the state. Wolfcha ships an opinionated game: fixed roles, a fixed round structure, a personality layer, and a memory layer, all wired to whatever providers the environment configures. If you want to study how a specific model handles deception, that opinionated surface sits between you and the model, and you cannot easily see or change the prompt without reading the source. A single-model harness you write yourself gives you the transcript, the prompt, and the state transitions in a form you control, at the cost of building the role logic, the vote tallying, and the UI. Wolfcha is the better choice when you want the game to exist today. A custom harness is the better choice when the game is the experiment rather than the product. The README's roadmap lists richer memory and bluffing as future work, which suggests the authors themselves treat the current agent behaviour as unfinished.

Upgrade surface and what maintenance looks like

The project has one release, v1.0.0, dated 2026-02-16, and the last push to main is 2026-09-09. The stack is Next.js 16, TypeScript, Tailwind CSS 4, Jotai, Radix UI, Framer Motion, and Tiptap. That is a modern frontend stack, and it is also a moving one: a Next.js major upgrade and a Tailwind major upgrade are both on the horizon by virtue of the versions already in use, and either can require touching component code across the app. Because the LLM calls are the product, provider-side changes matter as much as dependency bumps. If a provider retires a model name or changes a response shape, the game breaks in a way no lockfile protects you from. The roadmap lists mobile play, post-game review and free chat, richer memory, special mechanics such as time rewind and AI insight, multiplayer with friends and AI players, and community ratings for AI personalities. Those are ambitions, not commitments, and none of them appear in the v1.0.0 release. Budget for reading the source when you upgrade, not just bumping versions.

Editorial conclusion

Adopt Wolfcha if you want a playable Werewolf table without scheduling nine other people, or if you are studying how LLM agents behave under hidden information and social pressure. Do not adopt it if you need a documented, provider-agnostic API contract, or if you expect the repository to tell you which models produce good play. Before committing, read .env.example in full, count how many provider variables your deployment needs, and check the LICENSE file at the repository root against the Apache-2.0 metadata, because the README says MIT and the two cannot both be right.

Official sources

1. License: Apache-2.0
2. oil-oil/wolfcha on GitHub
3. Project website
4. README
5. Releases