Wolfcha: an AI Werewolf table where you take one seat

The seat-filling problem Wolfcha actually solves

Werewolf is a social deduction game that needs eight to twelve people in a room at the same time. That is the constraint Wolfcha attacks. The README frames the project around the part of Werewolf that is hardest to schedule: a complete table of distinct players. You choose a role, enter an 8 to 12 seat game, and the AI handles every other personality, secret, accusation and vote.

The intended user is a solo player who wants the deduction loop without the logistics, and secondarily someone who wants to observe LLM agents behaving under hidden information. The README describes the result as deduction, bluffing and chaos on demand. That phrase is doing real work: the appeal is not a balanced competitive game but a table that produces unpredictable conversation from a fixed ruleset.

Eight roles are listed as playable: Villager, Werewolf, White Wolf King, Seer, Witch, Hunter, Guard and Idiot. The README states that conversations are generated in real time, so the same role assignment can produce a different table on a second run. That is the core promise, and it is also the main thing you cannot verify without playing.

Night, speech, vote: the round loop and what the models are given

The README lays out a four-step cycle. Night falls, and Werewolves choose a target while special roles act on private information. Then the table speaks: every surviving player explains, suspects, misdirects, or pushes a read. Then everyone votes, turning conversation into a decision. Then new deaths and revealed information reshape the next round.

Two design claims sit underneath that loop. The first is table-aware memory: players follow speeches, votes, deaths and changing suspicions. The second is that decisions carry intent, meaning an agent accuses, defends, bluffs, follows or holds back according to its faction goal. The README also separates personality from role, describing each AI as having a stable personality layered over a hidden game role. That distinction matters, because it means a Werewolf and a Villager can share a speaking style while holding different objectives.

The repository layout supports the description of a structured game rather than a single prompt. There is a src/game/phases/ directory with test files for factual context, context regressions and vote resume, plus src/hooks/game-phases/ tests for the day phase and badge phase. A speech-order test and a streaming-speech-parser test sit alongside them. Whatever the exact implementation, the code is organised around phases that can be tested in isolation, and the package.json exposes a single script that runs the whole single-player context suite at once. The README does not document the prompt format or the context window strategy, so how memory is trimmed over a long game is not something a reader can check from the documentation alone.

Running Wolfcha locally with pnpm

The README gives a short local path and requires Node.js and pnpm. The commands clone the repository, install dependencies, copy the environment template, and start the development server. Note that the dev script passes --webpack, so the local server is not using Turbopack by default.

git clone https://github.com/oil-oil/wolfcha.git
cd wolfcha
pnpm install
cp .env.example .env.local
pnpm dev

After the server starts, open http://localhost:3000. The README states that you configure the providers you need in .env.local and that the available variables are documented in .env.example. That file is where the real setup work lives. It includes keys for ZenMux, TokenDance, MiniMax, DashScope, NewAPI and Supabase, plus a TOKENDANCE_BASE_URL and a MINIMAX_TTS_MODEL set to speech-01-turbo. There are also payment-related variables such as WATCHA_PAY_API_KEY and TOKENPAY_ENCRYPTION_KEY, and the comments in the file say the encryption key should be generated with openssl rand -base64 32 and configured only on the server.

openssl rand -base64 32

If you only want to see the game loop, the payment variables are the ones to leave blank; the file itself notes that Stripe is retained only for historical order callbacks and that new orders are disabled. The README does not say which single provider is sufficient to start a game, so expect to read .env.example carefully before the first round works. There is also a test script for the single-player context suite if you want to check the game logic without a live model call, and separate audit scripts that explicitly require .env.local and live credentials.

Where Wolfcha is the wrong tool

The clearest limitation is the one the roadmap admits. Multiplayer with friends and AI players is listed as a future item, not a shipped feature. If your goal is a human table with a couple of bots filling gaps, this is not that product yet. The README's own framing, one human and a table that talks back, is the boundary.

The second limitation is cost and dependency. Every speech, vote and night action is a model call, and the environment file expects keys from multiple vendors. A twelve-seat game with several rounds of conversation is a lot of generated text, and the README gives no token budget, no cost estimate and no rate-limit guidance. Anyone running this locally is exposed to whatever their provider charges, with no documented ceiling.

The third is verification. There is a substantial test suite for game phases and context handling, but the README does not describe how the project measures whether an AI player is actually reasoning about the table rather than producing plausible Werewolf-shaped text. Personality and memory are asserted as features, not demonstrated with evaluation results. For a project whose entire value is agent behaviour, that is the gap a skeptical reader should notice first.

How it differs from a general multi-agent framework

The obvious alternative for someone who wants LLM agents in a social setting is a general agent framework such as a multi-agent conversation library, where you define agents, give them roles and let them talk. The difference in approach is that a framework gives you a conversation and leaves the game to you. Wolfcha ships the game: the night phase, the speech order, the vote, the role set with special abilities, and the state transitions between rounds. That is why the repository has a src/game/phases/ directory and vote-resume tests rather than a generic message bus.

The trade-off runs the other way too. A general framework lets you swap in any scenario, any turn structure and any number of agents. Wolfcha is fixed to Werewolf and to the roles its README lists. If you want to study multi-agent negotiation in a different setting, adapting Wolfcha means fighting its phase machine, and a framework would be the shorter path. If you want a working table tonight, the framework is the longer one.

Maintenance, licensing and the cost of upgrading

The repository is not archived, and the last push was on 2026-09-09. The only release listed is v1.0.0 from 2026-02-16, while package.json still carries version 0.1.0, so the release tag and the package version do not agree. That is worth knowing before you pin anything: there is no documented upgrade path between versions, and the README does not describe a migration process.

Licensing has a genuine inconsistency. The README's license section links to an MIT licence, while the repository metadata for this project states Apache-2.0. Both are permissive, but they are not the same document, and Apache-2.0 includes an explicit patent grant that MIT does not. If you plan to redistribute or host a modified version, read the actual LICENSE file in the repository root rather than either summary, and treat the discrepancy as unresolved until the maintainers reconcile it. Nothing here is legal advice.

Operationally, the upgrade cost is tied to the environment file. The .env.example includes payment and OAuth variables alongside model keys, and the comments show that some integrations are legacy, such as Stripe being kept only for historical callbacks. Expect to re-read that file after a pull rather than assuming your existing .env.local still covers everything.

Editorial conclusion

Adopt Wolfcha if you want a full Werewolf table without recruiting nine friends, or if you want to watch LLM agents argue under hidden roles. Skip it if you need human-versus-human play, since the roadmap lists multiplayer with friends as a future item rather than a shipped feature. Before running it locally, open .env.example and confirm you have keys for the providers you intend to use, because the README points there for the available variables and the game needs at least one. Verify the licence file too: the README links MIT while the repository metadata says Apache-2.0.

Frequently asked questions

Official sources

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