Windhawk

Windhawk aims to make it easier to customize Windows programs. For more details, see the official website and the announcement.

This repository is used to report issues and to discuss Windhawk. For discussing Windhawk mods, refer to the windhawk-mods repository.

You're also welcome to join the Windhawk Discord channel for a live discussion.

Technical details

High-level architecture:

For technical details about the global injection and hooking method that is used, refer to the following blog post: Implementing Global Injection and Hooking in Windows.

Runtime storage contract

The most important runtime invariant for a working build is that the app, the embedded extension, and the engine all resolve to the same storage backend.

• windhawk.ini selects the install mode and points the app and extension to the active app-data root, engine folder, compiler folder, and UI runtime.
• Engine\<version>\engine.ini must resolve to the matching engine app-data root and, for installed mode, the matching registry subtree.
• If those files disagree, the UI can still show mods as installed while the injected engine loads a different storage location and the mods never activate.

The current fork now exposes runtime diagnostics in the About page, surfaces storage mismatches on the Home page, and includes a repair action that rewrites the engine config to match the active install.

Source code

The Windhawk source code can be found in the src folder, which contains the following subfolders:

• windhawk: The code of the main windhawk.exe executable and the 32-bit and 64-bit windhawk.dll engine libraries.

• vscode-windhawk: The code of the VSCode extension that is responsible for UI operations such as installing mods and listing installed mods.

• vscode-windhawk-ui: The UI part of the VSCode extension.

A simple way to get started is by extracting the portable version of Windhawk with the official installer, building the part of Windhawk that you want to modify, and then replacing the corresponding files in the portable version with the newly built files.

Development

Contributor setup, verified validation commands, and native build prerequisites are documented in CONTRIBUTING.md.

Portable installer build

This fork includes a portable packaging flow that bundles the rebuilt native binaries, the VS Code extension, and the React webview into a custom installer.

Typical packaging flow:

1. Refresh the native Release binaries:

$vsPath = & "${env:ProgramFiles(x86)}\Microsoft Visual Studio\Installer\vswhere.exe" `
  -latest -products * -property installationPath
cmd /c "call `"$vsPath\VC\Auxiliary\Build\vcvars64.bat`" && cd /d src\windhawk && build.bat Release"

2. Run the packaging script from the repository root. It rebuilds the webview and extension by default before staging the portable payload:

powershell -ExecutionPolicy Bypass -File artifacts\installer-build\build_custom_portable.ps1

If src\windhawk\build.bat doesn't detect the local Visual Studio installation automatically, a Visual Studio developer shell or the explicit vswhere + vcvars64.bat sequence above is the supported fallback.

The script produces artifacts/windhawk-custom-portable-installer.exe and artifacts/portable-build/windhawk-custom-portable.zip, refreshes the staged portable payload used by the installer stub, and expects a portable Windhawk baseline at %LOCALAPPDATA%\Programs\Windhawk-Custom-Portable. Use -SkipBuild only when you intentionally want to reuse the current webview and extension outputs.

UI preview

The React webview lives in src/vscode-windhawk-ui and can be iterated on independently from the native C++ binaries.

Typical local preview workflow:

1. cd src/vscode-windhawk-ui
2. npm install --ignore-scripts --no-package-lock
3. npx nx build vscode-windhawk-ui
4. Serve dist/apps/vscode-windhawk-ui with a static file server, for example: python -m http.server 4200 --directory dist/apps/vscode-windhawk-ui

Then open http://127.0.0.1:4200/.

Recent UI improvements

The webview UI now includes:

• smarter mod discovery with typo recovery, query broadening, and refinement suggestions
• a redesigned settings experience with persistent local workspace controls for density, startup page, Explore default sorting, editor assistance level, Windows quick-action density, wide layout, reduced motion, and performance tuning
• an expanded About page with current workspace status, runtime diagnostics, path inspection, repair actions, and quicker access to key project resources
• a richer installed-mods home view with a fast overview strip and an early warning when the engine storage backend diverges from the UI backend
• a research-informed install decision modal with scope/freshness/community signals and one-click review actions for details, source, and changelog tabs
• strategy-based install guidance with a disabled-first path for broad-scope or lower-reviewability mods, plus a short pre-install checklist derived from scope and freshness
• a shared changelog explorer with release-summary cards and inline filtering in both the About page and per-mod changelog views
• browse-mode insight chips in Explore so fresh, popular, and focused mods stand out even before typing a query
• guided Explore starting points that jump straight into fresh updates, community favorites, or focused areas such as Taskbar, Explorer, Start menu, and Audio
• research-backed Explore missions that turn common Windows goals into compare-and-verify flows, with copyable AI comparison briefs and an active mission workbench for top-candidate comparison
• broader Windows-surface discovery presets for notifications, window management, input, and appearance so the catalog is easier to navigate by the Windows area you want to change
• more Windows customization entry points in Explore for context menus, the desktop surface, Alt+Tab, virtual desktops, and widgets so it is easier to start from the part of Windows you actually want to change
• richer changelog tooling with release scoping, a latest-only toggle, and copy-to-clipboard support for the currently visible notes
• a new mod studio that promotes AI-assisted authoring with code-first and visual creation modes, language-aware C++ and Python starter filtering, a structured core starter, an AI-ready starter template, focused starters for Explorer shell work, Chromium/Chrome browser mods, window behavior mods, settings-first experiments, and optional .wh.py Python automation authoring that renders back to compatible .wh.cpp
• workflow bundles inside the mod studio with recommended launch paths, copyable kickoff packets, and CLI playbooks that combine the chosen starter, prompt packs, and verification checklist into one handoff
• persistent recent studio sessions in New Mod Studio so starters, visual presets, and workflow bundles can be relaunched with the same launch brief, packet, authoring language, and studio mode
• a redesigned editor cockpit with a real scroll shell, a pinned exit action, live mod metadata, visible compile mode cards, a one-click recommended compile action, an evidence board, a verification pack, a dynamic iteration plan, and copyable AI helper prompts for scope analysis, test planning, release notes, and review
• contextual Windows integration inside the editor cockpit, including inferred shell-surface tags and one-click deep links into the Windows settings pages that match the current mod's target processes
• newer research-driven editor innovations including prompt-less AI explainers for APIs, Windows terms, and usage examples, a visible challenge board that pushes the draft with counterquestions instead of agreement, a best-practice audit prompt, and a validation-feedback recovery prompt for failed builds
• a Windows toolkit on the About page with live OS/session diagnostics, expanded quick links into key Windows settings surfaces such as Start, Notifications, Multitasking, Colors, Background, Themes, Lock screen, Clipboard, and one-click opening of Windhawk runtime paths in Explorer
• local home quick-focus chips for drafts, compile-needed mods, logging-enabled mods, and pending updates so maintenance work is easier to batch
• a new Performance and AI settings section with runtime-based profile recommendations, NPU-aware acceleration preferences, and coordinated local UI presets for balanced, responsive, or efficient workspaces
• richer runtime diagnostics that now surface system memory and detected NPU hardware so local recommendations and Windows troubleshooting are grounded in the active machine
• a curated force-process-accelerators repository mod surfaced as a featured available install so process CPU/GPU/NPU preference tuning is easier to discover from the default catalog

Research-informed UX improvements

These interaction changes are intentionally grounded in a small set of papers that map well to Windhawk's mod-install and release-review workflows.

• Crying Wolf: An Empirical Study of SSL Warning Effectiveness motivated a more concrete install warning with supporting context and clear review paths instead of a single generic caution block.
• An Empirical Study of Release Note Production and Usage in Practice informed the release-summary cards and searchable changelog view so the most actionable updates are visible before reading the full Markdown stream.
• The Eyes Have It: A Task by Data Type Taxonomy for Information Visualizations continues to inform the "overview first, zoom and filter, then details on demand" structure used across Explore, changelog, and the editor cockpit's visible mode cards and status surfaces.
• Using an LLM to Help With Code Understanding pushed the editor cockpit toward prompt-light, in-IDE requests such as scope explanation, API understanding, and test-plan generation instead of one generic AI action.
• Identifying the Factors that Influence Trust in AI Code Completion motivated the evidence board, visible compile mode states, and safer compile recommendations so AI assistance is paired with explicit trust signals and verification steps.
• Source-level Debugging with the Whyline informed the new mission and editor flows that foreground "why this candidate?", "what Windows surface should I check?", and "what should I verify next?" instead of forcing users to build those questions manually.
• AI-assisted Assessment of Coding Practices in Industrial Code Review motivated the new best-practice audit prompt so contributors can ask for language-aware C++ and Windows review comments instead of only generic summaries.
• AI Should Challenge, Not Obey directly informed the editor challenge board and counterexample-hunt prompts so the assistant can question assumptions rather than merely comply.
• A Case Study of LLM for Automated Vulnerability Repair: Assessing Impact of Reasoning and Patch Validation Feedback pushed the new compile-recovery prompt toward smaller, validation-driven iteration loops after build failures instead of broader speculative rewrites.

Research-informed reliability

The new diagnostics and repair flow is based on a narrow, reliability-focused interpretation of configuration research rather than more invasive runtime behavior changes.

• PeerPressure: Using Peer Configuration to Troubleshoot Systems Automatically motivated the idea of treating configuration mismatches as first-class failures instead of as vague runtime symptoms.
• Strider: A Black-box, State-based Approach to Change and Configuration Management and Support informed the emphasis on comparing observed state with expected state before attempting repair.
• Automatically Generating Predicates and Solutions for Configuration Troubleshooting reinforced the direction of pairing diagnostics with concrete, low-friction fixes instead of only presenting raw paths and flags.
• The Eyes Have It: A Task by Data Type Taxonomy for Information Visualizations informed the UI structure: overview first, then diagnostic details on demand.

Advanced Research Features (2025-2026)

This research fork of Windhawk implements state-of-the-art stealth and evasion techniques:

Injection & Stealth

• Indirect Syscalls: Bypassing EDR/AV hooks by dynamically resolving SSNs and using legitimate syscall instructions in ntdll.
• Phantom Thread Pool Injection: Hijacking existing Windows Thread Pool worker threads via APCs to avoid NtCreateThreadEx detection.
• Module Stomping: Hiding engine shellcode within the memory region of signed, file-backed Microsoft DLLs (e.g., xpsprint.dll).
• ETW Evasion: Surgical suppression of EtwEventWrite to blind telemetry during sensitive engine operations.

Hooking & Integrity

• HWBP Hooking Engine: Hardware Breakpoint-based hooking using CPU Debug Registers (DR0-DR3), ensuring zero bytes of target code are modified.
• Injection Integrity Guard: VEH-based PAGE_GUARD monitoring to detect and alert on unauthorized tampering of engine trampolines.
• Call Stack Spoofing: Synthetic ROP chain construction to hide the engine's origin during critical OS API calls.

Performance & API

• Mod Sandbox: Per-mod resource limits (CPU rate, Memory MB, Max Handles) via thread-level throttling and background priority.
• Priority-Based Filtering: Orchestrated injection flow with configurable priorities (Deferred, Low, Normal, High, Critical).
• Extended Mods API: Native support for Wh_GetProcessInfo, Wh_RegisterCallback (async events), and Wh_GetSystemInfo.

Additional resources

Code that demonstrates the global injection and hooking method that is used can be found in this repository: global-inject-demo.