claude-desktop/CLAUDE.md

Claude Desktop

Native Tauri-2.0-Desktop-App die Claude Code/Agent SDK als Backend nutzt. Sprach-Interface, Live-Aktivität, Guard-Rails. Eigenes Pendant zur VSCodium-Sidebar mit voller Kontrolle über das System.

Detail-Übersicht + Status: README.md. Phasen-Stand: ROADMAP.md.

Tech-Stack

• Backend: Rust 2021, Tauri 2 (tauri = "2" mit tray-icon-Feature), tokio, mysql_async, rusqlite, reqwest
• Frontend: SvelteKit 2, Svelte 5, TypeScript, Vite 5, paneforge (Multi-Pane-Layout)
• AI: @anthropic-ai/claude-agent-sdk + @anthropic-ai/claude-code
• Sprache: Whisper (STT lokal), TTS Cloud-Streaming
• DB: claude-DB (MySQL 192.168.155.11 claude) für Wissensbasis, SQLite lokal für Sessions/Persistenz
• Build: NixOS-Dev-Shell (shell.nix), Forgejo CI für AppImage

Wichtige Pfade

• Rust-Module: src-tauri/src/ — 16 Module (main.rs, lib.rs, claude.rs, db.rs, guard.rs, voice.rs, hooks.rs, ide.rs, …)
• UI-Komponenten: src/lib/components/ — 24 Panels
• Routes: src/routes/ (+layout.svelte, +page.svelte, presentation/+page.svelte)
• VS-Code-Extension: vscode-extension/ (Bridge auf WebSocket-Port 7890)
• Workflow: .forgejo/workflows/build-appimage.yml
• Dev-Shell: shell.nix
• Tauri-Config: src-tauri/tauri.conf.json, src-tauri/Cargo.toml

Build & Run

Native Dev (Hot-Reload)

nix-shell shell.nix --run 'npm ci && npm run tauri:dev'

Native Production-Build (NixOS — Pflicht-Weg auf NixOS!)

# Cargo-target NICHT auf SMB-Mount! → I/O-Errors. Lokales tmpfs nutzen:
CARGO_TARGET_DIR=/tmp/claude-target \
  nix-shell shell.nix --run 'npm run tauri build -- --bundles appimage'
# Bundling kann mit pkg-config-Bug crashen — Binary unter
# /tmp/claude-target/release/claude-desktop ist trotzdem fertig & startbar:
nix-shell shell.nix --run /tmp/claude-target/release/claude-desktop

CI-Build via Forgejo Actions

Commit mit [appimage] in der Message → Build auf 16-Forgejo-Runner-AppImage (Debian) → Upload in Package-Registry. Triggert auch bei Tag-Push v*.

NixOS-Spezialfall — AppImage funktioniert NICHT

Das vom CI gebaute AppImage hat auf NixOS einen WebKit2GTK ↔ Mesa ABI-Konflikt (EGL_BAD_PARAMETER im WebKitWebProcess). Keine Kombination aus WEBKIT_DISABLE_DMABUF_RENDERER / _COMPOSITING_MODE / _SANDBOX_THIS_IS_DANGEROUS / GDK_BACKEND=x11 / LIBGL_ALWAYS_SOFTWARE löst es. Workarounds erschöpft → immer nativ bauen via shell.nix. Vollständige Diagnose: KB-Eintrag #381.

Auf Debian/Ubuntu/Fedora/Arch funktioniert das AppImage problemlos.

Konventionen

• Sprache: Deutsch in Code-Kommentaren, README, CHANGELOG, Commit-Messages, UI-Strings
• Modell-Defaults: Sonnet 4.6 für normale Tasks, Opus für Komplex, Haiku für Routineanfragen — UI-Auswahl im Footer
• Guard-Rails: alle System-Aktionen über guard.rs klassifizieren (Safe / Moderate / Critical / Blocked) — siehe src-tauri/src/guard.rs
• Audit: jede Tool-Ausführung landet im Audit-Log (audit.rs → SQLite + UI-Panel)
• Sessions: persistent in SQLite, restartbar
• Bridge zur VSCodium-Extension: Port 7890, einfaches WebSocket-Protokoll, in ide.rs definiert

Workflow-Eigenheiten (CI/CD)

Beim Anpassen von .forgejo/workflows/build-appimage.yml nicht vergessen:

• AppImage-Filename hat Leerzeichen → vor Upload tr ' ' '-' (curl-URL-Bug)
• Vor jedem Upload DELETE auf latest/ UND VERSION/ (Forgejo wirft 409 Conflict bei PUT auf existing)
• Custom-AppRun muss apprun-hooks/linuxdeploy-plugin-gtk.sh sourcen + AppRun.wrapped aufrufen, sonst finden WebKit-Subprozesse ihre Helpers nicht (KB #384)
• Re-Bundle nach AppRun-Patch mit appimagetool --no-appstream
• Ntfy-Notifications inline (nicht via data/ntfy-action, weil das Repo cross-org ist — für data-it/*-Repos siehe KB #220 für vollständige URL-Variante)

Wissensbasis (Claude-DB)

Bei spezifischen Bug-Themen vorab mysql_search_knowledge mit Schlüsselwort:

Thema	KB-ID
Pipeline-Übersicht	#311
Debian-Runner Setup	#371
libssl-dev / openssl-sys	#372
NixOS WebKit-EGL-Crash	#381
Cargo auf SMB → CARGO_TARGET_DIR	#382
Custom-AppRun + linuxdeploy-Hook	#384
Bluetooth 5.2 ≠ LE Audio	#385
Tauri shell.nix-Vorlage	#248
Forgejo Package-Registry 409	#161
Ntfy-Pattern (cross-org URL)	#190/#191/#220

Häufige Befehle

# Build-Status checken
curl -sS -u "token:<forgejo-token>" \
  'https://git.data-it-solution.de/api/v1/repos/data/claude-desktop/actions/tasks?limit=3' | jq

# AppImage frisch ziehen (Standard-Linux)
rm -f ~/Applications/Claude-Desktop.AppImage
curl -sSL -o ~/Applications/Claude-Desktop.AppImage \
  -u "token:<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

# Native NixOS-Start (nach einmaligem Build)
nix-shell shell.nix --run /tmp/claude-target/release/claude-desktop

# Build-Logs aus Forgejo-Container ziehen (bei Failure)
ssh unraid "docker cp 18-Forgejo:\$(docker exec 18-Forgejo find /data/gitea/actions_log/data/claude-desktop -name '<RUN_ID>.log.zst' | head -1) /tmp/build.log.zst"
ssh unraid "zstd -d -c /tmp/build.log.zst" | tail -100