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/mgth/LittleBigMouse 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 9mo ago

• Last commit 9mo ago
• 2 active contributors
• GPL-3.0 licensed
• CI configured
• Tests present
• ⚠ Slowing — last commit 9mo ago
• ⚠ Small team — 2 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 99% of recent commits
• ⚠ GPL-3.0 is copyleft — check downstream compatibility

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

What it runs against: a local clone of mgth/LittleBigMouse — 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 mgth/LittleBigMouse | 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 master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 297 days ago | Catches sudden abandonment since generation |

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "mgth/LittleBigMouse(\\.git)?\\b" \\
  && ok "origin remote is mgth/LittleBigMouse" \\
  || miss "origin remote is not mgth/LittleBigMouse (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 master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "LittleBigMouse.Core/LittleBigMouse.DisplayLayout/Monitors/MonitorsLayout.cs" \\
  && ok "LittleBigMouse.Core/LittleBigMouse.DisplayLayout/Monitors/MonitorsLayout.cs" \\
  || miss "missing critical file: LittleBigMouse.Core/LittleBigMouse.DisplayLayout/Monitors/MonitorsLayout.cs"
test -f "LittleBigMouse.Core/LittleBigMouse.DisplayLayout/Dimensions/DisplayRatio.cs" \\
  && ok "LittleBigMouse.Core/LittleBigMouse.DisplayLayout/Dimensions/DisplayRatio.cs" \\
  || miss "missing critical file: LittleBigMouse.Core/LittleBigMouse.DisplayLayout/Dimensions/DisplayRatio.cs"
test -f "HLab.Sys/HLab.Sys.Windows.Monitors/MonitorsService.cs" \\
  && ok "HLab.Sys/HLab.Sys.Windows.Monitors/MonitorsService.cs" \\
  || miss "missing critical file: HLab.Sys/HLab.Sys.Windows.Monitors/MonitorsService.cs"
test -f "HLab.Sys/HLab.Sys.Windows.Monitors/MonitorDevice.cs" \\
  && ok "HLab.Sys/HLab.Sys.Windows.Monitors/MonitorDevice.cs" \\
  || miss "missing critical file: HLab.Sys/HLab.Sys.Windows.Monitors/MonitorDevice.cs"
test -f "LittleBigMouse.Core/LittleBigMouse.DisplayLayout/Monitors/PhysicalMonitor.cs" \\
  && ok "LittleBigMouse.Core/LittleBigMouse.DisplayLayout/Monitors/PhysicalMonitor.cs" \\
  || miss "missing critical file: LittleBigMouse.Core/LittleBigMouse.DisplayLayout/Monitors/PhysicalMonitor.cs"

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

Little Big Mouse is a Windows-native DPI-aware mouse movement utility that solves the cursor jump problem when moving between monitors with different DPI settings (e.g., 4K + 1080p). It intercepts mouse input via a C++/Rust hook mechanism and translates coordinates to account for display scaling differences, enabling seamless cursor crossover with configurable speed, border resistance, and infinite scrolling across heterogeneous monitor setups. Modular monorepo: HLab.Sys/ contains Windows system abstractions (Monitors/, MonitorVcp/, Argyll color management); LittleBigMouse.Ui/ provides Avalonia UI; core mouse hooking logic split between C# (.NET) and C++/Rust (LittleBigMouse_Hook_Rust). Display enumeration via WinAPI wrapping (DisplayDevice.cs, MonitorDevice.cs), configuration persisted and bound to UI viewmodels.

Windows 10/11 users with multi-monitor setups involving mixed DPI displays (particularly gamers and productivity users with high-DPI + standard-DPI monitor combinations), and contributors maintaining the core mouse hooking logic and display enumeration subsystem.

Actively maintained with recent CI/CD setup (.github/workflows/dotnet-desktop.yml indicates modern build practices), substantial codebase (729KB C#, 272KB C++), and published releases. However, single maintainer (mgth) and sparse visible test files suggest moderate maturity—production-ready for its niche use case but not enterprise-grade.

Core risk: low-level mouse hook implementation (C++/Rust) requires kernel interaction and can destabilize input if buggy; single maintainer (mgth) creates continuity risk. Windows API surface area is large (HLab.Sys.Windows.Monitors enumerates display devices, EDID parsing, VCP controls); breaking Windows updates could require rework. No visible comprehensive test suite in file list.

Recent activity: Avalonia UI migration (HLab.Sys.Windows.MonitorVcp.Avalonia suggests modernization from legacy WPF/WinForms); GitHub Actions workflow indicates active CI/CD; color management and luminance tuning features under development (Tune.cs, ProbeLut.cs). Rust hook component initialized but not yet mature (LittleBigMouse_Hook_Rust/Cargo.toml is skeleton).

Clone the repo: git clone https://github.com/mgth/LittleBigMouse.git && cd LittleBigMouse. Restore .NET dependencies: dotnet restore. Build: dotnet build. Run the UI: dotnet run --project LittleBigMouse.Ui/LittleBigMouse.Ui.Avalonia (or check .github/workflows/dotnet-desktop.yml for exact build matrix).

Daily commands: After dotnet restore && dotnet build, run via: dotnet run --project LittleBigMouse.Ui/LittleBigMouse.Ui.Avalonia. For development with hot reload: dotnet watch --project LittleBigMouse.Ui/LittleBigMouse.Ui.Avalonia run. For Rust hook component: cd LittleBigMouse_Hook_Rust && cargo build (currently skeleton).

• LittleBigMouse.Core/LittleBigMouse.DisplayLayout/Monitors/MonitorsLayout.cs — Core layout engine that orchestrates multi-monitor DPI-aware positioning and mouse coordinate transformation—the heart of the application.
• LittleBigMouse.Core/LittleBigMouse.DisplayLayout/Dimensions/DisplayRatio.cs — Handles DPI ratio calculations and scaling transformations across monitors with different pixel densities.
• HLab.Sys/HLab.Sys.Windows.Monitors/MonitorsService.cs — Windows-specific monitor device enumeration and configuration—bridge between OS display APIs and the layout engine.
• HLab.Sys/HLab.Sys.Windows.Monitors/MonitorDevice.cs — Abstraction for individual physical monitors, exposing capabilities, resolution, and DPI information from Windows.
• LittleBigMouse.Core/LittleBigMouse.DisplayLayout/Monitors/PhysicalMonitor.cs — Domain model representing a monitor in the layout with physical dimensions, resolution, and position metadata.
• LittleBigMouse.Core/LittleBigMouse.DisplayLayout/Dimensions/DisplayScale.cs — Encapsulates scaling logic for translating mouse coordinates between logical and physical pixel spaces.

Add a New DPI Transformation Algorithm

1. Create a new class inheriting from DisplayRatio or DisplayScale in the Dimensions folder (LittleBigMouse.Core/LittleBigMouse.DisplayLayout/Dimensions/DisplayRatio.cs)
2. Implement coordinate transformation logic (e.g., scaling, rotation, perspective correction) (LittleBigMouse.Core/LittleBigMouse.DisplayLayout/Dimensions/DisplayScale.cs)
3. Register the transformation in MonitorsLayout via the dimension registry or factory (LittleBigMouse.Core/LittleBigMouse.DisplayLayout/Monitors/MonitorsLayout.cs)
4. Test with MultiMonitorTestCase in DisplayLayout.Tests (LittleBigMouse.Core/LittleBigMouse.DisplayLayout.Tests/UnitTest1.cs)

Support a New Monitor Detection Method

1. Extend MonitorDevice or create a variant that parses your device source (HLab.Sys/HLab.Sys.Windows.Monitors/MonitorDevice.cs)
2. Add a factory method in MonitorDeviceHelper for your detection strategy (HLab.Sys/HLab.Sys.Windows.Monitors/Factory/MonitorDeviceHelper.cs)
3. Update MonitorsService to call your factory during enumeration (HLab.Sys/HLab.Sys.Windows.Monitors/MonitorsService.cs)
4. Ensure EDID parsing is compatible, or extend Edid.cs for new metadata (HLab.Sys/HLab.Sys.Windows.Monitors/Edid.cs)

Add Monitor Calibration/VCP Control Feature

1. Define VCP commands and response parsing in VcpControl.cs (HLab.Sys/HLab.Sys.Windows.MonitorVcp/VcpControl.cs)
2. Create a model class (e.g., MonitorLevel subclass) for the control parameter (HLab.Sys/HLab.Sys.Windows.MonitorVcp/MonitorLevel.cs)
3. Expose the control through MonitorDevice extensions or a new IMonitorsService interface method (HLab.Sys/HLab.Sys.Windows.Monitors/IMonitorsService.cs)
4. Add UI binding in the Avalonia UI layer (if present) and test in TestPatternWindow (HLab.Sys/HLab.Sys.Windows.MonitorVcp.Avalonia/TestPatternWindow.axaml.cs)

Implement a New Layout Zone Strategy

1. Study ZonesLayoutFactory to understand zone creation patterns (LittleBigMouse.Core/LittleBigMouse.DisplayLayout/Monitors/Extensions/ZonesLayoutFactory.cs)
2. Create a new factory or strategy class that defines zone boundaries and crossing rules (LittleBigMouse.Core/LittleBigMouse.DisplayLayout/Monitors/MonitorsLayout.cs)
3. Implement coordinate mapping via ILayoutOptions or a layout mode enum (LittleBigMouse.Core/LittleBigMouse.DisplayLayout/Monitors/ILayoutOptions.cs)
4. Test with TravelDistanceHelper edge cases (screen edges, diagonals) (LittleBigMouse.Core/LittleBigMouse.DisplayLayout/Monitors/Extensions/TravelDistanceHelper.cs)

• C# / .NET — Provides Windows API interoperability, strong typing for coordinate transformations, and cross-platform UI frameworks (Avalonia)
• Windows API (P/Invoke) — Necessary for direct access to EDID, display modes, monitor enumeration, and VCP control unavailable through managed APIs
• Avalonia — Cross-platform XAML-based UI framework for configuration UI and test visualization without WPF lock-in
• Argyll CMS — Industry-standard color calibration toolkit for monitor profile and gamut management integration
• Rust (planned/submodule) — undefined

WinAPI fragility: DisplayChangeMonitor.cs hooks WM_DISPLAYCHANGE messages; timing edge cases between monitor hot-plugging and DPI cache invalidation can cause stale coordinate math. EDID parsing: Edid.cs relies on Windows DDC-CI protocol which not all monitors implement; fallback to WinAPI GetDeviceCaps may report logical rather than physical DPI. Rust hook immaturity: LittleBigMouse_Hook_Rust/Cargo.toml has no dependencies and is empty—Rust integration is experimental, unclear if/when it will replace C++ hook. UI framework transition: Avalonia codebase exists alongside legacy (likely WinForms or WPF) code paths; mixing old and new UI may cause state sync bugs. Single-threaded UI: Avalonia UI thread must not block on WinAPI calls in DisplayDevice enumeration or color profile parsing.

• DPI Scaling & Logical vs. Physical Pixels — LBM's entire reason for existence; cursor coordinates are logical (OS-reported) but must map to physical pixels when crossing monitors with different scale factors (96 DPI → 192 DPI requires 2× coordinate adjustment).
• EDID (Extended Display Identification Data) — Core input to DPI detection; Edid.cs parses raw EDID binary blobs to extract native resolution and timing specs, which feed coordinate transformation math.
• DDC-CI (Display Data Channel Command Interface) — Enables VcpControl.cs to send brightness/contrast commands to monitors via I²C; used for real-time color/luminance balancing feature.
• Low-Level Mouse Hooking (SetWindowsHookEx) — LBM intercepts mouse move events at kernel level via WinAPI WH_MOUSE_LL hook to inject DPI-aware coordinate transformation before OS delivers input to applications.
• WinAPI Display Enumeration (EnumDisplayDevices, GetDeviceCaps) — DisplayDevice.cs uses these to discover physical monitors, resolutions, and DPI via Windows Device Manager; foundation for building the multi-monitor virtual coordinate space.
• MVVM (Model-View-ViewModel) Pattern — Avalonia UI uses viewmodels (e.g., LuminanceViewModel.cs) to bind display state to UI elements; changes to monitors trigger reactive updates across the UI layer.
• Coordinate Transformation & Affine Mapping — Core algorithm in DeviceFactory.cs: maps cursor (x, y) from logical OS space to physical pixel space accounting for per-monitor DPI, rotation, and relative positioning—non-trivial when monitors have different scales.

• zhongyang219/TrafficMonitor — Also uses low-level WinAPI hooking and multi-monitor awareness on Windows; similar system integration challenges and coordinate transformation patterns.
• easymotion/vim-easymotion — While Vim-focused, demonstrates elegant coordinate mapping and DPI-agnostic input handling that LBM could reference for algorithm design.
• microsoft/Terminal — Heavy Avalonia/WinRT user with multi-monitor and DPI scaling expertise; source for best practices on cross-DPI rendering and coordinate math.
• jketing/Mos — macOS equivalent solving similar multi-monitor mouse coordination; architecture patterns (event hooking, coordinate transformation) are language-agnostic and instructive.
• argyllcms/argyllcms — Referenced in HLab.Sys.Argyll/; color management companion used by LBM for display profiling and calibration validation.

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 DisplayLayout.XUnit test project

The LittleBigMouse.DisplayLayout.XUnit project exists but contains only a stub UnitTest1.cs. Given that this is a DPI-aware mouse positioning system, there should be extensive tests for display layout calculations, multi-DPI scenarios, and screen crossover logic. This is critical for correctness in different monitor configurations (4K + FHD combinations mentioned in README).

• [ ] Review DisplayLayout/Dimensions/DisplayInverseRatio.cs and other Dimensions classes to understand calculation logic
• [ ] Create test cases for multi-DPI scenarios (4K + 1080p combinations)
• [ ] Add tests for screen crossover edge cases (cursor movement between monitors with different DPI)
• [ ] Add tests for coordinate transformation and ratio calculations
• [ ] Replace stub UnitTest1.cs in LittleBigMouse.DisplayLayout.XUnit with real test suite

Complete Rust mouse hook implementation and CI/CD integration

The Dependencies/LittleBigMouse_Hook_Rust Cargo.toml exists as an empty project (no dependencies, version 0.1.0). The mouse hook is likely the critical native component for DPI-aware cursor movement. This needs implementation and a GitHub Actions workflow to compile and test the Rust hook across Windows architectures (x86/x64), similar to the existing dotnet-desktop.yml.

• [ ] Implement core Rust mouse hook functionality with Windows API bindings (winapi or windows-rs crate)
• [ ] Add dependencies to Cargo.toml (windows, log, etc.)
• [ ] Create GitHub Actions workflow (.github/workflows/rust-build.yml) to build Rust project for x86 and x64
• [ ] Add integration test in CI to verify Rust DLL compilation
• [ ] Document build and linking process between C# and Rust components in README

Expand HLab.Sys.Windows.Monitors test coverage with multi-monitor scenarios

The HLab.Sys.Windows.Monitors project handles monitor detection (DisplayDevice.cs, MonitorsService.cs, EDID parsing). With no visible test project for this assembly, critical monitor enumeration and capability detection logic is untested. This directly impacts the correctness of DPI detection and monitor layout calculation.

• [ ] Create new test project HLab.Sys.Windows.Monitors.Tests alongside existing csproj
• [ ] Add unit tests for Edid.cs parsing (test EDID data deserialization from various monitor types)
• [ ] Add tests for DeviceCaps.cs DPI and resolution detection
• [ ] Add tests for DisplayDevice enumeration and PhysicalAdapter matching logic
• [ ] Add integration tests for edge cases (disconnected monitors, resolution changes, EDID parsing failures)

• Add unit tests for Edid.cs parsing logic. Currently no visible test files in HLab.Sys.Windows.Monitors/; write xUnit tests covering EDID header validation, descriptor block parsing, and fallback for malformed data.: Critical path for DPI detection lacks coverage; edge cases in EDID parsing can silently produce wrong DPI values.
• Document coordinate transformation algorithm in HLab.Sys.Windows.Monitors/Factory/DeviceFactory.cs with inline comments and a README. Include numerical examples (e.g., cursor at x=1920 on 100% DPI crossing to 200% DPI monitor).: The core DPI-aware mouse math is opaque; new contributors cannot confidently modify or debug coordinate crossover logic without written explanation.
• Complete the Rust hook skeleton in LittleBigMouse_Hook_Rust/Cargo.toml by adding dependencies (windows-rs or similar for low-level hooking) and a minimal runnable example. Include design doc on how it will interface with the C# side.: Rust component is declared but non-functional; unblock future contributors and clarify intent (replace C++ hook, run alongside, or experimental dead-end?).

The LittleBigMouse codebase shows moderate security posture with a C# multi-monitor management application featuring Windows Native API integration. Primary risks stem from low-level Windows API usage requiring elevated privileges, potential EDID/configuration parsing vulnerabilities, and external tool integration (Argyll CMS). The Rust hook component is minimal with no dependencies. No hardcoded secrets detected. Main recommendations: implement strict input validation for device configuration data, add dependency scanning for future packages, establish vulnerability disclosure policy, and remove IDE configuration from version control. The application's requirement for system-level mouse and monitor control inherently carries privilege escalation risk that requires careful API usage and code hardening.

• Medium · Rust Dependency Management - Empty Dependencies — Dependencies/Cargo.toml. The Rust package (LittleBigMouse_Hook_Rust) has no declared dependencies in Cargo.toml. While this reduces attack surface, it suggests the project may be in early development or incomplete. Future dependencies should be carefully vetted and kept up-to-date to avoid known vulnerabilities. Fix: Implement dependency scanning tools (cargo-audit, dependabot) to monitor for vulnerabilities when dependencies are added. Maintain a Software Bill of Materials (SBOM) and regularly update dependencies.
• Medium · Native Windows API Calls - Potential Privilege Escalation Risk — HLab.Sys/HLab.Sys.Windows.Monitors/, LittleBigMouse.Core/. The codebase extensively uses Windows Native APIs (indicated by NativeMethods.txt, WinApiExtensions.cs, DisplayChangeMonitor.cs). Mouse control and monitor enumeration at low levels could be exploited if input validation is insufficient. The application requires elevated privileges to function, increasing risk profile. Fix: Implement strict input validation for all Windows API calls. Run code analysis with tools like BinSkim. Apply principle of least privilege - request only necessary permissions. Consider code signing and manifest requirements.
• Medium · Unvalidated Display Configuration Parsing — HLab.Sys/HLab.Sys.Windows.Monitors/Edid.cs, HLab.Sys/HLab.Sys.Windows.MonitorVcp/LevelParser.cs, HLab.Sys/HLab.Sys.Argyll/IniFile.cs. Files like Edid.cs, LevelParser.cs, and IniFile.cs parse external device configuration data (EDID, INI files, VCP levels). Malformed or malicious EDID data from compromised monitors could cause buffer overflows or arbitrary code execution if not properly validated. Fix: Implement strict bounds checking and size validation for all parsed data. Use safe parsing libraries. Implement fuzzing tests for EDID and configuration file parsing. Add length limits and type validation.
• Low · Argyll CMS External Tool Integration — HLab.Sys/HLab.Sys.Argyll/ArgyllProbe.cs. ArgyllProbe.cs integrates with external Argyll CMS tool. If the tool path is not properly validated or the tool is vulnerable, it could be exploited. Process output is parsed without apparent validation. Fix: Validate the Argyll CMS tool binary path and hash before execution. Implement output validation and error handling. Consider running the tool in a sandboxed process with minimal privileges.
• Low · Missing Security Headers and Configuration — Repository root. No evidence of security configuration files (.github/SECURITY.md, security policy, CONTRIBUTING.md with security guidelines). The .gitattributes and .gitignore should be verified to ensure no secrets are accidentally committed. Fix: Add SECURITY.md with vulnerability disclosure policy. Review .gitignore for secrets patterns (*.key, .pem, .env). Implement pre-commit hooks to scan for secrets. Consider CODEOWNERS for security-sensitive files.
• Low · Third-Party IDE Configuration Committed — .idea/ directory structure. The .idea/ directory (JetBrains IDE) is committed to the repository. This can expose local configuration, potentially sensitive information about development environment, and create unnecessary noise in version control. Fix: Add .idea/ to .gitignore. Remove from git history using: git rm -r --cached .idea && git commit -m 'Remove IDE config'. Document IDE setup in CONTRIBUTING.md instead.

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.