# Claude Desktop — Nativer AI-Assistent

Eigenständige Desktop-Anwendung die Claude Code als Backend nutzt, mit nativem UI, Live-Übersicht und kontrolliertem OS-Zugriff.

## Status (Stand 2026-04-20)

**Variante A (Native Desktop-App) ist umgesetzt** — Tauri 2.0 + SvelteKit 5, Phase 1-13 fertig (siehe [ROADMAP.md](ROADMAP.md)). Variante B (autonome VM) bleibt Vision.

Was läuft:
- 4-Panel-Layout, 24 UI-Komponenten (Chat, Activity, Memory, Audit, Knowledge, Voice, Hooks, IDE, Programs, Performance, Settings, …)
- 16 Rust-Backend-Module (`claude.rs`, `db.rs`, `guard.rs`, `memory.rs`, `voice.rs`, `hooks.rs`, `ide.rs`, …)
- Sprach-Interface mit Push-to-Talk (`VoicePanel`), Whisper STT
- Modell-Auswahl Haiku/Sonnet/Opus, Token-/Kosten-Anzeige
- Subagent-Hierarchie, Multi-Agent-Modi, Hook-System
- Session-Persistenz (SQLite), Audit-Log
- VS-Code-Extension `claude-desktop-bridge` (steuert VSCodium aus der App heraus, WebSocket-Port 7890)
- CI/CD-Pipeline (Forgejo Actions) → AppImage in Package-Registry

## Installation

### AppImage (Debian/Ubuntu/Fedora/Arch — **nicht NixOS**)

```bash
mkdir -p ~/Applications
curl -sSL -o ~/Applications/Claude-Desktop.AppImage \
  -u "token:<dein-forgejo-token>" \
  'https://git.data-it-solution.de/api/packages/data/generic/claude-desktop/latest/Claude-Desktop_0.1.0_amd64.AppImage'
chmod +x ~/Applications/Claude-Desktop.AppImage
~/Applications/Claude-Desktop.AppImage
```

Auf NixOS hat das AppImage einen WebKit2GTK ↔ Mesa ABI-Konflikt → siehe nächster Abschnitt.

### NixOS — nativer Build (Pflicht)

Das AppImage läuft auf NixOS nicht (KB-Eintrag #381 zur Diagnose). Stattdessen lokal bauen mit der mitgelieferten `shell.nix`:

```bash
cd "/mnt/17 - Entwicklungen/20 - Projekte/ClaudeDesktop"

# Cargo-Target auf lokales tmpfs (SMB-Mount macht Cargo-Build-Errors)
CARGO_TARGET_DIR=/tmp/claude-target \
  nix-shell shell.nix --run 'npm ci && npm run tauri build -- --bundles appimage'

# Tauri-Bundling kann an pkg-config-Bug scheitern — Binary reicht aber:
nix-shell shell.nix --run /tmp/claude-target/release/claude-desktop
```

Permanenter Wrapper:

```bash
cat > ~/.local/bin/claude-desktop <<'EOF'
#!/usr/bin/env bash
cd "/mnt/17 - Entwicklungen/20 - Projekte/ClaudeDesktop"
exec nix-shell shell.nix --run /tmp/claude-target/release/claude-desktop
EOF
chmod +x ~/.local/bin/claude-desktop
```

### Development

```bash
cd "/mnt/17 - Entwicklungen/20 - Projekte/ClaudeDesktop"
nix-shell shell.nix --run 'npm ci && npm run tauri:dev'   # mit Hot-Reload
```

## CI/CD-Pipeline

Workflow: `.forgejo/workflows/build-appimage.yml`

| Trigger | Was passiert |
|---|---|
| Push auf `main` mit `[appimage]` in Commit-Message | AppImage bauen + in Package-Registry hochladen |
| Push eines Tags `v*` | zusätzlich als Release-Asset anhängen |

**Runner:** `16-Forgejo-Runner-AppImage` (Debian Bookworm, glibc, mit linuxdeploy + appimagetool + Tauri-Build-Stack vorinstalliert). Der Standard-Alpine-Runner kann Tauri-AppImages nicht bauen (musl-Inkompatibilität von linuxdeploy). Setup des Runners: KB-Eintrag #371.

**Workflow-Eigenheiten** (gut zu wissen wenn was ändern):
- AppImage-Filename mit Leerzeichen (`Claude Desktop_…`) wird vor Upload zu `Claude-Desktop_…` umbenannt (curl-URL-Bug)
- Vor jedem Upload werden alte Versionen gelöscht (Forgejo Package-Registry weist PUT auf existierenden Pfad mit HTTP 409 ab)
- Custom-AppRun mit NixOS-Detection wird nach `tauri build` eingesetzt + mit `appimagetool` re-bundled. Der Hook `apprun-hooks/linuxdeploy-plugin-gtk.sh` darf dabei nicht überschrieben werden (KB #384), sonst finden WebKit-Subprozesse ihre Helpers nicht
- Ntfy-Notifications (Build-Start/Success/Failure) — Topic `vk-builds`

Ntfy-Setup für andere Projekte: KB #190/#191/#220.

## VS-Code-Extension `claude-desktop-bridge`

Eigenes Subprojekt unter [vscode-extension/](vscode-extension/). Ermöglicht Claude Desktop, VSCodium fernzusteuern (Datei öffnen, Cursor-Position setzen, Terminal-Befehle absetzen) über einen WebSocket-Server (Port 7890 default).

```bash
cd vscode-extension
npm ci && npm run compile
# Verpacktes vsix: claude-desktop-bridge-0.1.0.vsix
codium --install-extension claude-desktop-bridge-0.1.0.vsix
```

Befehle in VSCodium: `Claude Desktop: Verbindung starten/beenden`. Die App meldet sich beim Start automatisch.

## Projektstruktur (Stand)

```
ClaudeDesktop/
├── src-tauri/src/        # 16 Rust-Module
│   ├── main.rs           # Entry (setzt WEBKIT_DISABLE_*-Defaults für Linux)
│   ├── lib.rs            # Tauri-App-Setup
│   ├── claude.rs         # Claude Agent SDK Integration
│   ├── db.rs             # MySQL (claude-DB) + SQLite-Persistierung
│   ├── guard.rs          # Guard-Rails (Critical/Moderate/Safe)
│   ├── hooks.rs          # Hook-System
│   ├── memory.rs         # Memory/Knowledge-Graph
│   ├── voice.rs          # Whisper STT + Voice-Activity-Detection
│   ├── ide.rs            # Bridge zur VSCodium-Extension
│   ├── audit.rs, knowledge.rs, programs.rs, session.rs,
│   │   teaching.rs, update.rs, context.rs
│   └── ...
├── src/                  # SvelteKit Frontend
│   ├── routes/+layout.svelte
│   ├── routes/+page.svelte
│   ├── routes/presentation/+page.svelte
│   └── lib/components/   # 24 UI-Panels
├── vscode-extension/     # VSCodium-Bridge
├── .forgejo/workflows/   # CI/CD
├── shell.nix             # NixOS Dev-Shell
├── ROADMAP.md            # Phase-Status
├── TEST-ROADMAP.md       # Test-Plan
├── tools.yaml            # MCP-Tool-Inventar
└── package.json
```

## Wissensbasis-Referenzen (für künftige Sessions)

| KB-ID | Thema |
|---|---|
| #311 | Diese Pipeline (Workflow-Tricks) |
| #371 | Debian Forgejo-Runner Setup |
| #372 | libssl-dev für openssl-sys |
| #381 | NixOS WebKit2GTK EGL-Crash → native build |
| #382 | Cargo auf SMB → CARGO_TARGET_DIR umleiten |
| #384 | Custom-AppRun + linuxdeploy-Hook |
| #248 | Tauri 2.0 + SvelteKit auf NixOS shell.nix |

---

## Motivation

Claude Code in VSCodium funktioniert, hat aber Grenzen:
- Sidebar-Chat ist eng, keine eigene Fensterverwaltung
- Kein Überblick was Claude gerade tut (Dateien, Befehle, DB-Queries)
- Kein "Stopp"-Button bei laufenden Aktionen
- Keine Präsentations-Ansicht für Ergebnisse
- Keine native OS-Integration (Fenster steuern, Programme öffnen)

## Vision

### Variante A: Native Desktop-App (begleitend)

Claude arbeitet begleitend — der User sieht alles mit und kann jederzeit eingreifen.

```
┌─────────────────────────────────────────────────────┐
│ Claude Desktop                               [─][□][×]│
├──────────────┬──────────────────────────────────────┤
│              │                                      │
│  💬 Chat     │  📋 Live-Aktivität                    │
│              │                                      │
│  Du: Fixe    │  ▶ Lese product/price.php:1609       │
│  den Bug in  │  ▶ Grep "addMoreActions" in 3 Files  │
│  der Preis-  │  ▶ Edit actions_produktkarte.class.php│
│  seite       │  ✓ Deploy nach /var/www/dolibarr/... │
│              │                                      │
│  Claude:     │  ⚠ Will deployen auf PROD            │
│  Gefunden,   │    [Erlauben] [Ablehnen]             │
│  der Hook... │                                      │
│              ├──────────────────────────────────────┤
│              │  📊 Ergebnis-Präsentation             │
│              │                                      │
│              │  Vorher: list=0 (unsichtbar)         │
│              │  Nachher: list=3 (auf Karte)         │
│              │                                      │
│              │  [Diff anzeigen] [Screenshot]        │
│              │                                      │
├──────────────┴──────────────────────────────────────┤
│  [⏹ STOPP]  CPU: 2%  │  DB: claude  │  Git: main   │
└─────────────────────────────────────────────────────┘
```

**Kernfeatures:**
- **Chat-Panel** — Aufgaben eingeben, Antworten lesen
- **Live-Aktivität** — Echtzeit was Claude tut (Dateien, Befehle, Queries)
- **Kritische Aktionen** — Popup bei Prod-Deploy, DB-Änderungen, Git Push
- **Präsentations-View** — Nach einer Aufgabe: Vorher/Nachher, Diffs, Screenshots
- **STOPP-Button** — Sofort alles abbrechen
- **Statusleiste** — Aktive DB, Git-Branch, CPU/RAM

**Technologie-Stack:**
- **Tauri 2.0** (Rust + WebView) — native App, ~5 MB statt 200 MB Electron
- **SvelteKit** — Frontend (gleiche Technologie wie Leckerbuch, VDE Katalog)
- **Claude Code SDK** (`@anthropic-ai/claude-code`) — AI-Backend
- **Claude DB** — Direkte MySQL-Anbindung (kein REST-Umweg)
- **MCP-Tools** — Docker, Forgejo, Wissensbasis

### Variante B: Autonome VM (selbständig arbeitend)

Claude hat einen eigenen Rechner (VM) mit Desktop und arbeitet Aufgaben selbständig ab. Der User überwacht remote.

```
┌──────────────────────────────────────────┐
│  Unraid Server                           │
│                                          │
│  ┌────────────────────────────────────┐  │
│  │  VM: Claude Agent                  │  │
│  │                                    │  │
│  │  ┌──────────┐  ┌───────────────┐  │  │
│  │  │ Desktop  │  │ Claude Agent  │  │  │
│  │  │ (XFCE)   │←→│ Computer Use  │  │  │
│  │  │          │  │ Terminal      │  │  │
│  │  │ Dolibarr │  │ Claude DB     │  │  │
│  │  │ Browser  │  │ MCP Tools     │  │  │
│  │  │ IDE      │  │ Git/Forgejo   │  │  │
│  │  └──────────┘  └───────────────┘  │  │
│  │       ↕                           │  │
│  │   VNC/noVNC (Port 6080)           │  │
│  └────────────────────────────────────┘  │
│                                          │
│  Netzwerk: ISOLIERT von Prod!            │
│  - Eigenes VLAN / Bridge                 │
│  - Zugriff nur auf Test-DB               │
│  - Kein SSH zu Unraid                    │
│  - Kein Zugriff auf Prod-Dolibarr        │
└──────────────────────────────────────────┘
         ↕
  Eddy (Browser → VNC)
  Sieht Claude arbeiten
  Kann jederzeit eingreifen
```

**Wie Claude Computer Use funktioniert:**
1. Claude bekommt einen Screenshot des Desktops
2. Claude analysiert was er sieht
3. Claude sendet Maus-/Tastatur-Befehle
4. Nächster Screenshot → nächste Aktion
5. Kann jedes Programm bedienen das ein Mensch bedienen kann

**Sicherheitskonzept für die VM:**
- **Netzwerk-Isolation** — eigenes VLAN, kein Zugriff auf Prod-Server
- **Nur Test-DB** — dolibarr_test auf 192.168.155.11, nie Prod-DB
- **Kein SSH nach außen** — keine SSH-Keys zu Unraid oder anderen Servern
- **Snapshot-basiert** — VM-Snapshot vor jeder Aufgabe, Rollback bei Problemen
- **Audit-Log** — jeder Befehl, jede Aktion wird geloggt
- **Zeitlimit** — maximale Laufzeit pro Aufgabe
- **Kill-Switch** — ein Befehl stoppt alles sofort

**Use Cases für die VM:**
- Dolibarr-Module entwickeln und testen (Browser + Terminal)
- Automatische Code-Reviews über mehrere Repos
- Dokumentation erstellen mit Screenshots
- UI-Tests durchführen (Dolibarr durchklicken, Fehler finden)
- Batch-Aufgaben (alle Module updaten, Lang-Dateien synchronisieren)

## Empfehlung: Stufenweise vorgehen

### Stufe 1: Native Desktop-App (Variante A)
- Sofort umsetzbar mit vorhandenem Wissen (Svelte, Tauri)
- Claude arbeitet begleitend, User behält Kontrolle
- Ersetzt die VSCodium-Sidebar durch bessere UX
- Geschätzter Aufwand: 2-3 Wochen Grundgerüst

### Stufe 2: Autonome VM (Variante B) — später
- Erst wenn Stufe 1 stabil läuft und Vertrauen aufgebaut ist
- Guard-Rails und Audit-Log müssen wasserdicht sein
- Netzwerk-Isolation auf Unraid einrichten
- Geschätzter Aufwand: 1-2 Wochen Setup, dann iterativ

## Architektur — Variante A im Detail

### Projektstruktur
```
ClaudeDesktop/
├── src-tauri/           # Rust-Backend (Tauri)
│   ├── src/
│   │   ├── main.rs      # App-Einstiegspunkt
│   │   ├── claude.rs    # Claude SDK Integration
│   │   ├── db.rs        # Direkte MySQL-Anbindung
│   │   └── guard.rs     # Sicherheits-Regeln
│   ├── Cargo.toml
│   └── tauri.conf.json
├── src/                 # SvelteKit Frontend
│   ├── routes/
│   │   ├── +layout.svelte    # Haupt-Layout (Chat + Panels)
│   │   ├── chat/             # Chat-Ansicht
│   │   ├── activity/         # Live-Aktivität
│   │   ├── presentation/     # Ergebnis-Präsentation
│   │   └── settings/         # Einstellungen
│   ├── lib/
│   │   ├── claude-bridge.ts  # Kommunikation mit Tauri-Backend
│   │   ├── db.ts             # Claude-DB Queries
│   │   └── stores.ts         # Svelte Stores (State)
│   └── app.html
├── package.json
├── svelte.config.js
├── vite.config.ts
└── README.md
```

### Datenfluss
```
User-Eingabe (Chat)
       ↓
SvelteKit Frontend
       ↓ (Tauri IPC)
Rust Backend
       ↓
Claude Code SDK (Node.js child process)
       ↓
Claude API (Anthropic)
       ↓
Tool-Ausführung (Bash, Dateien, DB, MCP)
       ↓
Ergebnis zurück an Frontend
       ↓
Live-Aktivität + Präsentation anzeigen
```

### Claude-DB Integration
Statt REST-API (aktuell) → direkte MySQL-Verbindung im Rust-Backend:
```rust
// Direkte DB-Abfrage, kein MCP-Umweg
let results = db.query(
    "SELECT * FROM knowledge WHERE MATCH(title,content) AGAINST(? IN BOOLEAN MODE)",
    &[search_term]
).await?;
```
- Schneller (kein HTTP-Roundtrip)
- Keine Token-Limits bei großen Ergebnissen
- Full-Text-Search direkt in MySQL

### Guard-Rails im nativen Programm
```rust
enum ActionRisk {
    Safe,       // Dateien lesen, Code schreiben → automatisch
    Moderate,   // Git commit, lokaler Deploy → Statusbar-Hinweis
    Critical,   // Prod-Deploy, DB-Schema, Git Push → Popup + Bestätigung
    Blocked,    // rm -rf, force push main → hart blockiert
}
```

## Sprach-Interface — Reden mit Claude

### Konzept

Echtes Gespräch mit Claude — reden, unterbrechen, weiterreden. Kein "Aufnahme starten/stoppen", sondern natürlicher Dialog.

```
┌─────────────────────────────────────────────────┐
│                                                 │
│   🎤 Du sprichst                                │
│   ↓                                             │
│   Whisper (Speech-to-Text, lokal)               │
│   ↓                                             │
│   VAD erkennt: "User hat aufgehört zu reden"    │
│   ↓                                             │
│   Text → Claude API → Antwort-Text              │
│   ↓                                             │
│   TTS (Text-to-Speech) → Lautsprecher 🔊        │
│   ↓                                             │
│   Du unterbrichst → VAD erkennt Sprache         │
│   → TTS stoppt sofort                           │
│   → Whisper nimmt deine neue Eingabe auf        │
│   → Kreislauf beginnt von vorn                  │
│                                                 │
└─────────────────────────────────────────────────┘
```

### Technologie

| Komponente | Technologie | Läuft wo |
|---|---|---|
| **Speech-to-Text** | OpenAI Whisper (whisper.cpp) | Lokal auf NixOS, kein Cloud-Upload |
| **Voice Activity Detection** | Silero VAD oder WebRTC VAD | Lokal, erkennt Sprache vs. Stille |
| **Text-to-Speech** | OpenAI TTS API oder ElevenLabs | Cloud (Streaming) |
| **Interrupt-Erkennung** | VAD + sofortiger TTS-Stopp | Lokal |

### Gesprächs-Modi

**Freies Gespräch** — wie mit einem Kollegen reden:
- Du redest, Claude hört zu (Whisper transkribiert live)
- Pause > 1,5 Sekunden → Claude antwortet
- Du unterbrichst → Claude stoppt sofort, hört dir zu
- Claude kann nachfragen wenn etwas unklar ist

**Diktier-Modus** — Claude führt aus was du sagst:
- "Fixe den Bug in der Preisseite, der Umrechnungsfaktor wird nicht berücksichtigt"
- Claude arbeitet, kommentiert per Sprache was er tut
- Du kannst jederzeit "Stopp" oder "Warte mal" sagen

**Präsentations-Modus** — Claude erklärt was er gemacht hat:
- "Zeig mir was du geändert hast"
- Claude öffnet Diff-View und erklärt per Sprache die Änderungen
- Du kannst zwischenfragen: "Warum hast du das so gemacht?"

### Stimmen-Optionen

**OpenAI TTS API:**
- 6 Stimmen (alloy, echo, fable, onyx, nova, shimmer)
- Sehr natürlich, Streaming-fähig (~200ms Latenz)
- Kosten: ~$15 pro 1M Zeichen

**ElevenLabs:**
- Hunderte Stimmen, eigene Stimmen klonbar
- Noch natürlicher, emotionaler
- Deutsch-Support gut
- Kosten: ab $5/Monat (30 Min)

**Lokal (Piper TTS):**
- Kostenlos, keine Cloud
- Deutsche Stimmen verfügbar
- Qualität gut aber nicht so natürlich wie Cloud
- Keine Latenz durch Netzwerk

### Latenz-Budget (Ziel: < 2 Sekunden)

```
VAD erkennt Stille:        ~300ms
Whisper transkribiert:     ~500ms (lokal, whisper.cpp mit GPU)
Claude API Antwort:        ~800ms (erstes Token, Streaming)
TTS erstes Audio:          ~200ms (Streaming)
─────────────────────────────────
Gesamt bis erste Silbe:    ~1.800ms
```

Mit Streaming: Claude beginnt zu "reden" während er noch denkt — wie ein Mensch der anfängt zu antworten bevor der Gedanke fertig ist.

### Integration in die Desktop-App

```
┌─────────────────────────────────────────────────────┐
│ Claude Desktop                               [─][□][×]│
├──────────────┬──────────────────────────────────────┤
│              │                                      │
│  💬 Chat     │  📋 Live-Aktivität                    │
│              │                                      │
│  (Text wird  │  ▶ Lese product/price.php            │
│  live mit-   │  ▶ Edit actions_produktkarte.class.php│
│  geschrieben │  ✓ Deploy nach /var/www/dolibarr/... │
│  während     │                                      │
│  gesprochen) │                                      │
│              │                                      │
├──────────────┴──────────────────────────────────────┤
│  🎤 ████████░░░░░░  Zuhören...    [🔇 Stumm] [⏹]   │
└─────────────────────────────────────────────────────┘
```

- Mikrofon-Leiste unten zeigt Pegel
- Gesprochenes wird als Text im Chat mitgeschrieben (Transkript)
- Claudes Antwort wird gleichzeitig als Text angezeigt und vorgelesen
- Stumm-Taste schaltet Mikrofon aus (nur Text-Modus)

### Whisper lokal auf NixOS

```nix
# In configuration.nix
environment.systemPackages = with pkgs; [
  whisper-cpp          # C++ Port, schnell, CPU/GPU
  # oder
  openai-whisper       # Original Python, braucht mehr RAM
];
```

Whisper "small" oder "medium" Modell reicht für Deutsch — ~500 MB RAM, Echtzeit auf CPU.

## Voraussetzungen

### Für Variante A (Desktop-App)
- NixOS: `rustc`, `cargo`, `nodejs`, `tauri-cli` in der Nix-Config
- Anthropic API Key (bereits vorhanden)
- Claude Code SDK npm-Paket
- MySQL-Client-Library für Rust (`sqlx` oder `mysql_async`)

### Für Variante B (VM)
- Unraid: VM mit Linux + Desktop (Ubuntu/Debian + XFCE)
- VNC-Server in der VM
- noVNC-Container auf Unraid für Browser-Zugriff
- Isoliertes Netzwerk (VLAN oder Bridge)
- Claude API Key + Computer Use Beta-Zugang

## Offene Fragen

- [ ] Anthropic API Key Kosten für Computer Use (Screenshot-intensiv)?
- [ ] Tauri 2.0 auf NixOS — Nix-Paket verfügbar?
- [ ] Claude Code SDK — stabil genug für Production?
- [ ] VM auf Unraid — genug RAM/CPU frei?