claude-desktop/README.md

# Claude Desktop

Nativer AI-Desktop-Assistent fuer Linux. Schneller und maechtiger als Codium + Claude Code Extension.

**Tech-Stack:** Tauri 2.0 (Rust) + SvelteKit 5 + Claude Agent SDK (Node.js)
**Codebase:** ~24.000 Zeilen, 154 Commits, 27 Svelte-Komponenten, 18 Rust-Module

---

## Schnellstart

```bash
# Development (Hot-Reload)
cd "/mnt/17 - Entwicklungen/20 - Projekte/ClaudeDesktop"
CARGO_TARGET_DIR=/tmp/claude-desktop-target nix-shell --run "npx tauri dev"

# Produktion (AppImage)
CARGO_TARGET_DIR=/tmp/claude-desktop-target nix-shell --run "npx tauri build -- --bundles appimage"

# CI: Commit mit [appimage] im Message → Forgejo Runner baut + uploaded automatisch
```

---

## Architektur

```
┌──────────────────────────────────────────────────────────┐
│                    SvelteKit Frontend                     │
│  27 Svelte-Komponenten (Chat, Voice, Guard-Rails, ...)   │
├──────────────────────────────────────────────────────────┤
│                      Tauri IPC                           │
├──────────────────────────────────────────────────────────┤
│                    Rust Backend                           │
│  18 Module (claude.rs, db.rs, guard.rs, voice.rs, ...)   │
├──────────────────────┬───────────────────────────────────┤
│  SQLite (lokal)      │  Unix Domain Socket / stdio       │
│  Sessions, Settings  │         ↕                         │
│  Memory, Audit       │  Claude Bridge (Node.js)          │
│  Offline-Queue       │  @anthropic-ai/claude-agent-sdk   │
├──────────────────────┤         ↕                         │
│  MySQL (claude-db)   │  Claude API (Anthropic)           │
│  Wissensbasis        │  + MCP-Server (6 Stueck)          │
└──────────────────────┴───────────────────────────────────┘
```

### Datenfluss

1. **User** → Eingabe im ChatPanel (Text/Sprache/File-Drop)
2. **Frontend** → `invoke('send_message')` via Tauri IPC
3. **Rust** → Sticky Context + KB-Hints laden, an Bridge senden
4. **Bridge** → `query()` mit Claude Agent SDK, Events streamen
5. **Claude API** → Antwort + Tool-Calls (Bash, Read, Edit, MCP, ...)
6. **Bridge** → Events via JSON-Lines an Rust zurueck
7. **Rust** → `emit()` Events ans Frontend
8. **Frontend** → Live-Rendering (Text, Tools, Subagents)

### Bridge-Modi

| Modus | Beschreibung | Wann |
|-------|-------------|------|
| **UDS-Daemon** | Bridge als eigenstaendiger Prozess, ueberlebt App-Neustart | Standard (bevorzugt) |
| **stdio** | Bridge als Child-Process mit stdin/stdout | Fallback wenn UDS fehlschlaegt |

Socket-Pfad: `/tmp/claude-bridge.sock`, PID-File: `/tmp/claude-bridge.pid`

---

## Dateistruktur

### Rust Backend (`src-tauri/src/`)

| Datei | Zeilen | Funktion |
|-------|--------|----------|
| `lib.rs` | ~340 | App-Setup, Tray-Icon, Global Hotkey (Super+C), Plugin-Init |
| `claude.rs` | ~1000 | **Kernmodul**: Bridge-Kommunikation (UDS/stdio), MCP-Hub, Ollama, send_message |
| `db.rs` | ~800 | SQLite: Sessions, Messages, Settings, Projekte, Monitor-Events, Fehler-Tracking |
| `knowledge.rs` | ~1000 | MySQL-Wissensbasis: Suche, Cache (60s TTL), KB-Hints, Smart Hints v2 |
| `session.rs` | ~300 | Session-CRUD, Offline-Queue (queue/flush/clear) |
| `guard.rs` | ~250 | Guard-Rails: Safe/Moderate/Critical/Blocked, Permissions |
| `memory.rs` | ~200 | Persistentes Gedaechtnis: Auto-Load, Patterns, Cross-Session |
| `context.rs` | ~300 | 3-Schichten Context: Sticky/Projekt/Hints, Render fuer Prompt |
| `voice.rs` | ~355 | Whisper STT + Piper TTS (5 deutsche Stimmen), offline |
| `hooks.rs` | ~200 | Hook-System: SessionStart, PreToolUse, PostToolUse |
| `audit.rs` | ~150 | Audit-Log: Alle Aktionen mit Timestamp + Risk-Level |
| `programs.rs` | ~300 | D-Bus Aktionen, Screenshot-Capture, Xvfb |
| `ide.rs` | ~200 | VSCodium-Extension Bridge (WebSocket Port 7890) |
| `clipboard.rs` | ~150 | Clipboard-Watch: Code/URL/Fehler erkennen |
| `teaching.rs` | ~150 | Praesentations-/Schulungsmodus (separates Fenster) |
| `chat_window.rs` | ~100 | Chat-Detach: Separates Fenster herausloesen/zurueckholen |
| `update.rs` | ~250 | Auto-Updater: Forgejo Package Registry, Lock-Datei |
| `commands.rs` | ~100 | Slash-Command Registry (scannt ~/.claude/commands/) |

### Frontend (`src/lib/components/`)

| Komponente | Funktion |
|-----------|----------|
| `ChatPanel.svelte` | **Hauptkomponente**: Nachrichtenliste, Eingabe, File-Drop, Modus-Indikator |
| `SessionList.svelte` | Sidebar: Sessions, Projekt-Wechsel, Suche |
| `ActivityPanel.svelte` | Live-Aktivitaet: Tool-Calls, Agent-Status |
| `AgentView.svelte` | Subagent-Hierarchie als Baumansicht |
| `MonitorPanel.svelte` | System-Monitor: API/Tool/Error Events |
| `PerformancePanel.svelte` | Token-/Kosten-Statistiken |
| `GuardRailsPanel.svelte` | 3-Tab: Live-Feed / Regeln / Blockiert |
| `VoicePanel.svelte` | Push-to-Talk, Gespraechsmodus, TTS-Wiedergabe |
| `ContextPanel.svelte` | Sticky Context anzeigen/editieren |
| `MemoryPanel.svelte` | Persistentes Gedaechtnis CRUD |
| `KnowledgePanel.svelte` | Wissensbasis durchsuchen |
| `HooksPanel.svelte` | Hook-Verwaltung |
| `SettingsPanel.svelte` | VS-Code-artiges Settings mit Suche/Kategorien |
| `ProgramsPanel.svelte` | D-Bus Aktionen, Screenshot, Xvfb |
| `IdePanel.svelte` | VSCodium-Verbindung Status |
| `AuditLog.svelte` | Audit-Eintraege durchsuchen |
| `QuickActions.svelte` | Ctrl+K Kommandopalette |
| `CommandPalette.svelte` | Slash-Command Autocomplete (/-Eingabe) |
| `CodeBlock.svelte` | Syntax-Highlighting + Copy-Button |
| `DiffView.svelte` | Diff-Anzeige fuer Code-Aenderungen |
| `MermaidDiagram.svelte` | Mermaid-Diagramme rendern |
| `StopButton.svelte` | Abbruch-Button waehrend Agent laeuft |
| `UpdateDialog.svelte` | Auto-Update Bestaetigungsdialog |
| `FilePreview.svelte` | Datei-Vorschau (Text/Bild) |
| `AnimatedCode.svelte` | Code-Tipp-Animation fuer Praesentation |
| `AutoCorrectionModal.svelte` | Fehler-Pattern Vorschlag |

### Bridge (`scripts/claude-bridge.js`)

~1100 Zeilen Node.js. Zentrale Datei fuer die Claude-Kommunikation:

- **query()** via `@anthropic-ai/claude-agent-sdk` — streamt Events
- **Multi-Agent-Modi**: Solo / Handlanger (Haiku-Worker) / Experten (4 spezialisierte Agents) / Auto
- **Subagent-Tracking**: Map mit toolUseId → agentId/type/depth
- **MCP-Server Injection**: Configs von Rust empfangen, in queryOptions injizieren
- **Ollama-Integration**: Auto-Detect beim Start, local-query fuer einfache Tasks
- **Auto-Retry**: 3x Backoff bei Rate-Limit/5xx/Netzwerkfehler
- **Session-Resume**: Stale Session-ID → automatisch neue Session starten
- **UDS-Server-Modus**: `--socket /tmp/claude-bridge.sock` fuer Daemon-Betrieb

### Stores (`src/lib/stores/`)

| Store | Inhalt |
|-------|--------|
| `app.ts` | activeSession, activeProject, agentMode, chatDetached, processingPhase |
| `events.ts` | Event-Handler fuer alle Bridge-Events (text, result, tool-start/end, ...) |
| `updateTrigger.ts` | Reactive Trigger fuer Panel-Updates |

---

## Features komplett

### Phase 1-2 (v0.1.0 — 14.04.2026)
- Tauri 2.0 + SvelteKit 5 Grundgeruest
- 4-Panel Layout, Claude Bridge (stdio), Guard-Rails
- SQLite + Session-Management, Claude-DB Integration
- 3-Schichten Context, Multi-Agent-Modi, Hook-System
- VSCodium-Extension, Programm-Steuerung (D-Bus, Xvfb)
- Praesentationsmodus, System-Monitor, Subagent-Hierarchie
- Auto-Updater, Slash-Commands, KB-Hints, Error-Patterns

### Phase 3: Performance (22.04.2026)
- KB-Cache (RAM, 60s TTL), Bridge Warm-Start, Lazy Panel-Load
- Session-Resume Fix, Auto-Retry (3x Backoff), Heartbeat
- FIFO Message Queue, **Bridge-Daemon** (UDS), **Unix Socket IPC**

### Phase 4: Codium-Killer Features
- Projekt-Wechsel (Ein-Klick), **MCP-Hub nativ** (6 Server)
- Guard-Rails UI (3 Tabs), Persistent Memory, Quick-Actions (Ctrl+K)
- Voice (Whisper + Piper, offline), Settings-Panel, Chat-Detach
- Aktivitaets-Phasen (Denkt/Streamt/Tool/Subagent)

### Phase 5: Lokale KI + Offline
- Whisper.cpp + Piper-TTS (komplett offline, 5 deutsche Stimmen)
- **Ollama-Integration** (Auto-Detect, local-query)
- **Offline-Queue** (SQLite, flush bei Reconnect)

### Phase 6: Desktop-Integration
- D-Bus Actions (10 Aktionen), Clipboard-Watch, File-Drop
- Screenshot-Analyse, Global Hotkey (Super+C)

---

## MCP-Server (6 Stueck, automatisch geladen)

| Name | Funktion | Transport |
|------|----------|-----------|
| `forgejo` | Git: Repos, Issues, PRs, Releases | stdio |
| `claude-db` | MySQL Wissensbasis: Suche, CRUD | SSE (MCP-Hub) |
| `playwright` | Browser-Automatisierung | stdio |
| `context7` | Library-Dokumentation | stdio |
| `portainer` | Docker-Container-Management | stdio |
| `homeassistant` | Smart-Home Steuerung | stdio |

Configs in `~/.claude.json` → werden beim Bridge-Start automatisch injiziert.

---

## CI/CD

**Workflow:** `.forgejo/workflows/build-appimage.yml`
**Runner:** `16-Forgejo-Runner-AppImage` (Debian Bookworm)
**Trigger:** `[appimage]` in Commit-Message auf `main`

1. Commit mit `[appimage]` → Push
2. Forgejo Runner baut AppImage (~8-10 Min)
3. Upload in Forgejo Package Registry
4. Ntfy-Notification (Topic: `vk-builds`)
5. App zieht Update beim naechsten Start (Auto-Updater)

**NixOS:** AppImage hat WebKit2GTK/Mesa ABI-Konflikt → lokaler Build mit `shell.nix` noetig. Nix-Wrapper in `~/.local/bin/claude-desktop`.

---

## Tastenkuerzel

| Kuerzel | Aktion |
|---------|--------|
| `Super+C` | Claude-Eingabe von ueberall oeffnen |
| `Ctrl+K` | Quick-Actions Palette |
| `Ctrl+Enter` | Nachricht senden |
| `Escape` | Quick-Actions/Autocomplete schliessen |
| `/` | Slash-Command Autocomplete |

---

## Wissensbasis-Referenzen

| KB-ID | Thema |
|-------|-------|
| #248 | Tauri 2.0 + SvelteKit auf NixOS shell.nix |
| #311 | CI/CD Pipeline (Workflow-Tricks) |
| #371 | Debian Forgejo-Runner Setup |
| #381 | NixOS WebKit2GTK EGL-Crash |
| #382 | Cargo auf SMB → CARGO_TARGET_DIR |
| #384 | Custom-AppRun + linuxdeploy-Hook |

---

## Nicht geplant

- Multi-User / Team-Features
- Cloud-Sync
- Plugin-System (overkill fuer 1-User-App)
- Electron-Port (Tauri bleibt)