Initial public upload from Projekte/ClaudeCodePanel

bbc65cd verified about 1 month ago

11.2 kB

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

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
CSS: build_css(palette) generiert ~150 Zeilen CSS aus der Palette
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):

Backup: settings.json → settings.json.backup-20260302-143000
Temp: Schreibe in settings-XXXX.tmp (gleicher Ordner)
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:

monitor.py:~662 — sorted() mit stat()-Lambda vereinfachen
log_viewer.py:~456 — unbenutzten sort_model Parameter entfernen
panel.py:~812 — _DETECTOR_LAYOUT Naming-Konvention
log_viewer.py — Status-Farben aus Theme-Palette statt hardcoded

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

Bekannte Gotchas

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.
Ghost-Prozesse: MCP-Server (opencode-mcp, gemini-mcp) werden pro Session gestartet aber nie beendet. Der Prozesse-Tab zeigt sie als "Ghosts" (>24h).
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).
COSMIC-only Theme Detection: Auf nicht-COSMIC-Desktops funktioniert nur der GTK-Fallback. Die Catppuccin-Farben bleiben, aber Live-Switching nur per GTK.
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).