Architektur (Konzept)

Grobe Schichtung — bewusst noch kein Code, nur das mentale Modell. Reihenfolge nach Doku-zuerst: erst hier verstehen, dann in app/ bauen.

Engine: Claude Agent SDK + API-Key

Der zentrale Befund: Die Power von Claude Code steckt in der Harness (Agenten- Loop, Kontext-Management, Tool-Use, Sub-Agenten, Permissions, MCP) — nicht im Abo-Modell. Anthropic liefert genau diese Harness als Claude Agent SDK (TypeScript/Python). Mit einem API-Key betrieben hat sie die volle Claude-Code-Power und vollen lokalen Zugriff. Der oft gehörte Satz „API ist schwächer als das Abo" verwechselt roher Einzel-API-Call mit Harness — der Unterschied ist die Harness, nicht die Abrechnungsart.

→ Wir bauen nicht einen eigenen Agenten und nicht einen Wrapper um die CLI, sondern betten das Agent SDK als Engine ein.

Gehirn lokal (local-first)

Der Agent-SDK-Prozess läuft als lokaler Prozess auf dem Rechner des Nutzers (Windows und macOS). Damit hat er denselben vollen Zugriff wie Claude Code: Dateien, Shell, Git, Drive, Programme. Das ist die Kern-Differenzierung gegenüber remote-first-Systemen — und nicht verhandelbar.

Plattform-Strategie: Windows + macOS, nativ & von Anfang an

Beide Betriebssysteme werden von Beginn an parallel entwickelt — bewusst in den nativen Sprachen des jeweiligen OS (Windows: .NET/WinUI, macOS: Swift/SwiftUI), kein geteilter Cross-Platform-Core. Grund: Ein Produkt, das tief ins System greift (OS-Steuerung), braucht native APIs (Accessibility, System-Integration, native Performance) — ein Cross-Platform-Shell würde das beschneiden. Der Preis (zwei Codebasen) wird bewusst in Kauf genommen.

Geteilt wird nur, was kein Code sein muss: Verträge, Protokoll-/Schema-Definitionen, Agenten-/Prompt-Specs und die LLM-Wiki-Struktur — das, was beide Apps gleichermaßen konsumieren.

Agent SDK = lokaler Dienst. Das Agent SDK ist Node/Python, die Apps sind nativ — das Hirn läuft daher als lokaler Sidecar/Daemon auf dem Rechner, mit dem beide nativen Shells reden. So bleibt „Gehirn lokal" erhalten, ohne die App-Schicht an Node zu binden.

Orchestrator → Mitarbeiter → Worker

Mensch (an der Pille)              ← orchestriert & beobachtet
   │  Auftrag
   ▼
Orchestrator (heute Mensch,        ← verteilt, bündelt Status
   später optional Agent)
   │
   ▼
KI-Mitarbeiter (Ordner + Rolle)    ← persistente Identität, eigenes Gedächtnis
   │  spawnt
   ▼
Worker (Agent-SDK-Subagenten)      ← laufende Ausführung, parallelisierbar

Die Parallel-Ausführung ist keine Eigenleistung: Agent SDK / Claude Code können Subagenten parallel spawnen (Task-/Agent-Mechanik, „Agent Teams"). Unser Beitrag ist die menschlich verständliche Ebene darüber — siehe ux-konzept.

Remote: dünnes Relay, kein VPS-Vorrang

Remote-Bedienung ≠ VPS. Ein VPS kann lokale Dateien nicht anfassen. Wenn Fernzugriff gebraucht wird, dann als dünnes Relay zum immer-an lokalen Rechner (Muster: Anthropics „Dispatch" — Handy = Steuerfläche, Rechner = Executor). Sekundär; der Nutzer arbeitet primär am Rechner. Ein VPS lohnt nur für Arbeit ohne lokale Dateien.

Offene Spannung: Lock-in vs. Provider-Freiheit ⚠️

Das bestehende 2Key-Prinzip (../wiki/glossar: „Provider — Kein Lock-in, hinter jeder Capability austauschbar") steht in Spannung zu „Engine = Anthropic Agent SDK". Vorschlag zur Auflösung (zu bestätigen): Die agent-Capability bindet sich bewusst an Anthropic (dort ist die Harness entscheidend überlegen), während stt/tts/image/chat austauschbar bleiben. Ehrlich benannt: Das ist Lock-in für den agentischen Kern — akzeptabel, solange er der Grund ist, warum die Mitarbeiter so gut sind. Entscheidung gehört in app/docs/FOUNDATION.md, sobald hart.

Verhältnis zur OS-Automation-Leiter

Die bestehende OS-Automation-Leiter (Tier 1 Primitive → 2 UI Automation → 3 MCP → 4 Vision-Fallback) widerspricht der Engine nicht — sie wird zur Werkzeugkiste, die die Harness aufruft. Offene Frage: wie viel davon übernimmt das Agent SDK nativ vs. eigene Tools. Klärung mit app/docs/funktionsumfang.md.