Claude Code Panel

A native GTK3 desktop panel for Claude Code on Linux. System tray icon, session browser, agent swarm monitor, cost tracking, event viewer — all in one place.

Built for Pop!_OS / COSMIC Desktop, works on any Linux with GTK3.

Features

• System Tray Icon — always-on indicator with quick access menu (AyatanaAppIndicator)
• Hub Tab — daily cost, top tools, active sessions at a glance
• Monitor Tab — signal cards, usage timeline, provider cost breakdown, phase badge
• Session Browser — search, filter, and resume sessions with one click
• Process Manager — Claude-related processes (MCP servers, CLI), ghost detection, kill button
• Agent Swarm Tab — live view of Agent Team pipelines (Scout → Weaver → Builder → Validator → Prüfer)
• Swarm Visual — HTML agent communication graph (hub-and-spoke, Bézier curves, particles)
• Event Viewer — live hook events from ~/.claude/events/ with filters + auto-scroll
• Shortcut Counter — keyboard shortcut usage stats from ShortcutCounter DB
• Project Dashboard — embedded WebKit2 view of project dashboards
• Log Viewer — filterable usage + coaching log entries
• Settings & Hooks — read/write Claude Code config with atomic file writes
• Cost Tracking — daily token costs, 7-day bar chart, per-provider breakdown
• Light/Dark Mode — auto-detects COSMIC Desktop theme, Catppuccin Mocha/Latte, live switching
• Singleton Lock — only one instance runs at a time (fcntl.flock)
• Portrait Monitor — auto-moves window to portrait display if available

Requirements

• Python 3.10+
• GTK 3.0
• AyatanaAppIndicator3 (system tray)
• WebKit2 (optional, for Project Dashboard tab)

# Pop!_OS / Ubuntu / Debian
sudo apt install python3-gi gir1.2-gtk-3.0 gir1.2-ayatanaappindicator3-0.1 gir1.2-webkit2-4.1

Installation

git clone https://github.com/smlfg/ClaudeCodePanel.git
cd ClaudeCodePanel

# Run directly
python3 panel.py

# Or install as systemd user service (auto-start on login)
cp claude-panel.service ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now claude-panel.service

Architecture

panel.py (2373 LOC) — Main window, 7+ tabs, tray icon, singleton lock
  ├── monitor.py (729)        — Data layer: costs, tools, sessions (TTL cache 30s)
  ├── config_io.py (168)      — Atomic config read/write (backup → temp → rename)
  ├── theme.py (620)          — COSMIC theme detection + Catppuccin CSS
  ├── session_browser.py (1039) — Session list, search, resume
  ├── process_manager.py (588)  — Process scan, ghost detection, kill
  ├── log_viewer.py (435)       — Usage + coaching log viewer
  ├── swarm_tab.py (974)        — Agent Team pipeline viewer
  ├── swarm_visual.py (708)     — HTML agent communication graph
  ├── event_tab.py (426)        — Live hook event viewer
  ├── shortcut_counter_tab.py (450) — Keyboard shortcut stats
  ├── project_dashboard_tab.py (254) — Embedded project dashboard (WebKit2)
  └── utils.py (33)            — Helper functions

tools-gui/ (separate window)

tools-gui/main.py (83)           — Standalone GTK3 window
  ├── tabs/sessions_tab.py (146) — Session list with search
  ├── tabs/costs_tab.py (216)    — Daily costs + 7-day bar chart (Cairo)
  └── tabs/tools_tab.py (178)    — Tool + skill usage breakdown

Total: ~9,700 LOC across 19 Python files.

Theme System

The panel auto-detects your desktop theme:

• COSMIC Desktop: reads ~/.config/cosmic/com.system76.CosmicTheme.Mode/v1/is_dark
• Other GTK desktops: uses gtk-application-prefer-dark-theme setting

Switching your system theme updates the panel in real-time (no restart needed).

Color palettes: Catppuccin Mocha (dark) / Catppuccin Latte (light).

License

MIT