AGENTS.md · diff
git:20260505.5f883ea to git:20260704.3e37969
43 added, 61 removed. Audit A to A.
What this update changes in the checks
No check changed: every fixed check gives the same answer before and after this update.
A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.
- # AGENTS.md
-
- This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.
-
- ## Project Overview
-
- WhisperM8 is a native macOS menu bar application for speech-to-text transcription using AI providers (OpenAI Whisper, Groq). Built with Swift 5.9 and SwiftUI, targeting macOS 14+ (Sonoma).
+ # AGENTS.md — Konventionen für Codex-Agenten in WhisperM8
- ## Build Commands
+ WhisperM8 ist eine native macOS-App (Swift 5.9, SwiftUI, macOS 14+, pure
+ SwiftPM — kein .xcodeproj) mit zwei Hälften: Diktat-Pipeline (Hotkey →
+ Whisper/Groq → optional Codex-Nachbearbeitung) und Agent Chats
+ (Session-Manager für Claude Code und Codex CLI: PTY-Terminals,
+ Background-Agents, Subagent-Jobs). Ausführliche Architektur-Doku: `CLAUDE.md`.
- ```bash
- make dev # Recommended: clean build, install to /Applications, launch
- make build # Release build only (creates local .app)
- make run # Quick debug build for rapid iteration
- make install # Build + install to /Applications
- make dmg # Create distributable DMG
- make clean # Clean build artifacts
- make clean-apps # Remove all app bundles (fixes Spotlight duplicates)
- make clean-install # Full reset (removes all app data + reinstall)
- make kill # Kill running instances
- ```
+ ## Sprache & Stil
- For development, always use `make dev` to avoid duplicate app versions in Spotlight.
+ - **Code-Kommentare auf Deutsch** — Repo-Konvention, auch für neue Dateien.
+ - Commit-Messages: Conventional Commits mit deutschem Beschreibungstext,
+ z.B. `feat(overlay): Kern-Waveform mit alter Dynamik` oder
+ `fix(agent-chats): Hooks als alleinige Statusquelle`.
+ - Kommentare erklären das **Warum** (Constraints, Gotchas), nicht das Was.
- ## Debugging
+ ## Bauen & Testen
- View live logs:
```bash
- log stream --predicate 'subsystem == "com.whisperm8.app"' --level debug
- ```
-
- ## Architecture
-
- The app follows a unidirectional data flow pattern:
-
- ```
- Hotkey Event → AppState → AudioRecorder/TranscriptionService → UI Update
+ export DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer # Pflicht (SwiftUI-Makros)
+ swift build # Debug-Build
+ swift test # volle Suite
+ swift test --filter <TestKlasse> # gezielt
```
- ### Key Components
-
- - **WhisperM8App.swift** - Entry point, sets up MenuBarExtra, Settings/Onboarding windows, and global hotkey listeners
- - **Models/AppState.swift** - Central `@Observable` state managing recording lifecycle, transcription coordination, and clipboard operations
- - **Models/TranscriptionProvider.swift** - Provider/model enums with settings migration logic
- - **Services/AudioRecorder.swift** - AVAudioEngine-based recording with real-time audio levels, outputs M4A (16kHz mono AAC)
- - **Services/TranscriptionService.swift** - Protocol-based API clients for OpenAI and Groq transcription endpoints
- - **Services/AudioDuckingManager.swift** - Reduces system volume during recording (see [docs/AUDIO_DUCKING.md](docs/AUDIO_DUCKING.md))
- - **Windows/RecordingPanel.swift** - Non-activating NSPanel overlay with OverlayController managing lifecycle
- - **Services/KeychainManager.swift** - Secure API key storage using macOS Keychain
-
- ### Recording Flow
-
- 1. Hotkey press → `AppState.startRecording()` → AudioRecorder starts, overlay panel appears
- 2. Audio captured via AVAudioEngine tap with RMS level calculation
- 3. Hotkey release → `AppState.stopRecording()` → Recording stops, audio sent to transcription API
- 4. Result copied to clipboard, optionally auto-pasted via CGEvent to previously active app
+ - Als headless Agent NICHT `make dev`/`make run` starten (öffnet die GUI,
+ braucht TCC-Permissions).
+ - Vor dem Committen: `swift test` muss komplett grün sein.
- ### LSUIElement Considerations
+ ## Test-Konventionen
- The app runs as a menu bar-only application (LSUIElement=true). This causes focus issues with text fields in windows. The workaround is temporarily switching to `.regular` activation policy when Settings/Onboarding windows appear.
+ - Dependency Injection über einfache Closures und kleine Protokolle
+ (`commandResolver: { _ in "/pfad" }`, `ProcessRunner`-Spies) — **kein**
+ DI-Framework.
+ - Tests thematisch gesplittet in `Tests/WhisperM8Tests/`; geteilte Helpers
+ in `AgentTestSupport.swift`.
+ - Pure Logik wird unit-getestet; SwiftUI-/NSEvent-Interaktionen sind
+ manuelle QA — keine UI-Tests erfinden.
- ## Dependencies
+ ## Architektur-Leitplanken (Auswahl)
- Managed via Swift Package Manager (Package.swift):
- - **KeyboardShortcuts** (1.16.1) - Global hotkey detection
- - **Defaults** (8.2.0) - Type-safe UserDefaults
- - **LaunchAtLogin-Modern** (1.1.0) - Launch at startup
- - **ISSoundAdditions** (2.0.0) - System volume control for audio ducking
+ - `Services/` ist dreigeteilt: `Dictation/`, `AgentChats/`, `Shared/` —
+ neue Dateien in den passenden Ordner (SwiftPM entdeckt rekursiv).
+ - Subprozesse NIE mit dem rohen ProcessInfo-Environment spawnen — immer
+ `LoginShellEnvironment.shared.processEnvironment()` +
+ `AgentCommandBuilder.commandPath(_:)` (GUI-PATH ist minimal).
+ - `AgentWorkspaceStore`-Mutation-Closures dürfen keine Subprozesse und kein
+ blockierendes I/O ausführen (NSLock-serialisiert) — alles vorberechnen.
+ - Alles unter `~/.claude/` und `~/.codex/` ist extern und read-only.
+ - Neue Bundle-Ressourcen brauchen Package.swift UND Makefile (`_bundle`) —
+ besser: kleine Ressourcen als Swift-String-Konstanten einbetten.
+ - Große Views/Services nicht aufblähen: thematische `extension`-Dateien
+ (`AgentChatsView+<Thema>.swift`) sind das etablierte Muster.
- ## Build Environment
+ ## Debugging
- Requires Xcode toolchain for SwiftUI Preview macro support:
```bash
- export DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer
+ log stream --predicate 'subsystem == "com.whisperm8.app"' --level debug
```
-
- The Makefile sets this automatically.