FOR_SMLFLG.md

# ClaudeCodePanel — Wie dein Panel funktioniert

## Die Kurzversion

Dein Panel ist wie ein **Cockpit fuer Claude Code**. Statt 15 Terminal-Fenster
und Config-Dateien zu jonglieren, hast du ein GTK3-Fenster mit 7 Tabs
und ein Tray-Icon das immer da ist. Denk an ein Auto-Armaturenbrett:
Tacho (Monitor), Bordcomputer (Hub), Fehlerlampen (Logs), Navigationsliste (Sessions).

**Stack:** Python 3.12 + PyGObject (GTK3) + Catppuccin Theming + systemd Service

---

## Architektur — 14 Module

### panel.py (2373 Zeilen) — Der Dirigent
Das Hauptfenster. Baut alle Tabs zusammen, startet die Timer, verwaltet das Tray-Icon.
Wie ein Dirigent: spielt selbst kein Instrument, aber koordiniert alle anderen.

**Key:** `ControlPanel` Klasse mit `_build_*_tab()` Methoden, `_refresh_hub()`, `_refresh_monitor()`.

### monitor.py (729 Zeilen) — Der Daten-Butler
Holt alle Zahlen: Kosten, Top-Tools, aktive Sessions, Timeline.
Hat einen TTL-Cache (30 Sekunden) — fragt nicht staendig die Festplatte.

**Key:** `get_daily_cost()`, `get_top_tools()`, `get_active_sessions()`. Nutzt MyAIGame's `tui.data.*` Module.

### log_viewer.py (435 Zeilen) — Der Protokollant
Zeigt heutige Usage-Eintraege und Coaching-Log. Filterbar nach Tools/Errors/Hooks.

**Key:** `build_logs_tab()`, `refresh_logs()`. Liest `~/.claude/usage/YYYY-MM-DD.jsonl`.

### session_browser.py (1039 Zeilen) — Das Telefonbuch
Alle Claude-Sessions durchsuchbar. Zeigt Projekt, Vorschau, Groesse. Resume-Button oeffnet kitty.

**Key:** `build_sessions_tab()`, `_scan_all_sessions()`, `_on_resume_clicked()`.

### process_manager.py (588 Zeilen) — Der Hausmeister
Scannt `ps aux` nach Claude-relevanten Prozessen. Zeigt RAM, CPU, Uptime.
Kill-Button pro Prozess + "Kill All Ghosts" fuer Prozesse >24h.

**Key:** `build_processes_tab()`, `_scan_processes()`, Ghost-Detection via `/proc/<pid>/stat`.

### theme.py (620 Zeilen) — Der Maler
Erkennt ob COSMIC Desktop dunkel oder hell ist, generiert passendes CSS.
Catppuccin Mocha (dark) / Latte (light). Wechselt live wenn du das System-Theme aenderst.

**Key:** `is_dark_mode()` liest `~/.config/cosmic/com.system76.CosmicTheme.Mode/v1/is_dark`.
`setup_theme_watcher()` nutzt `Gio.FileMonitor` fuer Live-Updates.

### config_io.py (168 Zeilen) — Der Tresorwaerter
Liest und schreibt `~/.claude/settings.json` **atomar** — nie direkt.
Immer: Backup → Temp-Datei → `os.replace()`. So geht nie was kaputt.

**Key:** `read_settings()`, `write_settings()`, `update_setting("key.path", value)`.

### swarm_tab.py (974 Zeilen) — Der Lageplaner
Zeigt die laufende Agent Team Pipeline in Echtzeit. Liest `~/.claude/teams/` und
`~/.claude/tasks/` und stellt Scout→Weaver→Builder→Validator→Pruefer als Karten dar.

**Key:** `build_swarm_tab()`, `_scan_teams()`, `_refresh_swarm()`.

### swarm_visual.py (708 Zeilen) — Der Kartograf
Generiert HTML-Seiten mit interaktiven Agent-Kommunikationsgraphen: Hub-and-Spoke-Layout,
Bezier-Kurven, Partikel-Animationen. Wird von swarm_tab.py aufgerufen und in WebKit2 eingebettet.

**Key:** `generate_swarm_html()`, Bezier + Partikel-Rendering via Canvas.

### event_tab.py (426 Zeilen) — Der Horcher
Live-Viewer fuer Hook-Events aus `~/.claude/events/YYYY-MM-DD.jsonl`. Filterbar
nach Event-Typ, Auto-Scroll wenn neue Events reinkommen.

**Key:** `build_events_tab()`, `_tail_events()`, Filter-Logik nach Typ/Quelle.

### shortcut_counter_tab.py (450 Zeilen) — Der Strichlisten-Fuehrer
Zeigt Keyboard-Shortcut-Statistiken aus der ShortcutCounter-Datenbank. Wie oft hast
du Ctrl+C vs. Ctrl+Z genutzt? Welcher Shortcut spart am meisten Zeit?

**Key:** `build_shortcut_tab()`, liest ShortcutCounter SQLite DB.

### project_dashboard_tab.py (254 Zeilen) — Das Fenster
Bettet das Project Dashboard als WebKit2-Webview direkt ins Panel ein, statt
einen Browser oeffnen zu muessen. Ein Tab = ein komplettes Web-Dashboard.

**Key:** `build_project_dashboard_tab()`, `WebKit2.WebView` Setup + Reload-Button.

### utils.py (33 Zeilen) — Der Werkzeugkasten
Kleine Hilfsfunktionen die ueberall gebraucht werden (Format-Helpers, Pfad-Utilities).
Klein aber da wenn man ihn braucht.

**Key:** Shared Utilities fuer alle anderen Module.

### tools-gui/ (623 Zeilen) — Das Zweite Cockpit
Separates GTK3-Fenster mit 3 eigenen Tabs: Kosten-Analyse, Session-Uebersicht, Tool-Statistiken.
Laeuft als eigenstaendiges Fenster neben dem Hauptpanel (main.py + 3 Tab-Module).

**Key:** `tools-gui/main.py` als Einstiegspunkt, 3 Tab-Module fuer costs/sessions/tools.

---

## Wie die Tabs zusammenhaengen

```
panel.py (Dirigent)
  ├── importiert monitor.py        → liefert Daten fuer Hub + Monitor Tab
  ├── importiert log_viewer.py     → baut Logs Tab
  ├── importiert session_browser.py → baut Sessions Tab
  ├── importiert process_manager.py → baut Prozesse Tab
  ├── importiert swarm_tab.py      → baut Agent Swarm Tab
  ├── importiert swarm_visual.py   → generiert Swarm-Graphen (HTML)
  ├── importiert event_tab.py      → baut Events Tab
  ├── importiert shortcut_counter_tab.py → baut Shortcut Counter Tab
  ├── importiert project_dashboard_tab.py → baut Project Dashboard Tab (WebKit2)
  ├── importiert theme.py          → CSS + Theme Watcher
  └── importiert config_io.py      → Settings + Hooks Tabs lesen/schreiben Config
```

Jedes Modul ist **eigenstaendig** — kann theoretisch allein funktionieren.
panel.py ist nur der Rahmen der sie zusammenbringt.

---

## Timer-System — Das Herzschlag-System

Dein Panel hat 6 Timer die wie Herzschlaege funktionieren. Jeder Timer
ruft periodisch eine Funktion auf die Daten aktualisiert:

| Timer | Intervall | Funktion | Was wird aktualisiert? |
|-------|-----------|----------|----------------------|
| Hub | 30s | `_refresh_hub()` | Kosten, Top-Tools, Sessions |
| Monitor-Start | 15s | `_start_monitor_timer()` | Startet Monitor-Timer |
| Logs | 10s | `refresh_logs()` | Usage + Coaching Eintraege |
| Sessions | 60s | `refresh_sessions()` | Session-Liste |
| Prozesse | 30s | `refresh_processes()` | Prozess-Scan |
| Monitor | 30s | `_refresh_monitor()` | Timeline, Skills |

**Warum gestaffelt?** Damit nicht alle gleichzeitig feuern und die UI einfriert.
Logs sind am schnellsten (10s) weil Usage-Daten sich oft aendern.
Sessions am langsamsten (60s) weil sich Sessions selten aendern.

**Was wenn ein Timer haengt?** Jeder Timer returned `True` um am Leben zu bleiben.
Wenn einer Exception wirft, faengt `try/except` es ab und der Timer laeuft weiter.
Worst case: ein Tab zeigt veraltete Daten, aber das Panel stuerzt nicht ab.

---

## Daten-Flow

```
~/.claude/usage/YYYY-MM-DD.jsonl  ──→  monitor.py (Cache 30s)  ──→  Hub Tab (Kosten, Tools)
                                    └──→  log_viewer.py          ──→  Logs Tab (Eintraege)

~/.claude/projects/*/  ────────────→  monitor.py + session_browser  ──→  Sessions Tab

ps aux ────────────────────────────→  process_manager.py  ──→  Prozesse Tab

~/.claude/settings.json  ──────────→  config_io.py  ──→  Settings + Hooks Tab
```

---

## Theme-System

1. **Detection:** Liest `~/.config/cosmic/com.system76.CosmicTheme.Mode/v1/is_dark`
   - `true` → Catppuccin Mocha (dunkle Palette)
   - `false` → Catppuccin Latte (helle Palette)
   - Datei fehlt → Fallback auf GTK `gtk-application-prefer-dark-theme`

2. **CSS:** `build_css(palette)` generiert ~150 Zeilen CSS aus der Palette

3. **Live-Switch:** `Gio.FileMonitor` beobachtet die COSMIC Config-Datei.
   Aendert sich das System-Theme, wird `apply_theme()` via `GLib.idle_add` aufgerufen.

---

## Config-System — Atomare Writes

Warum nicht einfach `json.dump(data, open(file, "w"))`?
Weil: wenn der Prozess mittendrin stirbt, hast du eine kaputte halbe Datei.

**Stattdessen (config_io.py):**
1. **Backup:** `settings.json` → `settings.json.backup-20260302-143000`
2. **Temp:** Schreibe in `settings-XXXX.tmp` (gleicher Ordner)
3. **Rename:** `os.replace(tmp, settings.json)` — atomar auf Linux!

Entweder hast du die alte ODER die neue Datei. Nie eine kaputte.

---

## Sprint 2026-03-04 Learnings

### Das Wichtigste zuerst: Deine vorherige Arbeit war solide.

4 von 5 Warnings waren **bereits gefixt** bevor der Sprint anfing (Commit `67a4362`).
Du hast einen 5-Agenten-Sprint geplant fuer... einen einzigen verbleibenden Fix (subprocess.run → Popen).
Das Panel ist zu **95%+ fertig**. Was wirklich noch offen ist: 4 Suggestions (nice-to-have), kein Critical.

### Muster: Erst schauen, dann planen.

Tendency erkannt: Samuel plant gross (5 Agents, detaillierter PLAN-File) **bevor** er den aktuellen Stand prueft.
Regel fuer dich: **`/check-state` vor jedem Sprint-Start.** Eine Minute Status-Check spart eine Stunde Overhead.

Konkret: Bevor du Tasks erstellst, kurz pruefen:
- Welche Punkte der Checkliste sind schon erledigt? (PLAN-File lesen)
- Laeuft der Service gerade fehlerfrei? (`systemctl --user status claude-panel.service`)
- Wie gross ist der echte Rueckstand? (1 Fix ≠ 5-Agenten-Aufwand)

### Was gut lief (verstaerken!)

- **Dokumentations-Disziplin:** PLAN-File erstellt, Review-Findings dokumentiert, Entscheidungen festgehalten. Das ist wertvoll.
- **Commit-Hygiene:** Criticals sofort gefixt und committed. Kein "ich mach das spaeter".
- **Code-Review Workflow:** Sonnet Review + MiniMax Zweitmeinung. Zwei Perspektiven fangen mehr.
- **Architektur-Entscheidungen klar begruendet:** `**/*.jsonl` fuer rekursive Suche, `"anthropic"` Key-Aggregation, Fingerprint-Mechanismus — alles dokumentiert.

### Was noch aussteht (die echte Restliste)

Nur Suggestions, kein muss:
1. `monitor.py:~662` — `sorted()` mit stat()-Lambda vereinfachen
2. `log_viewer.py:~456` — unbenutzten `sort_model` Parameter entfernen
3. `panel.py:~812` — `_DETECTOR_LAYOUT` Naming-Konvention
4. `log_viewer.py` — Status-Farben aus Theme-Palette statt hardcoded

Das Panel laeuft. Diese Fixes machen es sauberer, nicht funktionsfaehiger.

---

## Bekannte Gotchas

1. **CPU Spin-Loop (GEFIXT):** `GLib.idle_add(refresh_logs)` mit `return True` =
   Endlosschleife. Fix: One-Shot Wrapper mit `return False`. Regel: `idle_add`
   Callbacks muessen IMMER `False` returnen.

2. **Ghost-Prozesse:** MCP-Server (opencode-mcp, gemini-mcp) werden pro Session
   gestartet aber nie beendet. Der Prozesse-Tab zeigt sie als "Ghosts" (>24h).

3. **MyAIGame Dependency:** `monitor.py` importiert `tui.data.usage_reader` aus
   `~/Projekte/MyAIGame/`. Wenn das Projekt nicht existiert, fallen Kosten-
   und Tool-Statistiken auf Null zurueck (graceful fallback, kein Crash).

4. **COSMIC-only Theme Detection:** Auf nicht-COSMIC-Desktops funktioniert nur
   der GTK-Fallback. Die Catppuccin-Farben bleiben, aber Live-Switching nur per GTK.

5. **Singleton Lock (GEFIXT):** Frueher konnten mehrere Panel-Instanzen gleichzeitig
   laufen (systemd restart + manueller Start). Fix: `fcntl.flock` auf `/tmp/claude-panel.lock`.
   Zweite Instanz erkennt Lock und beendet sich mit `sys.exit(0)`.