# 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