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/ramensoftware/windhawk 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.

WAIT — Slowing — last commit 5mo ago

• Last commit 5mo ago
• 2 active contributors
• GPL-3.0 licensed
• ⚠ Slowing — last commit 5mo ago
• ⚠ Small team — 2 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 95% of recent commits
• ⚠ GPL-3.0 is copyleft — check downstream compatibility
• ⚠ No CI workflows detected
• ⚠ No test directory detected

_{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 ramensoftware/windhawk repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/ramensoftware/windhawk.

What it runs against: a local clone of ramensoftware/windhawk — 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 ramensoftware/windhawk | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 182 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of ramensoftware/windhawk. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/ramensoftware/windhawk.git
#   cd windhawk
#
# 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 ramensoftware/windhawk and re-run."
  exit 2
fi

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

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

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

# 4. Critical files exist
test -f "src/vscode-windhawk-ui/apps/vscode-windhawk-ui/src/app/app.tsx" \\
  && ok "src/vscode-windhawk-ui/apps/vscode-windhawk-ui/src/app/app.tsx" \\
  || miss "missing critical file: src/vscode-windhawk-ui/apps/vscode-windhawk-ui/src/app/app.tsx"
test -f "src/vscode-windhawk-ui/apps/vscode-windhawk-ui/src/app/webviewIPC.ts" \\
  && ok "src/vscode-windhawk-ui/apps/vscode-windhawk-ui/src/app/webviewIPC.ts" \\
  || miss "missing critical file: src/vscode-windhawk-ui/apps/vscode-windhawk-ui/src/app/webviewIPC.ts"
test -f "src/vscode-windhawk-ui/apps/vscode-windhawk-ui/src/app/webviewIPCMessages.ts" \\
  && ok "src/vscode-windhawk-ui/apps/vscode-windhawk-ui/src/app/webviewIPCMessages.ts" \\
  || miss "missing critical file: src/vscode-windhawk-ui/apps/vscode-windhawk-ui/src/app/webviewIPCMessages.ts"
test -f "src/vscode-windhawk-ui/apps/vscode-windhawk-ui/src/app/panel/Panel.tsx" \\
  && ok "src/vscode-windhawk-ui/apps/vscode-windhawk-ui/src/app/panel/Panel.tsx" \\
  || miss "missing critical file: src/vscode-windhawk-ui/apps/vscode-windhawk-ui/src/app/panel/Panel.tsx"
test -f "src/vscode-windhawk-ui/apps/vscode-windhawk-ui/src/app/i18n.ts" \\
  && ok "src/vscode-windhawk-ui/apps/vscode-windhawk-ui/src/app/i18n.ts" \\
  || miss "missing critical file: src/vscode-windhawk-ui/apps/vscode-windhawk-ui/src/app/i18n.ts"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 182 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~152d)"
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/ramensoftware/windhawk"
  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).

Windhawk is a Windows program customization marketplace and engine that uses global DLL injection and runtime hooking to modify behavior of Windows applications without source code access. It provides a VSCode extension UI for discovering, installing, and editing mods that patch Windows executables at runtime, combined with a C++ backend engine (windhawk.dll) that performs the actual hooking and injection across 32-bit and 64-bit processes. Monorepo structure with three main components: src/windhawk/ (C++ engine: main executable, 32/64-bit DLL libraries), src/vscode-windhawk/ (VSCode extension backend), and src/vscode-windhawk-ui/ (Nx-based React/TypeScript monorepo for the webview UI). The UI layer (vscode-windhawk-ui) uses Ant Design, Monaco Editor, and React Router; state management via SWR and Immer; styling with Less and styled-components.

Windows power users and developers who want to customize closed-source Windows applications (like Explorer, Notepad, etc.) without recompiling them, and mod developers who write JavaScript/C++-like mods targeting specific Windows programs. Contributors are typically C++ systems programmers and TypeScript/React UI developers interested in low-level Windows internals.

Actively maintained with substantial codebase (578k C++, 564k TypeScript lines) and an established marketplace at windhawk.net. The presence of CI workflows, VSCode extension distribution, and a dedicated Discord community indicates production readiness. Commit recency and the structured monorepo layout suggest ongoing development, though the exact GitHub metrics (stars, release frequency) are not visible in provided data.

High complexity due to global process injection and hooking—bugs can crash the entire Windows session. Risk factors include 32-bit/64-bit compatibility maintenance, tight coupling between C++ engine and TypeScript UI, and dependency on undocumented Windows internals that may break across Windows versions. Single team maintainership (ramensoftware) concentrates risk, though the public repo and Discord suggest community oversight.

Active development of the vscode-windhawk-ui with version 1.7.3 in package.json; the Nx monorepo structure indicates recent refactoring toward scalable multi-package builds. E2E testing via Cypress is set up, suggesting quality-focused iteration. The build-ext script coupling UI output to ../vscode-windhawk/webview indicates ongoing VSCode extension integration work.

Clone: git clone https://github.com/ramensoftware/windhawk.git. For the UI development: cd src/vscode-windhawk-ui && npm install && npm start (runs Nx dev server on the vscode-windhawk-ui app). For the full extension: npm run build-ext syncs the built UI into the VSCode extension directory. For CSS changes: npm run watch-css watches Less files and recompiles to app.css.

Daily commands: UI development: npm start from src/vscode-windhawk-ui/ launches Nx dev server (typically http://localhost:4200). Full build: npm run build compiles to dist/apps/vscode-windhawk-ui/. CSS live reload: npm run watch-css runs less-watch-compiler with --enable-js flag. Extension packaging: npm run build-ext outputs built UI to ../vscode-windhawk/webview for VSCode extension consumption.

• src/vscode-windhawk-ui/apps/vscode-windhawk-ui/src/app/app.tsx — Main React application entry point that orchestrates the entire VS Code extension UI and connects to the webview IPC layer.
• src/vscode-windhawk-ui/apps/vscode-windhawk-ui/src/app/webviewIPC.ts — Core IPC bridge between the webview UI and the VS Code extension backend; critical for all mod management operations.
• src/vscode-windhawk-ui/apps/vscode-windhawk-ui/src/app/webviewIPCMessages.ts — Defines all message contracts between extension and webview; any protocol change requires careful coordination.
• src/vscode-windhawk-ui/apps/vscode-windhawk-ui/src/app/panel/Panel.tsx — Root panel component that manages the primary UI layout and routes between mods browser, mod details, and settings.
• src/vscode-windhawk-ui/apps/vscode-windhawk-ui/src/app/i18n.ts — Internationalization configuration and setup; all user-facing strings flow through this abstraction.
• src/vscode-windhawk-ui/apps/vscode-windhawk-ui/src/app/sidebar/Sidebar.tsx — Secondary navigation sidebar for local mods and editor mode controls; major UI container.
• src/vscode-windhawk-ui/apps/vscode-windhawk-ui/src/app/vsCodeApi.ts — Thin wrapper around VS Code webview API; provides access to configuration, theme, and messaging capabilities.

Add a new mod detail panel section

1. Create new React component extending ModDetails layout (e.g., ModDetailsCustom.tsx) (src/vscode-windhawk-ui/apps/vscode-windhawk-ui/src/app/panel/ModDetails.tsx)
2. Import and add the component as a new tab/section in ModDetails render logic (src/vscode-windhawk-ui/apps/vscode-windhawk-ui/src/app/panel/ModDetails.tsx)
3. If section needs mod data, use existing IPC patterns from webviewIPCMessages to fetch from extension (src/vscode-windhawk-ui/apps/vscode-windhawk-ui/src/app/webviewIPCMessages.ts)
4. Add i18n keys to English locale file for all user-facing text (src/vscode-windhawk-ui/apps/vscode-windhawk-ui/src/locales/en/translation.json)

Add a new IPC message type for extension communication

1. Define message type interface (request/response) following existing patterns (src/vscode-windhawk-ui/apps/vscode-windhawk-ui/src/app/webviewIPCMessages.ts)
2. Add handler in webviewIPC.ts switch statement to route the message (src/vscode-windhawk-ui/apps/vscode-windhawk-ui/src/app/webviewIPC.ts)
3. Call ipc.invoke() from UI components using the message type (src/vscode-windhawk-ui/apps/vscode-windhawk-ui/src/app/panel/Panel.tsx)
4. Implement matching extension-side handler in the VS Code extension backend (

Monorepo build coupling: The build-ext script uses robocopy (Windows-only) to sync dist output to ../vscode-windhawk/webview—build will fail or behave unexpectedly on non-Windows systems. CSS build required: app.less must be compiled to app.css before testing; just editing .less won't work unless watch-css is running. Nx caching: Nx caches build outputs; use nx reset if builds seem stale. VSCode extension path: The vscode-windhawk backend expects UI output in a specific ../vscode-windhawk/webview location; changing build output paths breaks the extension. 32/64-bit DLL handling: The C++ engine uses separate DLL builds for architectures; mismatch between process bitness and DLL bitness will fail silently.

• Global DLL Injection — The fundamental technique Windhawk uses to load its hook engine into arbitrary Windows processes; understanding injection is critical for modifying the C++ engine or debugging hooking failures
• Runtime API Hooking / Detours — Windhawk patches Windows API calls at runtime to intercept and modify program behavior; essential knowledge for writing or debugging mods and understanding engine limitations
• 32-bit vs 64-bit Process Architecture Compatibility — Windhawk maintains separate DLL builds for x86 and x64; mods must account for bitness differences, and the engine bridges this gap transparently—failures here cause silent crashes
• VSCode WebView IPC (PostMessage) — The vscode-windhawk extension communicates with the React UI webview via postMessage; understanding this message-passing pattern is essential for modifying UI-to-extension interactions
• Nx Monorepo Workspace Management — The vscode-windhawk-ui uses Nx for multi-app builds, caching, and dependency graph management; incorrect Nx usage causes silent build failures or stale outputs
• Less CSS Preprocessing with JavaScript — The build pipeline uses less-watch-compiler --enable-js to compile app.less to app.css; the --enable-js flag allows JavaScript expressions in Less, a non-standard feature requiring careful syntax
• React 18 Concurrent Rendering and Suspense — The UI is built on React 18 with async features (SWR for data fetching, react-markdown lazy loading); understanding concurrent boundaries prevents UI freezes when loading large mod lists or diffs

• m417z/global-inject-demo — Official companion demo repo showing the exact global DLL injection and hooking technique Windhawk uses; serves as a learning reference for the engine's core mechanism
• ramensoftware/windhawk-mods — Official mod repository for Windhawk; where the community publishes mods targeting specific Windows applications, complementing the engine
• microsoft/vscode-extension-samples — Reference implementations for VSCode extension patterns; helpful for understanding the vscode-windhawk backend's webview communication and extension API usage
• nrwl/nx — The Nx monorepo framework powering vscode-windhawk-ui's build and workspace structure; understanding Nx is essential for modifying the UI build pipeline
• ant-design/ant-design — Ant Design v4 component library used throughout the UI; primary source for understanding available components and styling customization in vscode-windhawk-ui

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 ModDetailsSettings.tsx component

The ModDetailsSettings.tsx file has a corresponding .spec.ts file but the test coverage appears incomplete based on the complexity of settings management in the UI. This component handles user interactions with mod configuration, which is critical to the Windhawk experience. Adding tests would ensure settings validation, serialization, and state management work correctly across updates.

• [ ] Review ModDetailsSettings.tsx to identify all setting input types (checkboxes, text inputs, selects, etc.)
• [ ] Expand ModDetailsSettings.spec.ts to cover: setting value changes, validation, error states, and persistence
• [ ] Add tests for edge cases like invalid YAML in settings, type mismatches, and boundary values
• [ ] Run 'npm run test' to validate new test coverage

Add E2E tests for mod installation and settings configuration workflow

The e2e test suite only contains a basic app.cy.ts test. Given that Windhawk's core functionality is installing and configuring mods, adding E2E tests for the critical path (browse mods → install → configure settings → enable/disable) would catch regressions and ensure the UI workflow remains stable across changes.

• [ ] Review existing app.cy.ts test structure and fixtures in src/vscode-windhawk-ui/apps/vscode-windhawk-ui-e2e/
• [ ] Create new spec file 'mod-installation-workflow.cy.ts' in src/vscode-windhawk-ui/apps/vscode-windhawk-ui-e2e/src/e2e/
• [ ] Add tests covering: loading mods list, clicking install, opening settings panel, modifying settings, and toggling mod state
• [ ] Add fixture data in src/vscode-windhawk-ui/apps/vscode-windhawk-ui-e2e/src/fixtures/ for mock mod objects
• [ ] Run Cypress tests to validate: 'npm run test'

Add GitHub Actions CI workflow for automated linting and test execution on PR

The .github/ISSUE_TEMPLATE directory exists but there's no CI workflow file (.github/workflows/). Automated linting (eslint) and test execution (jest, cypress) on every PR would catch issues early, maintain code quality standards (referenced by .eslintrc.json and jest.config.ts), and reduce manual review burden.

• [ ] Create .github/workflows/ci.yml file
• [ ] Add job steps: run 'npm install', 'npm run build', 'npm run test', and 'npm run build-ext' (Windows-only with conditional runner)
• [ ] Configure ESLint checks: add separate job to run eslint against src/ directory
• [ ] Set workflow triggers to run on: push to main, all pull requests, and manual dispatch
• [ ] Consider separate workflow for E2E tests (Cypress) with longer timeout and artifact capture for failed tests

• Add unit tests for InputWithContextMenu.tsx (src/vscode-windhawk-ui/apps/vscode-windhawk-ui/src/app/components/)—component exists but no .spec.ts file is visible, leaving context menu logic untested.: Low risk, high learning value for understanding React component testing in this Nx setup; touches real test infrastructure (jest.config.ts already present).
• Document the build-ext robocopy command in src/vscode-windhawk-ui/README or add a cross-platform build script wrapper that explains the webview output path expectation.: Improves onboarding for new contributors; clarifies the implicit contract between vscode-windhawk-ui build and vscode-windhawk extension expectations.
• Add Cypress e2e tests for the CreateNewModButton.tsx flow in apps/vscode-windhawk-ui-e2e/src/e2e/app.cy.ts—e2e scaffold exists but no button interaction tests are visible.: Strengthens test coverage for a core user flow (creating mods); uses existing Cypress config and demonstrates VSCode webview e2e testing patterns.

• High · Potential XSS via react-markdown and rehype-sanitize — src/vscode-windhawk-ui/apps/vscode-windhawk-ui/src/app/components/ReactMarkdownCustom.tsx. The codebase uses react-markdown with rehype-sanitize for rendering user-generated markdown content. While rehype-sanitize is intended to prevent XSS, the configuration in ReactMarkdownCustom.tsx should be audited to ensure proper sanitization rules are applied, especially given the mod documentation and changelog rendering. Fix: Review the rehype-sanitize configuration to ensure all potentially dangerous HTML tags and attributes are filtered. Implement strict whitelist-based sanitization rules. Consider adding CSP headers to the webview context.
• High · Potential Code Injection via js-yaml — src/vscode-windhawk-ui/apps/vscode-windhawk-ui/src/app. The codebase includes js-yaml as a dependency for parsing YAML content. YAML parsing can be vulnerable to arbitrary code execution if using unsafe loading methods. This is critical when parsing mod metadata files. Fix: Ensure that yaml.load() is never used without the safe: true option. Use yaml.safeLoad() or yaml.load(content, { safe: true }) exclusively. Audit all YAML parsing code paths.
• Medium · Outdated Dependencies with Known Vulnerabilities — package.json. Several dependencies are outdated or pinned to older versions with known vulnerabilities: antd@4.24.16 (v4 is in extended support), @nrwl packages mixed versions (14.x and 19.x), and older dev dependencies. These may contain unpatched security issues. Fix: Update all dependencies to their latest stable versions. Specifically: upgrade antd from v4 to v5, align all @nrwl packages to consistent versions, and update core-js to latest. Run 'npm audit fix' regularly and implement automated dependency scanning.
• Medium · Missing Security Headers in Webview Context — src/vscode-windhawk-ui/apps/vscode-windhawk-ui/src/index.html and src/vscode-windhawk-ui/apps/vscode-windhawk-ui/src/app/vsCodeApi.ts. The webview application communicates with the VS Code extension via webviewIPC.ts. There is no evidence of Content Security Policy (CSP) headers or other security headers being set on the webview context, which could increase XSS attack surface. Fix: Add CSP headers to index.html with strict directives (script-src 'self', img-src data: https:, etc.). Implement X-Frame-Options and X-Content-Type-Options headers. Use nonce-based inline scripts if necessary.
• Medium · IPC Message Validation Not Evident — src/vscode-windhawk-ui/apps/vscode-windhawk-ui/src/app/webviewIPC.ts and webviewIPCMessages.ts. The webviewIPC.ts and webviewIPCMessages.ts files handle communication between the extension and webview. Without visible validation schemas, there's risk of accepting malformed or malicious messages. Fix: Implement strict type validation for all IPC messages using a schema validation library (e.g., zod, joi, or ts-runtime). Validate message structure, types, and payload sizes before processing. Log validation failures.
• Low · Build Script Potential Command Injection — package.json - build-ext script. The build-ext script uses robocopy with piped output and error handling via batch syntax. This could be vulnerable to command injection if any environment variables are untrusted. Fix: Replace batch scripting with cross-platform Node.js scripts or npm packages (e.g., 'fs-extra', 'shx') to handle file operations safely. Avoid shell metacharacters in build scripts.
• Low · No SBOM (Software Bill of Materials) — Repository root. There is no evidence of an SBOM or lock file tracking, which makes it difficult to audit dependency provenance and respond to supply chain vulnerabilities. Fix: Generate and maintain an SBOM using tools like cyclonedx-npm. Commit package-lock.json to version control. Implement dependency scanning in CI/CD pipeline using tools like

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.