Skip to content

AGENTS.md

Latest commit

 

History

History
86 lines (65 loc) · 3.6 KB

AGENTS.md

File metadata and controls

86 lines (65 loc) · 3.6 KB
Raw

Agent Guide

This file gives coding agents the short version of how to work safely in QontrolPanel.

Project Summary

QontrolPanel is a Windows tray application for audio, media, display, power, shortcut, and headset controls. It is built with Qt 6, C++20, QML, CMake, MSVC, vcpkg, hidapi, and a vendored HeadsetControl library.

Read these docs before larger changes:

  • docs/ARCHITECTURE.md
  • docs/BUILD.md
  • docs/HID_DEVICES.md
  • docs/HEADSETCONTROL_INTEGRATION.md

Important Paths

  • src/: C++ implementations.
  • include/: C++ headers and QML-facing singleton declarations.
  • qml/: QML UI.
  • qml/Common/: reusable QML controls.
  • qml/SettingsPane/: settings pages.
  • qml/Singletons/: QML-only singletons.
  • resources/: icons, sounds, resource files.
  • i18n/: Qt translation source files.
  • dependencies/headsetcontrol/: vendored HeadsetControl dependency.
  • cmake/: project CMake helpers.
  • tools/: installer and release support.

Coding Guidance

  • Follow existing Qt naming, signal, slot, and singleton patterns.
  • Keep Windows API details in C++ managers and bridges.
  • Keep QML focused on presentation and binding to bridge properties.
  • Do not block the UI thread with device enumeration, monitor brightness work, HID polling, network calls, or slow Windows API calls.
  • Prefer adding behavior to an existing bridge/manager when it belongs to that domain.
  • Use Qt models for list data shown in QML.
  • Update UserSettings consistently when adding settings: property, getter, setter, signal, member, defaults, load, save, and QML binding.
  • Update translations when adding user-visible strings.
  • Keep log messages in a stable untranslated form; do not pass LOG_* or LogManager message text through tr() or qsTr().
  • Keep HeadsetControl protocol/device work inside dependencies/headsetcontrol unless the change is only QontrolPanel orchestration or UI.

Build Commands

Typical Windows build:

git submodule update --init --recursive
C:\vcpkg\vcpkg install hidapi:x64-windows getopt-win32:x64-windows
cmake -S . -B build -DCMAKE_TOOLCHAIN_FILE=C:/vcpkg/scripts/buildsystems/vcpkg.cmake
cmake --build build --config Release
cmake --install build --config Release

Qt Creator with the MSVC 2022 64-bit kit is also a supported path.

Validation

When possible, validate changes with:

  • a CMake configure;
  • a Release build;
  • manual launch from Qt Creator or the installed output;
  • affected settings pane interaction;
  • real-device validation for audio, HID, display, hotkey, or power behavior.

For documentation-only changes, spelling, links, and consistency with CMakeLists.txt and existing source files are the main checks.

Risk Areas

  • Windows COM/WMI lifetime in monitor code.
  • Hotkey registration and native event filtering.
  • Audio session/device enumeration.
  • Headset HID writes and polling intervals.
  • Single-instance behavior through QLocalServer.
  • Translation generation changing .ts files during builds.
  • Installer and release workflow assumptions.

Repository Hygiene

  • Do not rewrite unrelated files.
  • Preserve existing line endings when editing human-authored files; this is a Windows app and line-ending churn makes focused reviews harder. Do not normalize generated files unless the task explicitly asks for it.
  • Do not update the HeadsetControl submodule unless the task explicitly asks for it.
  • Keep dependency and generated-file churn out of focused code changes.
  • When updating translations, edit only the .ts files in i18n/; .qm files are generated by CI.
  • Mention any validation that could not be run locally, especially because this app targets Windows.