First UI implementation (tray)

Author: n-n-code

.github/workflows/ci.yml

@@ -61,5 +61,15 @@ jobs:
       - name: Run tests
         run: ctest --test-dir build --output-on-failure
 
+      - name: Validate install tree
+        run: |
+          INSTALL_DIR="$(mktemp -d)"
+          cmake --install build --prefix "$INSTALL_DIR"
+          test -x "$INSTALL_DIR/bin/mutterkey"
+          test -x "$INSTALL_DIR/bin/mutterkey-tray"
+
       - name: Validate headless CLI startup
         run: QT_QPA_PLATFORM=offscreen ./build/mutterkey --help
+
+      - name: Validate headless tray startup
+        run: timeout 2s env QT_QPA_PLATFORM=offscreen ./build/mutterkey-tray

.github/workflows/release-checks.yml

@@ -50,5 +50,15 @@ jobs:
       - name: Run tests
         run: ctest --test-dir build --output-on-failure
 
+      - name: Validate install tree
+        run: |
+          INSTALL_DIR="$(mktemp -d)"
+          cmake --install build --prefix "$INSTALL_DIR"
+          test -x "$INSTALL_DIR/bin/mutterkey"
+          test -x "$INSTALL_DIR/bin/mutterkey-tray"
+
+      - name: Validate headless tray startup
+        run: timeout 2s env QT_QPA_PLATFORM=offscreen ./build/mutterkey-tray
+
       - name: Run Valgrind Memcheck lane
         run: bash scripts/run-valgrind.sh build

.gitignore

@@ -5,6 +5,7 @@
 /third_party/whisper.cpp/build/
 /third_party/whisper.cpp/build-*/
 /Makefile
+/next_feature/
 *.o
 *.obj
 *.moc

AGENTS.md

@@ -10,7 +10,7 @@ Current architecture:
 - Audio capture uses Qt Multimedia
 - Transcription is in-process through vendored `whisper.cpp`
 - Clipboard writes prefer `KSystemClipboard` with `QClipboard` fallback
-- There is no GUI yet; the entrypoint is the `mutterkey` binary with `daemon`, `once`, and `diagnose` modes
+- There is an early Qt Widgets tray shell in `mutterkey-tray`, but the daemon remains the product core
 - The recommended day-to-day runtime path is the `systemd --user` service
 - The installed desktop entry is intentionally hidden from normal app menus with `NoDisplay=true`
 - `daemon` is the default runtime mode; `once` and `diagnose` are validation helpers
@@ -36,9 +36,13 @@ This repository is intentionally kept minimal:
 - `src/transcription/transcriptionworker.*`: worker object hosted on a dedicated `QThread`
 - `src/transcription/transcriptiontypes.h`: normalized audio and transcription result value types
 - `src/config.*`: JSON config loading and defaults
+- `src/app/*`: shared CLI/runtime command helpers used by the main entrypoint
+- `src/control/*`: local daemon control transport, typed snapshots, and session/client APIs
+- `src/tray/*`: Qt Widgets tray-shell UI scaffolding
 - `contrib/mutterkey.service`: example user service
 - `contrib/org.mutterkey.mutterkey.desktop`: hidden desktop entry used for desktop identity/integration
 - `scripts/check-release-hygiene.sh`: repo hygiene checks for publication-facing content
+- `next_feature/`: tracked upcoming feature plans as Markdown; keep only plan `.md` files and the folder-local `.gitignore`
 - `docs/Doxyfile.in`: Doxygen config template for repo-owned API docs
 - `docs/mainpage.md`: Doxygen landing page used instead of the full README
 - `scripts/run-valgrind.sh`: deterministic Valgrind Memcheck runner for release-readiness checks
@@ -118,6 +122,7 @@ Notes:
 - Do not add broad Valgrind suppressions by default; only add narrow suppressions after reproducing stable third-party noise and keep them clearly scoped
 - When adding tests, prefer small `Qt Test` cases that run headlessly under `CTest` and avoid microphone, clipboard, or KDE session dependencies unless the task is specifically integration-focused
 - For tool-driven cleanups, preserve the existing design and behavior; do not perform broad rewrites just to satisfy style-oriented recommendations
+- Keep forward-looking feature plans under `next_feature/` as tracked Markdown files; do not leave scratch notes, binaries, or generated artifacts there
 
 ## Coding Guidelines
 
@@ -128,6 +133,8 @@ Notes:
 - Avoid introducing optional backends, plugin systems, or cross-platform abstractions unless the task requires them
 - Keep the audio path explicit: recorder output may not already match Whisper input requirements, so preserve normalization behavior
 - Prefer narrow shared value types across subsystems; for example, consumers that only need captured audio should include `src/audio/recording.h`, not the full recorder class
+- Keep JSON and other transport details at subsystem boundaries; prefer typed C++ snapshots/results once data crosses into app-owned control, tray, or service code
+- Prefer dependency injection for tray-shell and control-surface code from the first implementation so headless Qt tests stay simple
 - Preserve the current product direction: embedded `whisper.cpp`, KDE-first, CLI/service-first
 
 ## C++ Core Guidelines Priorities
@@ -193,10 +200,13 @@ Typical model location:
 
 - Read `README.md` first, especially `Overview`, `Quick Start`, `Run As Service`, and `Development`, then read the touched source files before editing
 - Prefer targeted changes over speculative cleanup
+- If a change grows daemon, tray, or control-plane behavior, prefer extracting or extending repo-owned libraries under `src/app/`, `src/control/`, or other focused modules instead of piling more orchestration into `src/main.cpp`
 - Update `README.md` and `config.example.json` when behavior or setup changes
 - Update `contrib/mutterkey.service` and `contrib/org.mutterkey.mutterkey.desktop` when service/desktop behavior changes
 - Update `LICENSE`, `THIRD_PARTY_NOTICES.md`, CMake install rules, and `third_party/whisper.cpp.UPSTREAM.md` when packaging, licensing, or vendored dependency behavior changes
 - Keep `README.md`, `AGENTS.md`, and any relevant local skills aligned with the current `scripts/update-whisper.sh` workflow when the vendor-update process changes
+- Store upcoming feature plans in `next_feature/` as Markdown files, and update the existing plan there when refining the same upcoming feature instead of scattering notes across the repo
+- Treat `mutterkey-tray` as a shipped artifact once it is installed or validated in CI; keep install rules, README/setup notes, release checklist items, and workflow checks aligned with that status
 - Verify with a fresh CMake build when the change affects compilation or linkage
 - Run `ctest` when touching covered code in `src/config.*` or `src/audio/recordingnormalizer.*`, and extend the deterministic headless tests when practical
 - Prefer expanding tests around pure parsing, value normalization, and other environment-independent logic before adding KDE-session or device-heavy coverage

CMakeLists.txt

@@ -21,12 +21,12 @@ option(MUTTERKEY_ENABLE_WHISPER_BLAS "Enable whisper.cpp BLAS CPU acceleration"
 set(MUTTERKEY_WHISPER_BLAS_VENDOR "Generic" CACHE STRING "BLAS vendor passed to whisper.cpp when BLAS acceleration is enabled")
 set_property(CACHE MUTTERKEY_WHISPER_BLAS_VENDOR PROPERTY STRINGS "Generic;OpenBLAS;FLAME;ATLAS;FlexiBLAS;Intel;NVHPC;Apple")
 
-find_package(Qt6 REQUIRED COMPONENTS Core Gui Multimedia)
+find_package(Qt6 REQUIRED COMPONENTS Core Gui Multimedia Network Widgets)
 find_package(KF6GlobalAccel CONFIG REQUIRED)
 find_package(KF6GuiAddons CONFIG REQUIRED)
 find_package(Doxygen QUIET)
 
-set(MUTTERKEY_APP_SOURCES
+set(MUTTERKEY_CORE_SOURCES
     src/audio/audiorecorder.cpp
     src/audio/audiorecorder.h
     src/audio/recordingnormalizer.cpp
@@ -40,7 +40,6 @@ set(MUTTERKEY_APP_SOURCES
     src/config.h
     src/hotkeymanager.cpp
     src/hotkeymanager.h
-    src/main.cpp
     src/service.cpp
     src/service.h
     src/transcription/transcriptiontypes.h
@@ -50,14 +49,52 @@ set(MUTTERKEY_APP_SOURCES
     src/transcription/whispercpptranscriber.h
 )
 
-add_executable(mutterkey ${MUTTERKEY_APP_SOURCES})
+set(MUTTERKEY_CONTROL_SOURCES
+    src/control/daemoncontrolclient.cpp
+    src/control/daemoncontrolclient.h
+    src/control/daemoncontrolprotocol.cpp
+    src/control/daemoncontrolprotocol.h
+    src/control/daemoncontrolserver.cpp
+    src/control/daemoncontrolserver.h
+    src/control/daemoncontroltypes.cpp
+    src/control/daemoncontroltypes.h
+)
+
+add_library(mutterkey_core STATIC ${MUTTERKEY_CORE_SOURCES})
+add_library(mutterkey_control STATIC ${MUTTERKEY_CONTROL_SOURCES})
+add_library(mutterkey_app STATIC
+    src/app/applicationcommands.cpp
+    src/app/applicationcommands.h
+)
+
+add_executable(mutterkey
+    src/main.cpp
+)
+
+add_executable(mutterkey-tray
+    src/tray/traystatuswindow.cpp
+    src/tray/traystatuswindow.h
+    src/traymain.cpp
+)
 
+target_include_directories(mutterkey_core PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/src)
+target_include_directories(mutterkey_control PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/src)
+target_include_directories(mutterkey_app PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/src)
 target_include_directories(mutterkey PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/src)
-target_link_libraries(mutterkey PRIVATE Qt6::Core Qt6::Gui Qt6::Multimedia KF6::GlobalAccel KF6::GuiAddons)
+target_include_directories(mutterkey-tray PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/src)
+target_link_libraries(mutterkey_core PUBLIC Qt6::Core Qt6::Gui Qt6::Multimedia KF6::GlobalAccel KF6::GuiAddons)
+target_link_libraries(mutterkey_control PUBLIC Qt6::Core Qt6::Network mutterkey_core)
+target_link_libraries(mutterkey_app PUBLIC Qt6::Core Qt6::Gui mutterkey_control)
+target_link_libraries(mutterkey PRIVATE mutterkey_app whisper)
+target_link_libraries(mutterkey-tray PRIVATE Qt6::Core Qt6::Gui Qt6::Widgets mutterkey_control)
 set_target_properties(mutterkey PROPERTIES
     BUILD_RPATH "$ORIGIN/../lib"
     INSTALL_RPATH "$ORIGIN/../lib"
 )
+set_target_properties(mutterkey-tray PROPERTIES
+    BUILD_RPATH "$ORIGIN/../lib"
+    INSTALL_RPATH "$ORIGIN/../lib"
+)
 
 function(mutterkey_enable_sanitizers target_name)
     if(NOT CMAKE_CXX_COMPILER_ID MATCHES "GNU|Clang|AppleClang")
@@ -84,7 +121,11 @@ function(mutterkey_enable_sanitizers target_name)
     endif()
 endfunction()
 
+mutterkey_enable_sanitizers(mutterkey_core)
+mutterkey_enable_sanitizers(mutterkey_control)
+mutterkey_enable_sanitizers(mutterkey_app)
 mutterkey_enable_sanitizers(mutterkey)
+mutterkey_enable_sanitizers(mutterkey-tray)
 
 set(MUTTERKEY_CLAZY_CHECKS "level0" CACHE STRING "Checks passed to clazy-standalone")
 
@@ -163,9 +204,10 @@ add_subdirectory(third_party/whisper.cpp EXCLUDE_FROM_ALL)
 # upstream public headers as part of its own package layout.
 set_target_properties(whisper ggml PROPERTIES PUBLIC_HEADER "")
 
-target_link_libraries(mutterkey PRIVATE whisper)
+target_link_libraries(mutterkey_core PUBLIC whisper)
 
 install(TARGETS mutterkey RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR})
+install(TARGETS mutterkey-tray RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR})
 install(TARGETS whisper ggml ggml-base
     LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
 )

README.md

@@ -18,7 +18,7 @@ Current direction:
 - KDE-first
 - local-only transcription
 - CLI/service-first operation
-- no GUI yet
+- tray-shell work has started, but the daemon remains the product core
 - minimal and developer-oriented rather than a hardened end-user security product
 
 Recommended startup path:
@@ -46,7 +46,7 @@ Supported environment:
 
 Build requirements:
 
-1. Qt 6 development packages with `Core`, `Gui`, and `Multimedia`
+1. Qt 6 development packages with `Core`, `Gui`, `Multimedia`, `Network`, and `Widgets`
 2. KDE Frameworks development packages for `KGlobalAccel` and `KGuiAddons`
 3. `g++`
 4. `cmake`
@@ -107,6 +107,7 @@ cmake --install "$BUILD_DIR"
 This installs:
 
 - `~/.local/bin/mutterkey`
+- `~/.local/bin/mutterkey-tray`
 - `~/.local/lib/libwhisper.so*` and the required `ggml` libraries
 - `~/.local/share/applications/org.mutterkey.mutterkey.desktop`
 
@@ -353,6 +354,9 @@ Repository layout:
 - `src/transcription/transcriptiontypes.h`: normalized-audio and transcription result value types
 - `src/clipboardwriter.*`: clipboard writes with KDE-first fallback behavior
 - `src/config.*`: JSON config loading and defaults
+- `src/app/*`: shared CLI/runtime command helpers used by the main entrypoint
+- `src/control/*`: local daemon control protocol, typed snapshots, and local-socket session/server wiring
+- `src/tray/*`: Qt Widgets tray-shell UI scaffolding
 - `contrib/mutterkey.service`: example user service
 
 Build and test:

RELEASE_CHECKLIST.md

@@ -105,6 +105,15 @@ ctest --test-dir "$SANITIZER_BUILD_DIR" --output-on-failure
 QT_QPA_PLATFORM=offscreen "$BUILD_DIR/mutterkey" --help
 ```
 
+- Validate tray-shell startup in a headless environment:
+
+```bash
+timeout 2s env QT_QPA_PLATFORM=offscreen "$BUILD_DIR/mutterkey-tray"
+```
+
+- Treat exit code `124` from the tray-shell smoke check as expected when the
+  process stays alive until `timeout` stops it.
+
 - If the change affects startup, service wiring, or config handling, also run:
 
 ```bash
@@ -122,6 +131,7 @@ cmake --install "$BUILD_DIR" --prefix "$INSTALL_DIR"
 
 - Confirm the installed tree contains:
   - `bin/mutterkey`
+  - `bin/mutterkey-tray`
   - required `libwhisper` / `ggml` shared libraries
   - the desktop file under `share/applications`
   - license files under `share/licenses/mutterkey`

src/app/applicationcommands.cpp

@@ -0,0 +1,132 @@
+#include "app/applicationcommands.h"
+
+#include "audio/audiorecorder.h"
+#include "clipboardwriter.h"
+#include "control/daemoncontrolserver.h"
+#include "service.h"
+#include "transcription/whispercpptranscriber.h"
+
+#include <QGuiApplication>
+#include <QJsonDocument>
+#include <QTextStream>
+#include <QTimer>
+
+Q_LOGGING_CATEGORY(appLog, "mutterkey.app")
+
+void configureLogging(const QString &level)
+{
+    qSetMessagePattern(QStringLiteral("%{time yyyy-MM-dd hh:mm:ss.zzz} %{if-debug}DEBUG%{endif}%{if-info}INFO%{endif}%{if-warning}WARNING%{endif}%{if-critical}ERROR%{endif}%{if-fatal}FATAL%{endif} %{category}: %{message}"));
+
+    if (level.compare(QStringLiteral("DEBUG"), Qt::CaseInsensitive) == 0) {
+        QLoggingCategory::setFilterRules(QStringLiteral("*.debug=true"));
+    } else {
+        QLoggingCategory::setFilterRules(QStringLiteral("*.debug=false"));
+    }
+}
+
+int runDaemon(QGuiApplication &app, const AppConfig &config, const QString &configPath)
+{
+    MutterkeyService service(config, app.clipboard());
+    DaemonControlServer controlServer(configPath, config, &service);
+    QObject::connect(&app, &QCoreApplication::aboutToQuit, &service, &MutterkeyService::stop);
+    QObject::connect(&app, &QCoreApplication::aboutToQuit, &controlServer, &DaemonControlServer::stop);
+
+    QString errorMessage;
+    if (!service.start(&errorMessage)) {
+        qCCritical(appLog) << "Failed to start daemon:" << errorMessage;
+        return 1;
+    }
+    if (!controlServer.start(&errorMessage)) {
+        qCCritical(appLog) << "Failed to start daemon control server:" << errorMessage;
+        service.stop();
+        return 1;
+    }
+
+    qCInfo(appLog) << "Mutterkey daemon running. Hold" << config.shortcut.sequence << "to talk.";
+    return app.exec();
+}
+
+int runOnce(QGuiApplication &app, const AppConfig &config, double seconds)
+{
+    AudioRecorder recorder(config.audio);
+    WhisperCppTranscriber transcriber(config.transcriber);
+    ClipboardWriter clipboardWriter(app.clipboard());
+
+    if (config.transcriber.warmupOnStart) {
+        QString warmupError;
+        if (!transcriber.warmup(&warmupError)) {
+            qCCritical(appLog) << "Failed to warm up transcriber:" << warmupError;
+            return 1;
+        }
+    }
+
+    QTimer::singleShot(0, &app, [&app, &recorder, &transcriber, &clipboardWriter, seconds]() {
+        QString errorMessage;
+        if (!recorder.start(&errorMessage)) {
+            qCCritical(appLog) << "Failed to start one-shot recording:" << errorMessage;
+            app.exit(1);
+            return;
+        }
+
+        qCInfo(appLog) << "Recording for" << seconds << "seconds";
+        QTimer::singleShot(static_cast<int>(seconds * 1000), &app, [&app, &recorder, &transcriber, &clipboardWriter]() {
+            const Recording recording = recorder.stop();
+            if (!recording.isValid()) {
+                qCCritical(appLog) << "Recorder returned no audio";
+                app.exit(1);
+                return;
+            }
+
+            const TranscriptionResult result = transcriber.transcribe(recording);
+            if (!result.success) {
+                qCCritical(appLog) << "One-shot transcription failed:" << result.error;
+                app.exit(1);
+                return;
+            }
+
+            if (!result.text.trimmed().isEmpty()) {
+                const QString trimmedText = result.text.trimmed();
+                if (!clipboardWriter.copy(trimmedText)) {
+                    qCWarning(appLog) << "Clipboard update appears to have failed";
+                }
+                QTextStream(stdout) << trimmedText << Qt::endl;
+            } else {
+                qCInfo(appLog) << "No speech detected";
+            }
+            app.exit(0);
+        });
+    });
+
+    return app.exec();
+}
+
+int runDiagnose(QGuiApplication &app, const AppConfig &config, double seconds, bool invokeShortcut)
+{
+    MutterkeyService service(config, app.clipboard());
+    QObject::connect(&app, &QCoreApplication::aboutToQuit, &service, &MutterkeyService::stop);
+
+    QString errorMessage;
+    if (!service.start(&errorMessage)) {
+        qCCritical(appLog) << "Diagnostic startup failed:" << errorMessage;
+        return 1;
+    }
+
+    qCInfo(appLog) << "Diagnostic mode active for" << seconds << "seconds. Press the configured shortcut now.";
+    if (invokeShortcut) {
+        QTimer::singleShot(750, &app, [&service]() {
+            QString invokeError;
+            if (!service.invokeShortcut(&invokeError)) {
+                qCWarning(appLog) << "Diagnostic shortcut invoke failed:" << invokeError;
+            } else {
+                qCInfo(appLog) << "Invoked the registered shortcut through KGlobalAccel";
+            }
+        });
+    }
+
+    QTimer::singleShot(static_cast<int>(seconds * 1000), &app, [&app, &service]() {
+        QTextStream(stdout) << QJsonDocument(service.diagnostics()).toJson(QJsonDocument::Indented);
+        app.exit(0);
+    });
+
+    return app.exec();
+}