File size: 4,092 Bytes
bbc65cd | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 | # Claude Code Panel
A native GTK3 desktop panel for [Claude Code](https://claude.ai/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)
```bash
# 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
```bash
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](https://github.com/catppuccin/catppuccin) (dark) / [Catppuccin Latte](https://github.com/catppuccin/catppuccin) (light).
## License
MIT
|