secret-hitler is a web port of the board game built on a pre-hooks React stack

A lobby, not a private room

The README describes the implementation model in a sentence that is easy to skim past. This codebase is a lobby style implementation, where anyone can make a game which is displayed on a list on the home page, the game starts when enough players are seated, and anyone can watch a game in progress.

That is a different application from the board game it adapts. There is no table, no passing of a device and no physical presence. A game is a URL, it appears on a public list, and people join it by sitting down. The spectator mode is the interesting part for an implementation, because the same SocketIO channel that carries a player's actions has to carry a viewer's view of the game state, and the back end has to keep the two consistent.

The front end is React with Redux, Sass and Semantic UI, which the README notes needs jQuery. The back end is Node with Express, Pug templates, Passport for authentication, MongoDB with Mongoose and SocketIO. The dependency list in the manifest matches that story, and it includes the pieces you would expect for an app with accounts and avatars, Passport strategies for local, Discord and GitHub logins, express-session wired to MongoDB and Redis stores through connect-mongodb-session and connect-redis, nodemailer with a Mailgun transport, a Discord webhook client, helmet and compression, and jimp with cropperjs and rc-slider for image handling on the client.

The game itself is the familiar one: a dramatic game of political intrigue in 1930s Germany where players are secretly divided into liberals and fascists, the fascists coordinate to install their leader, and the liberals try to find and stop the Secret Hitler before it is too late.

The README tells you not to work on it

The most valuable paragraph in this repository is the one that warns people off, and it deserves to be quoted rather than paraphrased.

The README says the tech to make this work is very old, from before React hooks, that it has had almost no oversight of public pull requests leading to some giant pasta style code, and that the author cannot recommend working on it, looking at it, or exposing it to sunlight. It then adds: it does work, though.

That is an unusual and honest disclaimer. It tells you three separate things. The code predates the hooks model of React, so the component patterns in it are not what a modern React developer would write. The lack of review means the structure has accreted rather than been designed, which is what the pasta style phrase is describing. And the author does not want to attract contributors, which is the opposite of the usual README invitation.

The repository structure is consistent with that account. There is an `app.js` at the root, a `models/` directory, `routes/`, `views/` for the Pug templates, a `src/` directory for the client, `public/`, `utils/`, an `iso/` directory, `data/`, `scripts/`, `bin/`, `logs/` and a `__test__/` directory. The toolchain is a mix of eras as well, with a `biome.json` and an `.oxlintrc.json` for linting, a `vite.config.mjs` for the client build, a `nodemon.json` for the server, husky hooks, a `render.yaml` deployment descriptor and a `version.js`.

For an evaluator, the practical reading is that this is a working product with a hard maintenance ceiling, not a codebase to build on.

Running it locally needs three services and a pinned Node

The installation section lists four prerequisites, and the wording of one of them is a small sign of how the project has been maintained.

The first is NodeJS v24.12.0, with a pointer to the `.nvmrc` file, and the README calls NVM the industry standard way to install Node. The second is MongoDB, which has to be in the path. The third is Redis, also in the path. The fourth is pnpm, for the operating system in question.

The install itself is three commands.

git clone https://github.com/cozuya/secret-hitler.git
cd secret-hitler
pnpm install

The manifest pins the toolchain rather than leaving it open. The package requires Node 24.12.0 or newer, and declares pnpm 10.26.1 as the package manager, and the package version is 1.9.3 with the licence field set to CC-BY-NC-SA-4.0.

Two dependencies are worth pointing out because they explain the data model. `mongoose` at 5.7.5 with `mongodb` at 3.1.10 is a generation-old pairing, and `immutable` is a dependency, which means application state is held in persistent data structures rather than plain objects, with Redux on top. `gfycat-style-urls` is installed straight from a git URL, which is the kind of dependency that makes a project harder to build reproducibly years later.

So the local setup is three services on your machine and a pinned runtime, and the running application is a Node server, a MongoDB instance, a Redis instance and a socket layer between the two.

Multiple sessions, no live reload, and a password you should change

The development mode section is the most practically useful text in the README, and it is full of the kind of detail that only exists because somebody hit the problem.

You start the redis server and then run the dev script.

pnpm dev

Then you open the local address.

http://localhost:8080

The rest of that paragraph is the part worth keeping. You need multiple sessions, so you use Chrome user profiles or Firefox multi-account containers, and the README says plainly that incognito will not work. You should tick disable cache on the network tab, because the Vite build runs in watch mode and does not cache bust itself and there is no live reload, so every save needs a manual refresh.

Then there is the helper accounts. It is helpful to create all of the quickdefault accounts with the default password so that you can log in to an account in one click, and there is a pnpm script that populates them into the database.

pnpm create-accounts

The default password for those accounts is `snipsnap`, and it is a development convenience written into the README. It is exactly the kind of value that must not survive into anything reachable, and the README does not say so explicitly, so it is worth saying here: if you expose this instance to a network, that password is the first thing to change.

Assigning yourself the admin role for testing

Testing the site properly means being able to reach the administrative functions, and the README describes a script for that.

It is done through the `secret-hitler/scripts/assignLocalMod.js` file, contributed by a user called Hexicube, and it runs after the account creation script so that the helper accounts already exist in the database.

pnpm assign-local-mod

The script assigns the account named `Uther` to the `admin` staffRole, and the README says that when you see the end result of `Assigned.` in the terminal, you know it worked, and that you should then refresh the local page to have a local mod available for testing additional functions of the site in a development environment.

The flow is therefore a three-step bootstrap for a developer: install, seed the accounts, promote one of them. That is a reasonable pattern for a game with roles, because testing the game properly means seeing the moderator's view of the table, and the fastest way to get there is a script rather than a database edit.

What the README does not document is how the mod assignment is protected outside a development environment, and given the helper account password is a published constant, that is the second thing to check before running this anywhere but your own machine.

The rule changes the web version makes

The section on alterations to the original game is where the project's own judgement about the rules shows through, and it is worth reading whether or not you intend to run the code.

The image assets have minor alterations and editing applied, and the assets are available in the repository. The veto power is slightly adjusted, so that chancellors have to select a policy before saying yes or no to vetoing it. The rules explanation is adapted to account for online play as against physical play.

Then there is the rebalancing option, and it is the most substantial change. A game creator can rebalance the 6, 7 and 9 player games, so that the 6 player game starts with a fascist policy already enacted, the 7 player game starts with one less fascist policy in the deck, and the 9 player game starts with two less. The stated reason is that players, and the results of analysing statistics, have found those modes are not well balanced in the original ruleset.

On top of that there is a custom game mode where the creator of a game chooses the ruleset itself, with the ability to pick which policy powers are in play, how many fascists there are, always fewer than the liberals, and how many policies are dealt.

The interesting design point for an implementer is that the ruleset is a parameter of the game rather than a constant. The same lobby code serves the standard game, a rebalanced variant and a custom variant, which is a neat trick for a codebase that has to work for six to nine players with different roles and different winning conditions.

A non-commercial licence, and a request not to run production

The last section of the README makes two statements that any adopter has to deal with.

The first is the production instruction. The production mode section says: don't, please respect the maintainers and contributors who have given their time for free to make the site as good as it is, and that running this codebase outside of the official site may have unintended consequences.

The second is the licence. The game is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International licence, the manifest records the same terms as `CC-BY-NC-SA-4.0`, and the repository's own licence file is a custom one that GitHub cannot classify. The design credit goes to Max Temkin, Mike Boxleiter and Tommy Maranges, with illustrations by Mackenzie Schubert, and the README notes the minor image alterations.

The non-commercial term has a direct consequence for anyone considering a hosted instance for a group, a school or a company. The game design's own licence forbids commercial use, and the project asks for production deployments to be left to the official site.

On maintenance, the repository is not archived and the last push was on 2026-10-21, so the code is still being touched. There are no GitHub releases, so the version history is the `1.9.3` in the manifest and the commit log, and the maintainer credits the community Discord and the larger pull requests over the years, noting close to two million games played. That is a functioning community around a codebase that its own author describes as unlikely to be a good foundation for new work, and those two facts sit together without contradiction.

Editorial conclusion

secret-hitler fits someone who wants to run the game on their own machine, or who wants to read how a lobby-style multiplayer game was put together with SocketIO sessions and MongoDB models. Skip it if you intend to run a public instance, because the README asks you not to and says there may be unintended consequences, and skip it if you plan to contribute code, because the maintainer says they cannot recommend working on the codebase. Verify first that you can run MongoDB and Redis locally, that the Node version matches the one the repository pins, and that the default helper account password is changed before the port is reachable by anyone else.

Frequently asked questions

Official sources

1. cozuya/secret-hitler on GitHub
2. Issues
3. Project website
4. README