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/randyrants/sharpkeys 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 — Stale — last commit 1y ago

• 14 active contributors
• MS-PL licensed
• ⚠ Stale — last commit 1y ago
• ⚠ Single-maintainer risk — top contributor 87% of recent commits
• ⚠ Non-standard license (MS-PL) — review terms
• ⚠ 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 randyrants/sharpkeys repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/randyrants/sharpkeys.

What it runs against: a local clone of randyrants/sharpkeys — 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 randyrants/sharpkeys | Confirms the artifact applies here, not a fork | | 2 | License is still MS-PL | 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 ≤ 510 days ago | Catches sudden abandonment since generation |

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

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(MS-PL)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MS-PL\"" package.json 2>/dev/null) \\
  && ok "license is MS-PL" \\
  || miss "license drift — was MS-PL 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 "SharpKeys/Dialog_Main.cs" \\
  && ok "SharpKeys/Dialog_Main.cs" \\
  || miss "missing critical file: SharpKeys/Dialog_Main.cs"
test -f "SharpKeys/Dialog_KeyPress.cs" \\
  && ok "SharpKeys/Dialog_KeyPress.cs" \\
  || miss "missing critical file: SharpKeys/Dialog_KeyPress.cs"
test -f "SharpKeys/Dialog_KeyItem.cs" \\
  && ok "SharpKeys/Dialog_KeyItem.cs" \\
  || miss "missing critical file: SharpKeys/Dialog_KeyItem.cs"
test -f "SharpKeys/SharpKeys.csproj" \\
  && ok "SharpKeys/SharpKeys.csproj" \\
  || miss "missing critical file: SharpKeys/SharpKeys.csproj"
test -f "SharpKeys/app.config" \\
  && ok "SharpKeys/app.config" \\
  || miss "missing critical file: SharpKeys/app.config"

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

SharpKeys is a Windows GUI utility (C# / .NET 4.0) that exposes and manages the Windows Registry key HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\kbdhid\Parameters\KeyboardLayout to remap physical keyboard keys to other keys without driver installation. It includes a pre-built database of ~100 US keyboard scan codes and a 'Type Key' feature to detect unmapped keys, then writes the remapping binary directly to the Registry. Single-crate monolithic Windows Forms application: SharpKeys/ folder contains three main dialog classes (Dialog_Main.cs, Dialog_KeyPress.cs, Dialog_KeyItem.cs) that manage the UI, and AssemblyInfo.cs defines metadata. App.config holds runtime settings, SharpKeys.exe.manifest declares admin elevation requirement, and the .skl file (HandyRemapForSurfaceKeyboard.skl) is a pre-built example mapping.

Windows users (especially touchtype professionals and accessibility-focused users) who want to remap keys like Caps Lock → Shift, or disable problematic keys. Maintained by Randy Rants (@randyrants) as a personal open-source project; contributors are primarily advanced Windows power users and a few C# developers interested in Registry manipulation.

Actively maintained as of 2024; available on Microsoft Store and via WinGet/scoop installers, indicating production-ready status. No visible test suite in the repo structure, and last commit recency is unknown from the data provided, but the presence of multi-platform support (x86/x64/ARM via separate builds in Releases) and v2→.NET 4.0 migration shows intentional long-term support.

Standard open source risks apply.

No PR/issue/milestone data visible in the provided file list. The presence of .gitignore and recent file structure suggests active GitHub hosting, but specific change activity is not evident from the snapshot. The README mentions Windows 10 support, suggesting the project tracks OS releases.

git clone https://github.com/randyrants/sharpkeys.git
cd sharpkeys/SharpKeys
msbuild SharpKeys.csproj  # or open SharpKeys.sln in Visual Studio 2015+

Daily commands: Open SharpKeys/SharpKeys.sln in Visual Studio 2015+ (or Visual Studio Code with C# extension), then Build → Build Solution (Ctrl+Shift+B). Launch the resulting .exe from bin/Debug or bin/Release. Note: requires admin privileges to write Registry; SharpKeys.exe.manifest declares requireAdministrator level.

• SharpKeys/Dialog_Main.cs — Main application window that loads/saves registry key mappings and orchestrates the entire UI flow—entry point for all user interactions.
• SharpKeys/Dialog_KeyPress.cs — Key capture dialog that intercepts and identifies keyboard key presses—core to the 'Type Key' feature that recognizes arbitrary keys.
• SharpKeys/Dialog_KeyItem.cs — Individual key mapping dialog that defines the source→target key remapping pair—used for every mapping creation/edit.
• SharpKeys/SharpKeys.csproj — Project configuration that defines build targets, .NET framework version (4.0 Client Profile), and assembly metadata.
• SharpKeys/app.config — Application configuration file that may contain registry hive paths and other runtime settings for Windows remapping.
• SharpKeys/AssemblyInfo.cs — Defines assembly versioning, name, and metadata visible to the Windows registry interaction layer.

• Dialog_Main (C#, Windows Forms, Registry API) — Load/save mappings from registry; display list; launch child dialogs for add/edit/delete.
  • Failure mode: Registry read fails → cannot load existing mappings; registry write fails → changes not persisted.
• Dialog_KeyPress (C#, Windows message hook (WM_KEYDOWN/WM_KEYUP)) — Intercept keyboard input; identify key code; return to parent dialog.
  • Failure mode: Key not detected → user cannot identify key; hook fails → dialog hangs.
• Dialog_KeyItem (C#, Windows Forms) — Present dropdowns/buttons for source and target key selection; validate mapping pair.
  • Failure mode: Invalid mapping (e.g., same source/target) → corrupt registry entry.
• App.config (XML) — Runtime configuration (e.g., registry hive path, default settings).
  • Failure mode: Missing config → hardcoded paths fail on non-standard Windows setups.

• Windows Registry (Keyboard Layout key) → Dialog_Main — Load existing key mappings at startup; each mapping is a registry value (source key code → target key code hex).
• Dialog_KeyPress → Dialog_KeyItem — Captured key code passed to editor; user selects target key from list.
• Dialog_KeyItem → Dialog_Main — Completed mapping pair (source, target) returned to main list.
• Dialog_Main → Windows Registry (Keyboard Layout key) — Serialize all mappings and write to HKEY_LOCAL_MACHINE; registry value format: 00000000 XX000000 YY000000 00000000 (hex key codes).
• Windows Kernel → User input device — Kernel applies remapping table; physical key press mapped to logical key before delivery to application.

Add a New Key Mapping Preset

1. Create a new .skl file (text-based registry key format) in the repository root following the same structure as HandyRemapForSurfaceKeyboard.skl (HandyRemapForSurfaceKeyboard.skl)
2. In Dialog_Main.cs, add a menu item or button that loads and deserializes the .skl file into the mappings list (SharpKeys/Dialog_Main.cs)
3. Test the preset by launching the UI and verifying mappings populate correctly (SharpKeys/Dialog_Main.cs)

Add a New Key Recognition Feature

1. Extend Dialog_KeyPress.cs to add a new capture hook or key code mapping strategy (e.g., handle additional scan codes) (SharpKeys/Dialog_KeyPress.cs)
2. Update Dialog_KeyItem.cs to display/select the newly recognized key in the source/target dropdowns (SharpKeys/Dialog_KeyItem.cs)
3. Test by opening Dialog_KeyPress, pressing the new key type, and verifying it is correctly identified (SharpKeys/Dialog_KeyPress.cs)

Modify Registry Writing Logic

1. Locate the registry persistence code in Dialog_Main.cs (likely in a Save or Apply method) that writes to HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Keyboard Layout (SharpKeys/Dialog_Main.cs)
2. Adjust the hex encoding or registry value structure to match Windows requirements (e.g., change key code transformation algorithm) (SharpKeys/Dialog_Main.cs)
3. Test by applying mappings and verifying the registry values match expected format via regedit (SharpKeys/Dialog_Main.cs)

• C# / .NET 4.0 Client Profile — Provides direct Windows Registry access via RegistryKey class and Windows Forms for GUI; lightweight runtime suitable for system utilities.
• Windows Forms — Native Windows UI framework enabling dialog-based UX for key selection and mapping configuration without heavy dependencies.
• Windows Registry (HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Keyboard Layout) — Only official mechanism in Windows to persistently remap keyboard keys at the OS level, survives reboots.
• Keyboard API (WM_KEYDOWN/WM_KEYUP or GetAsyncKeyState) — Captures raw keyboard input to identify key codes in the Type Key feature without third-party input libraries.

• No installer; direct executable distribution

  • Why: Reduces complexity and allows users to run portably; app only needs registry write access.
  • Consequence: Users must manually place .exe; no automatic updates; requires manual elevation for registry access.

• Stored as .skl text/registry files rather than database

  • Why: Aligns with Windows convention of registry-based system settings; portable and human-readable.
  • Consequence: No built-in versioning or backup; large mapping collections stored in registry may impact boot time.

• Modal dialogs for key capture and mapping editing

  • Why: Simpler state management; clear user intent; avoids asynchronous callback complexity.
  • Consequence: UI is blocking; cannot work on multiple mappings in parallel; less responsive feel.

• Does not remap keys for specific applications only; applies globally to all contexts.
• Does not support macros or multi-key sequences; only 1:1 key-to-key mappings.
• Does not provide a GUI-based registry editor; only edits the Keyboard Layout registry key.
• Does not support Linux or macOS; Windows-only due to registry dependency.
• Does not include cloud sync or cross-device settings backup.

• Direct registry manipulation without error handling — SharpKeys/Dialog_Main.cs (inferred): Registry writes may fail due to permissions or hive locks; code likely does not handle RegistryAccessDeniedException or InvalidOperationException gracefully.

1. Admin elevation required: The .exe.manifest's requireAdministrator tag means the app will prompt for UAC; silent Registry writes will fail if not elevated. 2. Registry path is hardcoded: The Registry key path (HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\kbdhid\Parameters\KeyboardLayout) is likely a magic string in Dialog_Main.cs; changing it breaks all users. 3. Scan code database is monolithic: No visible separate data file for the ~100 US keyboard keys; they are likely hardcoded in Dialog_KeyItem.cs or .resx, making international keyboard support painful. 4. Reboot required for enforcement: Changes only take effect after logout or reboot (per README); testing requires full OS restart, not app restart. 5. No undo from GUI: Once written, the only way to undo a bad mapping is to edit the Registry manually or reinstall.

• Windows Registry Scan Code Mapping (kbdhid KeyboardLayout key) — SharpKeys' entire purpose is to manage this specific Registry binary value; understanding the scan code format (little-endian pairs: source code + target code) is essential to modifying Dialog_Main.cs's write logic.
• HID Scan Codes (USB HID specification) — The Dialog_KeyPress.cs capture logic and the hardcoded key list depend on knowing which physical key press maps to which numeric scan code; critical for adding new keys or fixing detection.
• WinForms Event-Driven Architecture (KeyDown, KeyPress, KeyUp) — Dialog_KeyPress.cs uses KeyDown/KeyUp events to capture raw input without translation; misunderstanding event order or modifiers (Ctrl, Shift) causes bugs in key detection.
• Windows Registry Hive Structure (HKEY_LOCAL_MACHINE vs. HKEY_CURRENT_USER) — SharpKeys writes to HKEY_LOCAL_MACHINE (system-wide), not HKEY_CURRENT_USER (per-user); this choice affects persistence, UAC elevation, and which users are affected.
• .NET Framework 4.0 Client Profile Compatibility — App.config targets .NET 4.0 Client Profile (not Full Framework); this restricts available base libraries and affects how to upgrade to .NET 6+ without breaking legacy Windows XP/Vista support claims.
• P/Invoke (Platform Invocation Services) — Direct Registry access via Microsoft.Win32.Registry API; if raw Registry calls or low-level I/O become necessary, P/Invoke to Windows API (RegOpenKeyEx, RegSetValueEx) may be required.
• Binary Key Layout Format (Little-Endian Encoded Scan Code Pairs) — The Registry value is a binary blob, not plaintext; Dialog_Main.cs must serialize/deserialize the mapping list to/from little-endian 16-bit pairs (header + source1 + target1 + source2 + target2 + ... + terminator). Any serialization bug breaks all mappings.

• microsoft/PowerToys — PowerToys > Keyboard Manager is a modern first-party Microsoft alternative to SharpKeys with GUI and profile management; co-exists in same ecosystem.
• jakerudolph/keymapper — Open-source keyboard remapper for Windows; older abandoned project but similar Registry-hacking approach to SharpKeys.
• W4LD0/KeySwap — Another Registry-based Windows key remapper; shows alternative UI patterns and feature parity comparisons.
• dotnet/winforms — Official .NET WinForms repository; SharpKeys is a WinForms application; essential for understanding UI framework and compatibility.
• microsoft/terminal — Modern Windows developer tool; relevant for understanding current .NET ecosystem and how newer projects differ from SharpKeys' .NET 4.0 baseline.

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 unit tests for Dialog_KeyPress.cs key detection logic

The Dialog_KeyPress.cs file handles the 'Type Key' feature that automatically recognizes keyboard keys. This critical functionality lacks test coverage, making it vulnerable to regressions across different keyboard layouts and key types. Adding unit tests would ensure the key detection works correctly for edge cases (modifier keys, special keys, international layouts) and provide confidence for future refactoring.

• [ ] Create SharpKeys.Tests project in the solution
• [ ] Add unit tests for Dialog_KeyPress.cs key recognition logic (test common keys, modifier combinations, special keys)
• [ ] Test edge cases like unmapped keys and rapid key presses
• [ ] Wire tests into CI/CD pipeline (add .github/workflows/dotnet-test.yml for automated test runs on PR)

Refactor Dialog_Main.cs into separate concerns (Model, View, Controller layers)

Dialog_Main.cs appears to be a monolithic WinForms file handling UI rendering, registry management, and user remapping logic simultaneously. This violates separation of concerns and makes the codebase hard to test and maintain. Splitting into RegistryManager.cs, RemappingModel.cs, and keeping UI-only logic in Dialog_Main would improve testability and modularity.

• [ ] Extract registry read/write operations from Dialog_Main.cs into a new RegistryManager.cs class
• [ ] Extract remapping data model and validation logic into a new RemappingModel.cs class
• [ ] Update Dialog_Main.cs to call these new classes rather than implementing logic directly
• [ ] Add unit tests for RegistryManager.cs and RemappingModel.cs to verify core functionality

Add XML documentation comments and generate DocFX documentation site

The codebase lacks inline documentation (missing /// XML comments in Dialog_KeyItem.cs, Dialog_KeyPress.cs, Dialog_Main.cs). New contributors cannot quickly understand the purpose of key methods or classes. Adding standardized XML documentation and generating a DocFX site would lower the barrier to contribution and help users understand the registry key structure being modified.

• [ ] Add XML documentation comments (///) to all public classes and methods in SharpKeys/*.cs files
• [ ] Add special documentation to Dialog_KeyPress.cs explaining the key detection algorithm
• [ ] Add docfx.json and docs template setup in repo root
• [ ] Create .github/workflows/docfx.yml to auto-publish docs on releases
• [ ] Update README.md with link to generated documentation

• Add a 'Reset to defaults' button in Dialog_Main.cs that clears all remappings from the Registry without requiring manual Registry editor access. This requires reading the current Registry state, displaying it, and providing a safe delete option.: File: Dialog_Main.cs; feature gap in the UI for reverting changes.
• Extract the hardcoded US keyboard scan code list into a separate .xml or .csv data file (e.g., KeyCodes.xml) and add a parser in a new KeyCodeRepository.cs class. This unblocks future addition of international keyboard layouts (German QWERTZ, French AZERTY, etc.) without recompiling.: Refactoring: likely in Dialog_KeyItem.cs or Dialog_KeyPress.cs; modularity for i18n.
• Add a .skl file import/export feature (parse/serialize the mappings to/from XML or JSON) so users can share and backup their key mapping configurations. The HandyRemapForSurfaceKeyboard.skl file in the repo hints that this format exists but may not be fully implemented.: Files: Dialog_Main.cs (add menu items), create new SketchLayoutSerializer.cs or similar; feature gap visible from .skl file presence.

SharpKeys has moderate security concerns primarily related to outdated framework versions and direct Registry manipulation without visible input validation safeguards. The application's core functionality—modifying Windows Registry for keyboard remapping—is inherently privileged and requires careful security implementation. The .NET 4.0 framework is outdated and unsupported. While there are no obvious injection vulnerabilities or hardcoded secrets visible, the lack of code signing, comprehensive input validation patterns, and explicit privilege management represents risk. Recommend modernizing the framework, implementing rigorous input validation, adding code signing, and explicitly documenting all Registry modification operations.

• High · Direct Registry Manipulation Without Validation — SharpKeys application core functionality (Dialog_Main.cs, Dialog_KeyItem.cs). SharpKeys directly modifies Windows Registry keys for keyboard remapping. Without proper input validation and sanitization, this could allow attackers to remap keys maliciously or cause system instability. Registry modifications require administrative privileges and could impact system security if not properly validated. Fix: Implement strict input validation and sanitization for all key mapping inputs. Validate that only legitimate keyboard scan codes are accepted. Add logging for all Registry modifications. Consider implementing a whitelist of allowed key mappings.
• Medium · Outdated .NET Framework — SharpKeys/SharpKeys.csproj, AssemblyInfo.cs. The application targets .NET 2.0 and .NET 4.0 Client Profile, which are outdated and no longer actively supported by Microsoft. These frameworks lack modern security patches and improvements. The .NET 4.0 Client Profile is particularly concerning as it has been discontinued. Fix: Upgrade to .NET Framework 4.8 or migrate to .NET 6+ (if dependencies allow). This ensures access to the latest security patches and performance improvements.
• Medium · Missing Security Manifest Validation — SharpKeys/SharpKeys.exe.manifest. The application includes SharpKeys.exe.manifest but without visibility into its contents, there's a risk it may not properly declare required permissions or security context. Improper manifest configuration could lead to privilege escalation issues. Fix: Review and validate the manifest file to ensure it properly declares all required permissions and uses requestedExecutionLevel='highestAvailable' only when necessary. Implement explicit permission requests rather than auto-elevation.
• Medium · Administrative Privilege Requirement Without Clear Notification — SharpKeys/Dialog_Main.cs. Registry key remapping requires administrative privileges, but the codebase doesn't show explicit privilege escalation warnings or checks. Users may not understand they're granting administrative access. Fix: Implement explicit privilege level checks and user consent dialogs. Clearly inform users that the application requires administrative privileges and explain why. Use UAC properly for privilege escalation.
• Low · No Dependency Version Locking — SharpKeys/SharpKeys.csproj. No package file (packages.config, .csproj with PackageReference) was provided. If external dependencies are used, there's a risk of transitive dependency vulnerabilities from uncontrolled version updates. Fix: If using NuGet packages, ensure packages.config or .csproj explicitly pins dependency versions. Regularly audit dependencies using tools like OWASP Dependency-Check or GitHub Dependabot.
• Low · Missing Code Signing — SharpKeys/SharpKeys.exe. No evidence of code signing for the executable. This increases the risk of tampering and makes it harder for users to verify authenticity. Fix: Implement code signing with a valid certificate from a trusted Certificate Authority. This protects against tampering and helps users verify the application's authenticity.

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.