Windhawk Mods: a catalogue where every mod is one C++ file with metadata in the header

A catalogue that is a directory of files

This repository is the official collection of Windhawk mods. The mods can be viewed on the online mods catalog at windhawk.net/mods, and can be viewed and installed with Windhawk itself.

The interesting thing about how the collection is stored is that it is not a monorepo of packages, a directory of build outputs, or a registry of manifests. The contribution rules say it plainly. To submit a new mod you create a pull request that must consist of a single file, `mods/<mod-id>.wh.cpp`, where `<mod-id>` is the mod id as specified in the mod file.

So a mod is one C++ source file, named after the mod's own identifier, and the identifier appears in the file as well as in the path. The catalogue, the installer, and the changelog are all derived from that one file.

That convention has consequences. A reviewer looking at a new mod looks at one file and can see everything about it, the metadata, the behaviour, and the licence. There is no build to run, no dependency graph to resolve, and no artefact to trust, because the artefact is the source. For a catalogue that has to accept contributions from strangers, that is a genuinely good shape, and it is a much easier review than a repository of packages would be.

The price is that a mod has to be expressible as one file. Anything with a build step, several translation units, or third-party dependencies is out of scope for this route, and the licence note at the end of the submission section says as much about third-party code.

The top level of the repository holds the `mods/` directory, a `changelog_override/` directory, `public/`, `scripts/`, and the deployment tooling, `deploy.ts` and `modSourceUtils.ts`, with a `package.json`, a `tsconfig.json`, and a `package-lock.json` for the TypeScript side.

The metadata is the contract, and it is checked against you

The mod file is not just code, and the submission rules make the metadata part of the review rather than an afterthought.

The mod's `github` metadata value must be specified, and must match the pull request author's GitHub profile. If the mod's `twitter` metadata value is specified, the mod author must be the owner of the Twitter profile and must be able to verify it.

So the metadata is an identity claim, and the repository checks it. The reason is not bureaucratic. A catalogue of mods shown to end users, each with a name and an author, is a place where impersonation is the obvious failure mode, and the check is against the pull request author rather than against a text field anyone can type. The GitHub profile is a real account, and it is the account making the pull request, so the binding is to an identity the platform has already verified.

The Twitter check is softer and is expressed as a capability rather than a fact. The author must be able to verify it, which is a different and lower bar, appropriate to a field that is optional.

The same identity rule applies to updates, and it produces a rule that is worth reading carefully. The mod's `github` metadata value must match the pull request author's GitHub profile, and the project spells out the consequence: this means that you can only submit an update for a mod that you originally submitted. If you would like to update a mod that you did not submit, you can either submit the changes to the mod author, or submit a new mod instead.

So the catalogue is not a commons. Ownership is per mod, enforced at review time, and the escape hatch for someone who wants to improve someone else's mod is to convince its author. That is a defensible position for a catalogue where the mod runs with privileges in other people's processes, and it does create a bus factor of one per mod.

The version metadata has its own rule for updates. The mod's `version` metadata value must be changed to a newer version, and the commit message should include information about the new version, because that information is shown in the mod's changelog.

The licence default is MIT, and it is the submitter's job to be more specific

One line in the submission section carries most of the legal weight of the repository.

Mods which don't specify a license are submitted under the MIT license. It's the author's responsibility to specify the appropriate license for third-party code.

That is a default-licence scheme, and the way it works is worth being precise about. If you write a mod and say nothing about the licence, the catalogue treats it as MIT. That is the permissive end of the spectrum, and it is a sensible default for a community catalogue where most contributions are small original works.

The second sentence is the sharp one. The author is responsible for specifying the appropriate licence for third-party code. So the default only applies to what the author wrote. If a mod includes code that came from somewhere else, the author has to say so and choose the right terms for that part, and the responsibility does not transfer to the catalogue or the project. A mod that embeds a GPL library and does not declare it has declared MIT by omission, and the omission is the author's error rather than the catalogue's.

The repository's own licence is recorded as unknown in the metadata, with the terms in a LICENSE file at the root, and the licence for the tooling is separate from the licence of the mods. A catalogue of third-party contributions cannot impose one licence on the contributions, which is why the per-mod licence field exists at all.

For anyone using a mod, the practical advice is to read the licence metadata of the specific mod rather than assume MIT, and to be especially careful with any mod that declares something else, because the catalogue's default tells you nothing about it.

The TypeScript tooling is what turns a directory into a site

The repository is not only C++ files, and the small TypeScript layer around them is what produces the catalogue.

The package.json declares the module as an ES module, and the dependencies are three, all of them build-side. `showdown` is a Markdown to HTML converter, `feed` is a feed generator, and `tsx` is the TypeScript execution tool that lets the scripts run without a separate compile step. The dev dependencies include the GitHub actions script toolkit and its webhook types, plus the Node and showdown type definitions.

Those three dependencies tell you what the deployment does. The mods are Markdown-bearing source files with metadata, `showdown` converts that prose into HTML for the catalogue pages, and `feed` produces an RSS feed so the catalogue can be subscribed to. The `tsx` dependency means the scripts are run directly from TypeScript in whatever environment the deploy runs in.

The two named source files at the root are the core of it. `deploy.ts` is the deployment script, and `modSourceUtils.ts` is the shared utility for reading and interpreting mod sources, which is where the metadata parsing lives, since the catalogue has to understand the mod id, version, author, licence, and description of every file in `mods/`.

The `changelog_override/` directory is the other piece of the puzzle, and it exists because a mod's own changelog comes from its commit history and version metadata, while some entries need to be written by hand. A catalogue that wants to say something like a known issue or a compatibility note needs a place to put it that is not the mod author's commit message.

The `scripts/` directory holds the rest of the pipeline, and `public/` is the static output, the images and the generated pages that the site serves.

The repository also carries a `.clang-format` file, which tells you that the C++ in the mods directory is formatted to a standard before it is merged, and a `.vscode/` directory for editor settings.

How a new mod gets made and what the wiki expects

The creation process is split across two documents, and the division is instructive.

The Creating a New Mod section of the project summary does not contain the instructions. It refers you to the corresponding wiki page in the Windhawk repository, at the Creating a New Mod page. The wiki is where the how-to lives, and the wiki belongs to the Windhawk project rather than to the mods collection. That makes sense given the split of responsibilities: the mods collection holds mod source, and the Windhawk project holds the engine, the format specification, and the tooling that compiles a mod into something loadable.

The submission process, by contrast, is documented in the project summary itself, because it is specific to this repository. The mod catalogue and the mod source live together, and the pull request is the delivery mechanism.

So the workflow for a new author is: learn the file format from the wiki, write one C++ file, add its metadata, and open a pull request against this repository. The review then checks the mechanical things, the file is exactly one file at the right path, the mod id in the path matches the mod id in the file, the `github` metadata matches the pull request author, and the licence is either stated or defaults to MIT.

The community channels are given early in the project summary. You are welcome to participate in GitHub Discussions or join the Discord channel for a live discussion. The Discord is the place for a live conversation, which is the right medium for the questions a mod author actually has, which tend to be about format details and engine behaviour rather than about the catalogue policy.

The repository has no GitHub releases attached, so the changelog the users see is the per-mod changelog derived from version metadata and commit messages, and the `changelog_override/` directory for hand-written entries. The last push to the repository was on 2026-10-15, and the primary language is C++.

Where this repository is the wrong place to look

The limits here are about what the collection is and is not, and they are worth stating before an hour goes into a pull request that gets closed.

First, this is not a code host for Windhawk itself. The engine, the loader, the format specification, the wiki, and the installer all live in the separate Windhawk repository, and the online catalogue at windhawk.net/mods is a separate site again. If you want to understand how a mod is compiled and injected, that is the Windhawk project. If you want to understand what mods exist, that is the catalogue. This repository is the source of the mod files and the pipeline that publishes them.

Second, the one-file rule is a hard constraint on what a mod can be. A mod that needs a build step, several source files, or vendored dependencies cannot be submitted here as a single pull request with one `.wh.cpp` file. The third-party code clause hints at the boundary, since borrowed code has to fit inside that one file and carry its own licence note, but the practical limit is the file itself.

Third, the ownership rule means the catalogue is not a commons. If you want to maintain a mod someone else wrote, you have to work through that author, and if the author has gone away the route is to submit a new mod instead. That is a deliberate choice for a catalogue whose mods run with elevated privileges in other people's Windows sessions, and it does mean the availability of a given mod depends on one person.

Fourth, the licence default is a convenience that can mislead. A mod without a stated licence is MIT, which is fine, and the mod's own metadata is the only reliable source. For a mod that includes third-party code, the author is responsible for the right terms, and the catalogue does not verify that beyond the review of the metadata field.

Fifth, the repository is a publishing pipeline as much as a source tree, and the tools around it are thin. The `deploy.ts` and `modSourceUtils.ts` files and the three dependencies are all there is, so if you are looking for a sophisticated build or a test harness for the mods, you are not going to find it here. The tests that matter for a mod are the ones the engine and the wiki describe, run on a machine with Windhawk installed.

Editorial conclusion

windhawk-mods fits a Windows developer who wants to ship a small, self-contained tweak through the Windhawk catalogue, and who is willing to work inside a one-file-per-mod convention and a metadata-driven review process. It is the wrong repository for anything that is not a Windhawk mod, and the wrong place to build a multi-file project. Check three things before opening a pull request: that your mod's `github` metadata matches your GitHub profile, that the file is named `mods/<mod-id>.wh.cpp` with the mod id matching the one inside the file, and that you have set an explicit licence if your mod includes third-party code, since a mod that does not specify one is submitted under MIT.

Frequently asked questions

Official sources

1. Issues
2. ramensoftware/windhawk-mods on GitHub
3. README