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/seerge/g-helper 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 — Solo project — review before adopting

• Last commit today
• GPL-3.0 licensed
• CI configured
• ⚠ Solo or near-solo (1 contributor active in recent commits)
• ⚠ GPL-3.0 is copyleft — check downstream compatibility
• ⚠ 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 seerge/g-helper repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/seerge/g-helper.

What it runs against: a local clone of seerge/g-helper — 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 seerge/g-helper | 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 ≤ 30 days ago | Catches sudden abandonment since generation |

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "seerge/g-helper(\\.git)?\\b" \\
  && ok "origin remote is seerge/g-helper" \\
  || miss "origin remote is not seerge/g-helper (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 "app/GHelper.csproj" \\
  && ok "app/GHelper.csproj" \\
  || miss "missing critical file: app/GHelper.csproj"
test -f "app/HardwareControl.cs" \\
  && ok "app/HardwareControl.cs" \\
  || miss "missing critical file: app/HardwareControl.cs"
test -f "app/Helpers/AsusService.cs" \\
  && ok "app/Helpers/AsusService.cs" \\
  || miss "missing critical file: app/Helpers/AsusService.cs"
test -f "app/Mode/Modes.cs" \\
  && ok "app/Mode/Modes.cs" \\
  || miss "missing critical file: app/Mode/Modes.cs"
test -f "app/AnimeMatrix/AnimeMatrixDevice.cs" \\
  && ok "app/AnimeMatrix/AnimeMatrixDevice.cs" \\
  || miss "missing critical file: app/AnimeMatrix/AnimeMatrixDevice.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 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
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/seerge/g-helper"
  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).

G-Helper is a lightweight C# Windows application that replaces Asus's Armoury Crate bloatware with a minimal (~1.2M LOC) alternative offering fan control, power profiles, display settings, keyboard backlighting, and hardware monitoring for Asus ROG, TUF, ProArt, and Vivobook laptops. It communicates directly with ASUS ACPI interfaces, USB devices (AnimeMatrix LED displays), and native Windows APIs (CCD, AMD/Intel display drivers) to achieve near-feature-parity with the official tool at a fraction of the system cost. Monolithic WinForms desktop app (GHelper.sln in /app/): feature modules organized by hardware subsystem—/Fan/, /Display/, /Battery/, /Ally/, /AnimeMatrix/—each with Control and Device classes. Core ACPI access via AsusACPI.cs, USB via /AnimeMatrix/Communication/Platform/ abstraction. Configuration persisted through AppConfig.cs. No explicit separation of UI from logic; all modules inherit from Control or are service classes.

Power users and developers with Asus gaming/workstation laptops who want granular control over fan curves, power states, and RGB peripherals without the resource overhead of Armoury Crate. Also appeals to maintainers building system utilities for Windows hardware abstraction.

Highly mature and production-ready: 1,199k LOC in C#, thousands of GitHub stars, active release pipeline (build.yml, release.yml, CodeQL scanning), established multi-language docs (Chinese, Japanese, Czech translations in /docs/), and SLSA3 attestations. Recent activity visible via published releases and CI workflows. Single maintainer (seerge) but stable enough for daily driver use across 10+ laptop models.

Moderate risk from single-maintainer status and direct hardware I/O dependency: any Windows driver update or ASUS firmware change could silently break fan control or LED communication without immediate notice. No visible test suite in the file list (no Tests/ directory). AnimeMatrix USB communication via WindowsUsbProvider.cs is model-specific and fragile. GitHub Issues suggest ongoing device compatibility requests, indicating incomplete hardware coverage.

Actively maintained with release workflow (release.yml) pushing builds and periodic feature additions. GitHub Issues show ongoing requests for new device support (peripherals_request.yml template exists), display profile improvements, and fan curve refinement. No specific PR data visible, but CODE_OF_CONDUCT.md and CONTRIBUTING.md suggest organized contribution guidelines.

Clone with git clone https://github.com/seerge/g-helper.git, open app/GHelper.sln in Visual Studio 2022+ (C# project), restore NuGet packages (implicit), and build the solution. No npm or external CLI tooling required—native Windows desktop app. Run the built exe directly after compilation.

Daily commands: Build in Visual Studio, then run GHelper.exe from the output bin directory. No dev server—it's a standalone executable. For development, open the .sln in Visual Studio, hit F5 to launch with debugger attached.

• app/GHelper.csproj — Project file defining all dependencies, build configuration, and target framework—essential for understanding build setup and adding new features.
• app/HardwareControl.cs — Core orchestrator for all hardware interactions (fans, GPU, power modes, battery)—every contributor must understand this to modify device control logic.
• app/Helpers/AsusService.cs — Primary interface to ASUS-specific system services and ACPI calls—critical for adding support for new hardware features.
• app/Mode/Modes.cs — Power mode enumeration and mode-switching logic—foundation for understanding how performance profiles are managed.
• app/AnimeMatrix/AnimeMatrixDevice.cs — USB-based AnimatrixDevice communication abstraction—essential for understanding peripheral device protocol patterns.
• app/Display/ScreenControl.cs — Display brightness and color profile orchestration layer—shows how hardware abstraction integrates multiple backends.

Add Support for a New ASUS Laptop Model

1. Identify the model's ASUS device ID (ACPI path or USB VID:PID) by examining existing device patterns in AsusACPI.cs and other model-specific device definitions. (app/AsusACPI.cs)
2. If the model uses a new peripheral (e.g., AnimatrixDevice or mouse), create a new device class in the appropriate Peripherals folder (e.g., app/Peripherals/Mouse/Models/NewMouse.cs) inheriting from IPeripheral. (app/Peripherals/IPeripheral.cs)
3. Add model-specific control logic in HardwareControl.cs to initialize and route hardware calls to the new device type. (app/HardwareControl.cs)
4. Register the new model in AppConfig.cs device detection logic and create corresponding UI controls (if needed) in a new .cs form file. (app/AppConfig.cs)
5. Test via AsusService.cs integration to ensure ACPI method calls and thermal monitoring work with the new model. (app/Helpers/AsusService.cs)

Add a New Hardware Control Feature (e.g., Fan Curve)

1. Define the hardware abstraction interface (if new) or extend an existing control class. For fan curves, check FanSensorControl.cs structure. (app/Fan/FanSensorControl.cs)
2. Implement the control logic using AsusService.cs to invoke the appropriate ACPI method or WMI call. (app/Helpers/AsusService.cs)
3. Register the new control method in HardwareControl.cs so it is initialized and callable from the main application. (app/HardwareControl.cs)
4. Create or update a Windows Forms UI component (e.g., Fans.cs or Extra.cs) to expose the control to the user. (app/Fans.cs)
5. Add configuration persistence in AppConfig.cs so settings are saved and restored on application restart. (app/AppConfig.cs)

Add Support for a New Mouse or Peripheral Device

1. Create a new class in app/Peripherals/Mouse/Models (e.g., NewMouse.cs) that extends AsusMouse.cs or implements IPeripheral. (app/Peripherals/Mouse/AsusMouse.cs)
2. Define the USB VID:PID identifiers and implement device discovery in the new mouse class constructor. (app/AnimeMatrix/Communication/Platform/WindowsUsbProvider.cs)
3. Implement protocol commands for the device (e.g., DPI settings, button remapping) using the USB communication pattern from AnimeMatrixDevice.cs. (app/AnimeMatrix/AnimeMatrixDevice.cs)
4. Add initialization and control calls to HardwareControl.cs so the new device is detected and controlled. (app/HardwareControl.cs)
5. Create or update the mouse settings UI (AsusMouseSettings.cs) to expose new device controls to users. (app/AsusMouseSettings.cs)

• C# Windows Forms (.NET Framework) — Lightweight, native Windows integration for ACPI/WMI calls; no external runtime required; direct hardware API access via P/Invoke.
• ACPI & WMI — Standard Windows firmware interfaces for ASUS-specific device control (thermal management, power modes, GPU switching).
• USB HID (via WindowsUsbProvider) — Cross-platform peripheral communication for AnimatrixDevice, mice, and handheld devices without requiring custom drivers.
• Global keyboard hook (SetWindowsHookEx) — Enables hotkey detection for quick fan/mode/display switching without requiring focus.
• NVIDIA NVML & AMD ADL — Vendor-native GPU APIs for performance monitoring and discrete GPU enable/disable without relying on vendor bloatware.

• Monolithic HardwareControl vs. modular service architecture

  • Why: Single entry point simplifies initialization and reduces inter-component complexity for a single-window application.
  • Consequence: HardwareControl.cs can become large; adding features requires careful coordination. Easier to understand flow but harder to test in isolation.

• Windows Forms instead of WPF or modern .NET

  • Why: Lighter memory footprint, faster startup, minimal dependencies—critical for a background utility application.
  • Consequence: Reduced modern UI capabilities but smaller binary and lower system resource usage aligns with 'lightweight' design goal.

• Direct ACPI method invocation vs. abstraction layer

  • Why: ASUS devices have diverse ACPI implementations; direct inv
  • Consequence: undefined

No explicit NuGet dependencies visible in file list—may use implicit .NET Framework libs (WMI, P/Invoke). Windows 10/11 only; no cross-platform abstraction. ACPI access requires admin privileges at runtime (likely prompted on first launch). USB communication via WindowsUsbProvider assumes WinUSB driver installed for custom VID/PID devices. Fan curve validation and thermal protection logic buried in Fans.cs—no documented firmware safety limits. Display CCD API requires GPU driver support (AMD/Intel-specific code paths); may fail silently on some integrated graphics. Single-threaded UI with blocking hardware calls = potential UI freeze on slow devices.

• Windows ACPI via WMI (Embedded Controller) — G-Helper reads/writes Asus firmware fan tables and power limits through ACPI methods exposed by Embedded Controller—understanding ACPI namespaces and WMI class instantiation is core to hacking fan curves or power profiles
• P/Invoke and Native Interop — Display brightness control (ScreenBrightness.cs), USB device enumeration (WindowsUsbProvider.cs), and ACPI access all use P/Invoke to call Win32 APIs—critical for hardware communication in .NET WinForms
• USB HID Protocol and Packet Framing — AnimeMatrix LED communication (Communication/Packet.cs, Device.cs) requires constructing USB control transfers with precise opcode/checksum structure—firmware-level protocol understanding needed for adding new RGB devices
• Windows Color Correction and CCD API — Display color profiles and refresh rate switching (ScreenNative.cs, ScreenCCD.cs) use Windows CCD (Color Correction Driver) API to interact with GPU drivers—understanding CCD enables custom color profile support
• Thermal Throttling and Fan Curve Interpolation — FanSensorControl.cs and Fans.cs implement piecewise-linear fan speed interpolation based on CPU/GPU temps—knowledge of thermal design and hysteresis prevents oscillation and ensures sustained performance
• Model-Specific Hardware Abstraction — G-Helper supports 10+ Asus laptop SKU families with different ACPI register offsets, USB device IDs, and sensor mappings—the codebase lacks a device detection registry, making hardware additions a manual reverse-engineering effort
• WinForms Control Inheritance and Event-Driven Architecture — Each subsystem (Fans.cs, ScreenControl.cs, BatteryControl.cs) inherits from WinForms Control or acts as a service class—understanding event routing and UI state synchronization is essential for adding new tabs or fixing race conditions

• asus-linux/asusctl — Linux equivalent providing identical Asus hardware control (fans, power, RGB) via command-line and systemd—reference for ACPI register mappings across models
• mastercomfig/comfig — Community-maintained Asus ROG peripheral configuration tool overlapping with G-Helper's keyboard/mouse macro support
• iAmWerewolf/Asus-Keyboard-Config — Dedicated ASUS keyboard macro and lighting management—complements G-Helper's RGB support for TUF/ROG keyboards
• seerge/g-helper-web — Official companion web dashboard and documentation for G-Helper settings/guides (if exists as separate repo)

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 GPU control modules (NVidia and AMD)

The GPU control system has two separate implementations (app/Gpu/NVidia/NvidiaGpuControl.cs and app/Gpu/AMD/AmdGpuControl.cs) that are critical for laptop performance management, but there are no visible test files in the repo. Adding unit tests would catch regressions when modifying GPU switching logic, especially important given the complexity of NvBootState and AmdAdl2 interop.

• [ ] Create app/Gpu/Tests/ directory structure
• [ ] Add unit tests for NvidiaGpuControl.cs covering boot state detection and GPU switching scenarios
• [ ] Add unit tests for AmdGpuControl.cs covering ADL2 initialization and mode switching
• [ ] Add IGpuControl.cs interface tests to ensure both implementations conform to expected behavior
• [ ] Integrate tests into .github/workflows/build.yml to run on every PR

Extract Fan/Battery/Display control common patterns into shared base classes

The codebase has parallel control modules (app/Fan/FanSensorControl.cs, app/Battery/BatteryControl.cs, app/Display/ScreenControl.cs, app/AnimeMatrix/AniMatrixControl.cs) that likely share initialization, error handling, and state management patterns. Extracting these into base classes would reduce duplication and make maintenance easier across 50+ control modules.

• [ ] Analyze common patterns in FanSensorControl.cs, BatteryControl.cs, ScreenControl.cs, and AnimeMatrix controls
• [ ] Create app/Helpers/BaseDeviceControl.cs with shared lifecycle methods (Initialize, Update, Cleanup)
• [ ] Refactor at least 3 existing control classes to inherit from BaseDeviceControl
• [ ] Document the pattern in CONTRIBUTING.md with code examples
• [ ] Ensure all tests still pass in build.yml workflow

Add integration tests for ACPI/WMI communication layer (AsusACPI.cs)

AsusACPI.cs is a critical bridge to laptop hardware but lacks visible tests. Given the variety of supported laptop models (ROG, TUF, Flow, Vivobook, etc.), integration tests using mocked ACPI responses would prevent regressions when supporting new device variants and catch compatibility issues early.

• [ ] Create app/Tests/AsusAcpiIntegrationTests.cs with mocked WMI responses
• [ ] Add test cases for common ACPI method calls (fan control, lighting, power profiles) with different return values
• [ ] Add test coverage for error scenarios (unavailable methods, invalid parameters)
• [ ] Create app/Tests/Mocks/MockWmiProvider.cs to simulate different laptop firmware responses
• [ ] Document supported ACPI methods in /docs/ACPI_REFERENCE.md for future contributors
• [ ] Add integration tests to separate CI workflow (.github/workflows/integration-tests.yml)

• Add unit tests for AppConfig.cs serialization/deserialization (JSON round-trip validation)—currently no test directory exists, pick a simple config scenario (fan curve with 5 points) and write XUnit tests.
• Extend Display/ColorProfileHelper.cs documentation and add missing ICC profile validation for edge cases (sRGB vs DCI-P3 switching on AMD vs Intel)—examine existing code comments and add explicit examples in /docs/.
• Create a device compatibility matrix document (CSV or Markdown table in /docs/) mapping laptop model SKUs to tested fan table offsets, USB device IDs, and known display driver quirks—scrape GitHub Issues for model reports.

The G-Helper application shows moderate security posture. Key concerns include: (1) Direct USB communication without visible encryption or validation, (2) External process execution via ProcessHelper that may be vulnerable to injection, (3) System-level registry and ACPI access with unclear input validation, and (4) Potential unencrypted storage of sensitive configuration. The application demonstrates good practices with SLSA3 compliance and security policy documentation. Recommendations: implement comprehensive input validation across all external interactions, secure USB packet communication, add configuration encryption, and enhance logging sanitization. No obvious hardcoded secrets or credentials detected in file structure. Overall, the application requires security hardening in process execution, system-level API calls, and data protection mechanisms.

• Medium · Use of ProcessHelper for External Command Execution — app/Helpers/ProcessHelper.cs. The presence of ProcessHelper.cs suggests the application executes external processes. Without visible input validation in the file structure, there's a risk of command injection if user input is passed to process execution functions without proper sanitization. Fix: Ensure all external process calls use parameterized execution (separate arguments from command), validate and sanitize all user inputs before passing to ProcessHelper, and use allowlists for executable names.
• Medium · RestrictedProcessHelper May Bypass Security Restrictions — app/Helpers/RestrictedProcessHelper.cs. The RestrictedProcessHelper.cs file name suggests an attempt to handle restricted processes, but the implementation details are unknown. There may be potential security bypasses or elevation of privilege vulnerabilities. Fix: Review the implementation to ensure proper permission checks, use Windows API securely, avoid running processes with elevated privileges unnecessarily, and implement comprehensive access control lists.
• Medium · Potential Insecure USB Device Communication — app/AnimeMatrix/Communication/Platform/WindowsUsbProvider.cs, app/AnimeMatrix/Communication/Packet.cs. The application communicates with USB devices (AnimeMatrix/Communication/Platform/WindowsUsbProvider.cs). Direct USB communication can be vulnerable to packet interception, injection, or manipulation if not properly secured. Fix: Implement packet validation and checksums, use secure communication protocols, validate all USB responses before processing, implement timeout mechanisms, and consider using established secure communication standards.
• Medium · Registry Access via AsusACPI.cs — app/AsusACPI.cs. Direct ACPI and Windows registry access (AsusACPI.cs) without visible input validation could allow unauthorized system configuration changes if user input reaches these functions. Fix: Implement strict input validation for all ACPI calls, use only hardcoded or allowlisted registry paths, validate all parameters before system calls, and implement proper error handling.
• Low · Potential Information Disclosure via Logger — app/Helpers/Logger.cs. Logger.cs may log sensitive information such as system paths, configuration values, or user preferences without redaction, potentially exposing sensitive data. Fix: Implement log sanitization to remove sensitive data (paths, credentials, personal information), set appropriate file permissions on log files, implement log rotation, and consider using secure logging levels.
• Low · Dynamic Lighting and Input Handling Security — app/Helpers/DynamicLightingHelper.cs, app/Input/KeyboardHook.cs, app/Input/InputDispatcher.cs. DynamicLightingHelper.cs and input handling components (KeyboardHook.cs, InputDispatcher.cs) involve system-level input/output which could be exploited if not properly validated. Fix: Validate all input from keyboard hooks and input dispatchers, implement rate limiting on input processing, use secure inter-process communication, and follow Windows API security best practices.
• Low · Unencrypted Configuration Storage — app/AppConfig.cs, app/App.config. AppConfig.cs stores application configuration. If sensitive settings are stored in plain text without encryption, user preferences and system settings could be compromised. Fix: Encrypt sensitive configuration values using DPAPI (Data Protection API), store credentials securely, restrict file permissions on config files, and validate all loaded configuration values.

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.