HarmonyX: a Harmony fork rebuilt on MonoMod.RuntimeDetour for Unity modding

What it is: Harmony's API, MonoMod's engine

HarmonyX describes itself as a library for patching, replacing and decorating .NET and Mono methods during runtime, now powered by MonoMod.RuntimeDetour.

Those three verbs are the whole capability set, and the distinction between them matters in practice. Patching means redirecting a call to your own code while keeping the original reachable. Replacing means the original is no longer called at all. Decorating means your code runs before and after the original, with the ability to skip it. A modding framework needs all three, because the same method might need an extra check before it runs, a different implementation entirely, or a wrapper that intercepts a result.

The lineage is stated directly in the About section. HarmonyX is a fork of Harmony 2 that specialises on support for games and game modding frameworks, and it is being developed primarily for use in game frameworks alongside MonoMod. The main target usage of HarmonyX is BepInEx and Unity.

So the architecture is a split. The public surface and the semantics come from Harmony 2, which is why existing Harmony knowledge transfers, and the engine underneath is MonoMod.RuntimeDetour, which is a much smaller, lower-level library focused on detouring a method at runtime. The README calls it powered by MonoMod and its runtime patching tools, and the list of important aspects names full interop with MonoMod.RuntimeDetour as a property: patches made with either can coexist.

That last point is the strategic reason for the fork existing rather than a new library. Unity modding has two competing patching stacks, the Harmony family and the MonoMod family, and a mod that uses one and a framework that uses the other has a problem. HarmonyX resolves it by making the two coexist rather than by asking every mod author to pick one.

The project is MIT licensed, the primary language is C#, the default branch is master, the last push was on 2026-07-08, and the recent releases are v2.16.1 on 2026-03-30, v2.16.0 on 2025-11-26 and v2.15.0 on 2025-09-03.

The six aspects that define the fork

The README lists the important aspects of HarmonyX, and the list is a good summary of what a fork changes relative to its upstream.

* Unity support first: builds for .NET Framework 3.5 and .NET Standard 2.0
* Patching feature parity with Harmony while reducing code duplication using MonoMod.RuntimeDetour
* Fast release schedule: get periodic stable releases off [NuGet](https://www.nuget.org/packages/HarmonyX/) or [GitHub](https://github.com/BepInEx/HarmonyX/releases), or download the latest CI build with [nightly.link](https://nightly.link/BepInEx/HarmonyX/workflows/build/master/HarmonyX)
* Full interop with [MonoMod.RuntimeDetour](https://github.com/MonoMod/MonoMod/blob/master/README-RuntimeDetour.md): patches made with either can coexist
* Easily extendable patching: [built-in support for native method patching](https://github.com/BepInEx/HarmonyX/wiki/Valid-patch-targets#native-methods-marked-extern) and possibility to extend to other patch targets (e.g. IL2CPP)
* Fixes, changes and optimizations aimed at Unity modding

Unity support comes first in the list, and that ordering is deliberate. It builds for .NET Framework 3.5 and .NET Standard 2.0, which is a much older target set than a modern .NET library would use. The reason is the runtime it has to load into: Unity games ship with an old Mono implementation, and a patching library that requires a recent runtime simply cannot be loaded into the process it is meant to patch. Building for 3.5 is not a lack of ambition, it is the constraint that makes the library usable at all in the target environment.

Feature parity with Harmony is the second point, and the qualifier is reducing code duplication using MonoMod.RuntimeDetour. The duplication referred to is between the two patching implementations, so keeping the shared machinery in one lower-level library is how HarmonyX can match Harmony's feature set without maintaining two copies of the same code.

The third point is about cadence rather than capability. Stable releases go out periodically to NuGet and to GitHub releases, and there is also a nightly CI build available through nightly.link for anyone who wants the newest commit rather than the newest tag.

The fifth point is the one that suggests where the project is heading. Built-in support for native method patching is there, and the list says there is possibility to extend to other patch targets, with IL2CPP given as the example. Unity's IL2CPP backend compiles the game's C# to native code, which means there are no managed methods left to patch, and a patching library for that case has to operate at a completely different level. The word possibility in the README is doing honest work there, since the extension point exists but the IL2CPP target is not claimed as shipped.

Interoperability with MonoMod, and what coexist actually means

The interoperability claim deserves unpacking, because in practice it is the difference between a mod ecosystem that works and one that does not.

A Unity game under BepInEx may load a framework that patches with MonoMod.RuntimeDetour, while individual mods patch with Harmony. If both libraries tried to detour the same method independently, the result would be unpredictable: two trampolines, or one that silently wins, or a crash. The README says patches made with either can coexist, which means HarmonyX has been built so that the two libraries share the same underlying mechanism rather than each installing its own.

The engineering consequence of that sharing is that HarmonyX is not really a separate library so much as a Harmony-shaped front end over MonoMod's detours. Which is also why the reduce-code-duplication point appears alongside feature parity: the work of implementing prefixes, transpilers, priority ordering and the rest of Harmony's patching model is not repeated here, it is expressed on top of a shared base.

For a mod author this has a practical consequence worth planning around. If you write a HarmonyX patch and a MonoMod patch in the same process, the ordering and interaction between them is governed by the shared base rather than by either library's own rules. The README does not spell out the ordering semantics in the visible text, so the HarmonyX wiki is the place to confirm them before you rely on a specific interaction.

The extendability point sits in the same area. Built-in support for native method patching means the library is not limited to managed methods, and the wiki has a page on valid patch targets with a section on native methods marked extern. Extending to other target kinds, with IL2CPP named, is the same idea taken one step further: rather than hard-coding a set of target kinds, the design allows more to be added.

For a Unity modder, the practical advice is short. If your framework is BepInEx, use HarmonyX. If you are writing patches from scratch and mixing them with an existing MonoMod-based framework, HarmonyX's interop is the reason it can work at all.

Where the code lives, and how it is built

The top level listing shows a repository that has kept the shape of its upstream while changing what is inside it.

There is a Harmony/ directory, which is where the library source lives and retains the upstream name, and a HarmonyTests/ directory for the test suite. Alongside those there is a TestLibrary/, which is the separate assembly the tests patch, since a runtime patching library needs something real to patch and cannot test against itself.

The solution file is still Harmony.sln rather than HarmonyX.sln, another piece of the upstream shape surviving the fork. And there are two licence files, LICENSE and LICENSE.Harmony, which is the expected arrangement for a fork that is rewriting the code of a differently licensed upstream: the fork carries its own licence while retaining the original one for the inherited portions.

The build tooling is the Cake-based setup, with build.cake as the script and build.sh, build.bat and build.ps1 as the entry points for Unix, Windows batch and PowerShell. That trio of launchers is the standard shape for a repository that expects to be built on any of the three platforms, which for a library targeting .NET Framework 3.5 and Unity is a real requirement rather than a courtesy.

The rest of the configuration is standard modern .NET practice. There is a Directory.Build.props for properties shared across the projects, a global.json pinning the SDK version, a nuget.config, an .editorconfig, a .gitattributes, and a .config/ directory, which by convention in .NET repositories holds the dotnet tools manifest. The .gitattributes and .editorconfig together are what keep line endings and formatting consistent across contributors on different operating systems.

The GitHub directory holds the workflows, and the nightly.link URL in the README points at a workflow named build on the master branch, which confirms the CI produces downloadable nightly artefacts in the format nightly.link serves.

Getting a build, and the documentation that is a wiki

HarmonyX ships no API documentation in the repository itself. The README's documentation section is a single line: check the documentation out at the HarmonyX wiki.

That is worth noting because it is unusual for a library of this size to have no docs directory and no generated API reference in the tree. The wiki is where the API documentation, the usage guides and the patch target reference live, and the valid patch targets page in particular is the reference that matters when you are deciding whether a method can be patched at all.

For obtaining the library there are three documented routes, and they differ in what you are opting into.

The stable route is the NuGet package, with a download count badge in the README pointing at the package page, and there are matching GitHub releases for the same versions. For a project where reproducible builds matter, pinning the NuGet version is the straightforward choice.

The fast route is the nightly CI build via nightly.link, linked to the build workflow on the master branch. The README frames the release schedule as fast precisely to make this attractive: the point of a fork with a short release cadence is that a fix can land and reach modders quickly, and a CI artefact gets it to them before a tagged release does. The cost is that a nightly build can change without notice, so it belongs in development rather than in a shipped mod.

Then there is the licensing and build environment, which the README does not cover but the repository structure implies. Building for .NET Framework 3.5 and .NET Standard 2.0 on a current machine needs the right targeting packs, and the global.json pins the SDK so everyone builds against the same one. If you are running on Linux or macOS, building the .NET Framework 3.5 target is the part most likely to need attention, and the wiki is where the project would document it.

The pragmatic sequence for someone evaluating the library is therefore short: read the wiki's patch target page to understand what you can patch, take the NuGet package to start, and keep the nightly build link for when you are chasing a fix.

Who this is for, and the question a fork always raises

HarmonyX is a fork, and forks raise a question that is worth answering directly: why not just use the upstream.

The answer here is stated in the About section, which is unusually blunt about it. HarmonyX specialises on support for games and game modding frameworks, is developed primarily for use in game frameworks alongside MonoMod, and its main target usage is BepInEx and Unity.

That is a narrower mission than Harmony's. Upstream Harmony serves a broader audience beyond games, and it is well suited to that. HarmonyX optimises for a specific environment where three things dominate: the runtime is old, so the library must build for it; the ecosystem already contains MonoMod, so the two must interoperate; and the workload is a long-lived game process with many mods loading at unpredictable times, so failures and contention are the normal conditions rather than the exception.

The release cadence is part of that mission. A general-purpose library can release twice a year. A fork that serves a modding ecosystem has to ship when the ecosystem needs a fix, which is why the nightly CI build is a documented route rather than an accident of the build configuration.

The last line in the list, fixes, changes and optimizations aimed at Unity modding, is the one that is easiest to miss and probably the most valuable in practice. A library that is only a fork for licensing reasons gives you nothing extra. A fork that carries specific fixes for the target environment gives you a reason to prefer it over upstream even if the API is the same.

The MIT licence and the presence of a CONTRIBUTING.md say that the fork is open to outside work, and the hacktoberfest topic on the repository suggests it actively takes contributions, which is how a fork keeps its advantage over the upstream it diverged from.

Editorial conclusion

Adopt HarmonyX if you are writing runtime patches for Unity games or a BepInEx based mod, and you want Harmony's API surface backed by MonoMod.RuntimeDetour rather than the original implementation. Do not adopt it for ordinary .NET patching work where Harmony 2 already fits, since HarmonyX exists to serve a narrower target. Before you mix the two in one process, read the interoperability note, because patches made with either library can coexist but they are not the same objects, and decide whether you want the stable NuGet release or a nightly CI build from nightly.link.

Frequently asked questions

Official sources

1. BepInEx/HarmonyX on GitHub
2. Issues
3. License: MIT
4. README
5. Releases