If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/pardeike/Harmony shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 7w ago
• 8 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Single-maintainer risk — top contributor 81% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live pardeike/Harmony repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/pardeike/Harmony.

What it runs against: a local clone of pardeike/Harmony — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in pardeike/Harmony | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 80 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of pardeike/Harmony. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/pardeike/Harmony.git
#   cd Harmony
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of pardeike/Harmony and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "pardeike/Harmony(\\.git)?\\b" \\
  && ok "origin remote is pardeike/Harmony" \\
  || miss "origin remote is not pardeike/Harmony (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "Harmony/AssemblyInfo.cs" \\
  && ok "Harmony/AssemblyInfo.cs" \\
  || miss "missing critical file: Harmony/AssemblyInfo.cs"
test -f "Harmony/Extras/FastAccess.cs" \\
  && ok "Harmony/Extras/FastAccess.cs" \\
  || miss "missing critical file: Harmony/Extras/FastAccess.cs"
test -f "Harmony/Extras/MethodInvoker.cs" \\
  && ok "Harmony/Extras/MethodInvoker.cs" \\
  || miss "missing critical file: Harmony/Extras/MethodInvoker.cs"
test -f "Harmony/Extras/DelegateTypeFactory.cs" \\
  && ok "Harmony/Extras/DelegateTypeFactory.cs" \\
  || miss "missing critical file: Harmony/Extras/DelegateTypeFactory.cs"
test -f "Directory.Build.props" \\
  && ok "Directory.Build.props" \\
  || miss "missing critical file: Directory.Build.props"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 80 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~50d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/pardeike/Harmony"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Harmony is a runtime method patching library for .NET and Mono that lets you intercept, replace, and decorate methods in loaded assemblies without modifying source code or disk files. It enables multiple patches to coexist on the same method by providing prefix/postfix/transpiler hooks, IL manipulation capabilities, and a unified patching API—used in production by games like Rust, Rimworld, and Stardew Valley. Single-package architecture: core Harmony library under src/ (inferred from .csproj structure); Documentation/ folder contains Docfx-based API docs and articles (basics.md, execution.md, annotations.md); .github/workflows/ defines multi-platform CI (test-windows-dotnet.yml, test-unix-mono.yml, test-qemu-*.yml); Directory.Build.props and Directory.Build.targets centralize build configuration across projects.

Mod developers and plugin authors who need to alter third-party .NET code at runtime; game modding communities; WPF/C# testing frameworks (used at Microsoft and Google); anyone building extensible C# applications where monkey-patching is the only option.

Harmony 2.x is production-ready and actively maintained (v2.4 current). It has established adoption across major game titles and enterprise use. The codebase shows comprehensive GitHub Actions CI/CD (.github/workflows/ contains test suites for Windows/Unix/Mono/QEMU across multiple runtimes), extensive documentation (Documentation/ folder), and structured release versioning. Single maintainer (pardeike) but stable API and no recent breaking changes.

Primary risk is single-maintainer bus factor (pardeike owns the repo). Dependencies on MonoMod.Core (external library) could introduce supply-chain risk. Runtime IL manipulation and reflection-based patching are inherently fragile across .NET versions and JIT implementations—patches can break silently on runtime updates. No visible open issue backlog data in file list, but runtime complexity means edge cases are likely.

Active maintenance on version 2.4; GitHub Actions workflows indicate continuous testing across Windows/.NET/Mono/Unix/QEMU architectures. Documentation is under version control (Documentation/api/index.md, Documentation/articles/). Copilot instructions exist (.github/copilot-instructions.md), suggesting recent tooling updates. Release model appears stable with no indication of major API changes in flight.

git clone https://github.com/pardeike/Harmony.git
cd Harmony
dotnet build
dotnet test

Or to use as a dependency: install NuGet package Lib.Harmony (merged assembly) or Lib.Harmony.Thin (requires dependency management).

Daily commands:

dotnet build Harmony.sln
dotnet test --no-build

For documentation generation: requires Docfx (inspect Documentation/Documentation.csproj). Workflows show: dotnet build followed by test-specific runners (see .github/actions/test-execute-test/action.yml).

• Harmony/AssemblyInfo.cs — Entry point and version declaration for the entire Harmony library—defines the public API surface and assembly identity.
• Harmony/Extras/FastAccess.cs — Core reflection and runtime IL emission utilities that enable high-performance method patching across .NET and Mono runtimes.
• Harmony/Extras/MethodInvoker.cs — Critical infrastructure for dynamically invoking patched methods with minimal overhead, essential to the patching engine.
• Harmony/Extras/DelegateTypeFactory.cs — Generates delegate types on-the-fly for patch callbacks, bridging reflection metadata and runtime IL generation.
• Directory.Build.props — Master build configuration defining compilation targets (.NET Framework, .NET Core, Mono) and shared project properties across the solution.
• .github/workflows/test-build.yml — CI/CD pipeline that validates builds across Windows, Unix, Mono, and QEMU environments—catches cross-platform regressions early.
• Documentation/articles/patching.md — Canonical reference for the patching API patterns and concepts that all contributors and users must understand.

• FastAccess (Reflection.Emit, MethodInfo, FieldInfo) — Provides optimized reflection (field/property access) and IL code generation utilities; handles platform differences between .NET and Mono.
  • Failure mode: Incorrect IL metadata or unsafe memory access → runtime crash or silent IL corruption; patch silently fails on unsupported runtime.
• MethodInvoker (DynamicMethod, Delegate, IL code generation) — Dynamically constructs delegate wrappers for patched methods to minimize stack overhead during patch callback invocation.
  • Failure mode: Incorrect delegate signature → MethodAccessException or InvalidCastException at patch invoke time;

Add a new Patch Type or Hook Strategy

1. Create the core IL emission logic in a new file under Harmony/Extras/, following the pattern of MethodInvoker.cs for runtime safety and performance. (Harmony/Extras/NewHookType.cs)
2. Expose the hook type in the public API by adding a new method or property to the main Harmony facade (likely in AssemblyInfo.cs or a new public class). (Harmony/AssemblyInfo.cs)
3. Add comprehensive documentation describing the new hook, its use cases, and code examples. (Documentation/articles/patching-newhook.md)
4. Create a runnable example in the Documentation/examples directory demonstrating the new hook in isolation. (Documentation/examples/patching-newhook.cs)
5. Add test cases covering both .NET Framework and .NET Core in the appropriate test project, following the pattern of existing test workflows. (.github/workflows/test-build.yml)

Add Support for a New Runtime or Platform

1. Define the target framework and conditional compilation symbols in Directory.Build.props. (Directory.Build.props)
2. Create a new GitHub Actions workflow file (e.g., test-platform-name.yml) following the pattern of test-windows-dotnet.yml or test-unix-dotnet.yml. (.github/workflows/test-newplatform.yml)
3. If platform-specific IL patterns are needed, add runtime detection and fallback logic to FastAccess.cs or MethodInvoker.cs. (Harmony/Extras/FastAccess.cs)
4. Reference the new workflow in .github/workflows/test.yml to integrate with the main CI pipeline. (.github/workflows/test.yml)
5. Document platform-specific quirks and limitations in Documentation/articles/. (Documentation/articles/patching-edgecases.md)

Enhance Documentation with a New Article or Tutorial

1. Create a new Markdown file in Documentation/articles/ with clear headings, code snippets, and diagrams (using SVG or external tools). (Documentation/articles/newtopic.md)
2. Register the article in the table of contents. (Documentation/articles/toc.md)
3. Create a paired runnable example in Documentation/examples/ to accompany the article. (Documentation/examples/newtopic.cs)
4. Verify the example compiles by adding it to the test suite or the example test-all.sh script. (Documentation/examples/test-all.sh)

• C# Reflection & Reflection.Emit — Enables runtime method inspection and IL code generation without source code access; essential for patching third-party assemblies.
• .NET Framework, .NET Core, Mono — Supports both legacy Windows applications and modern cross-platform .NET; wide game engine compatibility (Unity, custom engines).
• GitHub Actions — Multi-platform CI/CD (Windows, Linux, macOS) with native Mono and .NET toolchain support; enables early detection of runtime-specific regressions.
• DocFX for Documentation — Generates static API docs from XML comments and Markdown; integrates code examples without duplication; works offline.

• Runtime IL emission instead of post-compilation patching

  • Why: Allows patching already-loaded assemblies at runtime without requiring recompilation or pre-processing.
  • Consequence: More complex IL manipulation logic and potential platform-specific edge cases; higher CPU cost during patch application (~100ms per method), but negligible at call-time.

• Support for multiple runtimes (Framework, Core, Mono) in single codebase

  • Why: Maximizes compatibility with legacy applications (Rust, Rimworld) and modern projects.
  • Consequence: Requires platform detection, conditional compilation, and regression testing across three runtime variants; increased maintenance burden.

• Manual patch ordering via Priority attributes instead of automatic dependency resolution

  • Why: Simpler API and deterministic execution order without complex graph analysis.
  • Consequence: Developer must manually manage patch sequence; circular dependencies not detected; harder to reason about patch interactions.

• Real-time debugging or breakpoint support for patched code
• Automatic IL optimization or JIT profiling feedback
• Support for async/await or Task-based patch contexts
• Patching of native methods or unmanaged code
• Hot reload or zero-downtime patch application (requires full restart)

Runtime JIT sensitivity: patches are fragile across .NET runtime versions and CPU architectures (hence the QEMU test matrix). IL manipulation gotchas: transpilers operate on raw IL, not C# AST—typos or version-specific IL layouts cause silent failures. Mono vs .NET Core divergence: test suite covers both because behavior differs (see test-windows-mono.yml vs test-unix-dotnet.yml). Dependency merging: Lib.Harmony merges MonoMod.Core; Lib.Harmony.Thin does not—mismatched consumer deps cause runtime load failures. No global installation: patches are instance-based per Harmony instance; multiple incompatible patches on same method can cause hard crashes.

• IL Weaving & Code Injection — Harmony works by modifying Common Intermediate Language (IL) at runtime; understanding IL stack, opcodes, and method signatures is essential to debug transpiler patches
• Method Detours & Trampolines — Core mechanism: Harmony replaces method entry points with jumps to your code, then calls original via a trampoline; crucial to understand why patches affect call sites, not just the method itself
• Reflection & Runtime Type Discovery — Harmony uses System.Reflection to locate methods by name/signature in loaded assemblies; patches are applied at runtime before or after JIT compilation
• JIT Compilation & Runtime Patching — Patches must be applied before the JIT compiler executes the method, or the compiled native code becomes stale; timing and platform differences (ARM/x86/x64) explain why multi-architecture testing exists
• Prefix/Postfix/Transpiler Hook Pattern — Harmony's three-tier hook model (execute before / after / replace IL) allows non-conflicting patches; understanding precedence and return values is critical for patch ordering
• Mono vs .NET Runtime Divergence — Harmony supports both .NET Framework/Core and Mono; IL layout, JIT behavior, and reflection APIs differ subtly between runtimes, requiring platform-specific test coverage
• Assembly Load Context (ALC) — In .NET Core, assemblies load into isolated contexts; Harmony patches must target the correct ALC, or patches fail silently against dynamically loaded code

• MonoMod/MonoMod.Core — Direct dependency: provides low-level IL manipulation and detour generation that Harmony builds upon
• BepInEx/BepInEx — Popular mod loader for games using Harmony for runtime patching; represents a major end-user of this library
• Kraggs/Minibloq — Alternative method patching library for .NET; solves the same problem but with different API design
• 0xd4d/dnlib — IL reading/writing library used in ecosystem; shares similar concerns around runtime IL manipulation
• pardeike/Harmony.Extensions — Official companion repo (inferred from single-maintainer pattern) providing optional helper utilities on top of core Harmony

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for Harmony transpiler code matching system

The repo has extensive documentation on transpiler matchers (Documentation/articles/patching-transpiler-matcher.md) but the test coverage for the code matching logic appears incomplete. Given that transpilers are a complex feature used by major titles, adding focused unit tests for matcher edge cases, pattern combinations, and error conditions would significantly improve reliability and prevent regressions.

• [ ] Review existing tests in the test project for transpiler matcher coverage
• [ ] Create new test class targeting Documentation/articles/patching-transpiler-matcher.md scenarios
• [ ] Add tests for: complex instruction patterns, nested matchers, boundary conditions, and error handling
• [ ] Ensure tests validate both positive matches and intentional non-matches
• [ ] Reference the test results in updated documentation if gaps are found

Create GitHub Action workflow for QEMU-based ARM/ARM64 testing on Linux

The repo has test workflows for test-qemu-dotnet.yml and test-qemu-mono.yml but they appear to be templated/incomplete based on the file structure. Given that Harmony supports Mono and .NET cross-platform, adding a complete, working QEMU-based CI workflow for ARM64 architecture would ensure runtime compatibility on embedded systems and mobile platforms where games run.

• [ ] Review .github/workflows/test-qemu-dotnet.yml and test-qemu-mono.yml for completeness
• [ ] Implement QEMU setup steps using GitHub Actions (qemu-user-static container or setup-qemu-action)
• [ ] Configure multi-architecture dotnet/mono test execution (linux-arm64 specifically)
• [ ] Add artifact upload step using existing .github/actions/test-upload-result
• [ ] Validate against .github/actions/test-setup-dotnet and test-execute-test patterns

Document and add tests for Harmony patching in WPF/UI framework contexts

The README mentions Harmony is used at Microsoft and Google for unit testing WPF controls, but there is no dedicated documentation article or test suite for UI framework patching scenarios (binding, event handling, dependency injection in XAML). Adding Documentation/articles/patching-ui-frameworks.md with corresponding test cases would provide valuable guidance for enterprise users.

• [ ] Create new documentation file: Documentation/articles/patching-ui-frameworks.md
• [ ] Include examples for: WPF DependencyProperty patching, event handler interception, binding patching
• [ ] Add test cases for UI-specific challenges (thread safety, event routing, property change notifications)
• [ ] Update Documentation/articles/toc.md to reference the new article
• [ ] Reference real-world examples from the WPF/Google use cases mentioned in README

• Add inline XML documentation comments to public API surface in src/Harmony/ (check which files lack /// summary tags); improves IDE IntelliSense and documentation generation.
• Create a specific test case in the test suite for Mono IL differences (Harmony supports both .NET and Mono but test-windows-mono.yml may have gaps); run dotnet test targeting Mono to find untested edge cases.
• Expand Documentation/articles/execution.md with a real working example showing prefix/postfix/transpiler hooks on a single method (current docs are high-level; a concrete before/after code sample is missing).

The Harmony library is a well-established, legitimate project used in production by major gaming titles and organizations. The primary security consideration is the nature of the library itself - runtime method patching - which could potentially be misused. The codebase appears well-maintained with comprehensive testing workflows. Main recommendations: (1) Ensure all dependencies are documented and scanned for vulnerabilities, (2) Implement security scanning in the CI/CD pipeline, (3) Create a clear security policy and responsible disclosure process, and (4) Provide comprehensive security documentation for users on safe implementation practices. No obvious hardcoded secrets, injection vulnerabilities, or infrastructure misconfigurations were detected in the visible file structure.

• Medium · Runtime Method Patching - Potential for Malicious Code Injection — Core library functionality - Harmony library design. Harmony is a library designed to patch, replace, and decorate .NET/Mono methods at runtime. While this is a legitimate use case, the library's functionality could potentially be misused by malicious actors to inject code into running applications or modify behavior of trusted libraries without detection. The dynamic nature of runtime patching bypasses standard code verification mechanisms. Fix: 1. Document security implications clearly in README and documentation. 2. Implement code signing for the library distribution. 3. Encourage users to validate patch sources and implement integrity checks. 4. Consider adding logging and monitoring capabilities for patch application. 5. Provide security best practices documentation for safe usage.
• Low · Missing Dependency Management Documentation — Project root - dependency declaration files. The 'Dependencies/Package file content' section is empty, making it impossible to verify if the project has vulnerable dependencies. There is no visible package.json, packages.config, or .csproj file content showing dependency versions. Fix: 1. Provide complete dependency manifest files (all .csproj files, packages.config, etc.) for analysis. 2. Use automated dependency scanning tools (OWASP Dependency-Check, Snyk) in CI/CD pipeline. 3. Regularly update dependencies and monitor for CVEs. 4. Document minimum required versions for dependencies.
• Low · No Evidence of Security Testing — .github/workflows/ - test configuration files. While the repository contains comprehensive test workflows, there is no visible evidence of security-focused testing, fuzzing, or penetration testing in the CI/CD pipeline configuration. Fix: 1. Add security scanning tools (e.g., SonarQube, Snyk, CodeQL) to the CI/CD pipeline. 2. Implement static analysis security testing (SAST). 3. Consider dynamic analysis and fuzzing for runtime patching scenarios. 4. Add dependency vulnerability scanning in workflows.
• Low · Lack of Security Policy Documentation — Project root. No visible SECURITY.md or security policy file is present in the repository, making it unclear how security vulnerabilities should be reported or how the project handles security issues. Fix: 1. Create a SECURITY.md file with responsible disclosure guidelines. 2. Define the process for reporting security vulnerabilities. 3. Include expected response times for security issues. 4. Consider setting up a security.txt file or bug bounty program.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.