👾 ClawdPanel

A retro-styled desktop HUD for Claude Code.
Monitor token usage, switch accounts, dock across monitors, and stream Lo-Fi radio — all from a native cross-platform utility bar.

Always-on-top · Frameless · Multi-monitor Dock · Pin / auto-hide on hover · System tray · Multi-account

---

💡 Why ClawdPanel?

A permanent lightweight desktop HUD for Claude Code users — live token monitoring, multi-account switching, cross-monitor docking, retro terminal aesthetics, ambient Lo-Fi radio, zero-browser workflow.

Unlike browser dashboards or terminal-only tools, ClawdPanel lives directly in your desktop environment with native OS integrations: Windows AppBar reservation, macOS LaunchAgents, Linux _NET_WM_STRUT_PARTIAL, system-tray everywhere.

👤 Built for

• Claude Code power users running long sessions
• Teams juggling multiple Claude accounts
• Terminal enthusiasts and retro / CRT-aesthetic fans
• Anyone who prefers a HUD over an extra browser tab

---

🎬 Demo

Animated demos coming soon. For now, see the bar layout above and the themes section below.

---

🖥️ Core Features

• Live token usage — weekly + hourly consumption, percentage, shaded progress bar, reset countdown
• Multi-account — switch any number of Claude accounts (separate ~/.claude paths) via tray or Settings
• Multi-monitor docking — pick the target monitor at any time; reserves screen space on Windows + Linux X11
• Pin / auto-hide on hover — unpin to slide the bar off-screen; cursor at top edge slides it back
• System tray — switch account, switch monitor, toggle start-on-login, manage accounts, quit
• Start on login — native autostart on all three platforms
• 5 retro themes — Claude, Fallout, Amber, Matrix, Dracula
• Headless Claude FM — embedded Lo-Fi YouTube stream with custom volume control

---

🚀 Quick Start

Download from the Releases page:

Platform	File	Notes
Windows 10/11 x64	ClawdPanel-*-windows-amd64-setup.exe	NSIS installer. Requires WebView2 Runtime (pre-installed on Win11).
macOS 10.13+ (Intel + Apple Silicon)	ClawdPanel-*-macos-universal.pkg	Double-click to install to /Applications.
Debian / Ubuntu	clawdpanel_*_amd64.deb	sudo apt install ./clawdpanel_*_amd64.deb
Fedora / RHEL	clawdpanel-*.x86_64.rpm	sudo dnf install ./clawdpanel-*.x86_64.rpm
Any Linux (portable)	ClawdPanel-x86_64.AppImage	chmod +x ClawdPanel-x86_64.AppImage && ./ClawdPanel-x86_64.AppImage

Installers wire up Claude Code's statuslineCommand automatically and clean it up on uninstall — no terminal commands needed. AppImage users get a one-time first-run prompt instead.

First-launch security warnings (unsigned v1)

• Windows → SmartScreen "Windows protected your PC" → More info → Run anyway
• macOS → "ClawdPanel cannot be opened…" → System Settings → Privacy & Security → Open Anyway, or right-click the .app → Open
• Linux .deb/.rpm → no warnings (root install)
• AppImage → no warnings (user-mode)

Build from source

Requires Go 1.25+, Node.js 18+, Wails v2 CLI (go install github.com/wailsapp/wails/v2/cmd/wails@latest). On Linux also: libgtk-3-dev, libwebkit2gtk-4.1-dev, libayatana-appindicator3-dev, pkg-config.

wails dev                                         # hot-reload dev mode
wails build -platform windows/amd64 -nsis         # Windows installer
wails build -platform darwin/universal            # macOS .app (then build/darwin/scripts for .pkg)
wails build -platform linux/amd64 -tags webkit2_41  # Linux binary (then nfpm/AppImage via build/linux/*)

---

🎨 Visual Design

Five distinct CRT-scanline-filtered themes, cycle on the fly:

Theme	Vibe
🔸 CLAUDE (default)	Flat CLI — signature terracotta orange (#d77757), lavender badges (#b1b9f9), white headers
🟢 FALLOUT	Pip-Boy green HUD, outlined progress brackets, glowing CRT scanlines
🟡 AMBER	DEC VT100 / Fallout NV amber terminal — glowing values, dimmed labels
📟 MATRIX	Digital rain — sharp green characters, blinking caret synced to warning status
😈 DRACULA	Sleek dark mode — cyan labels, pastel pink progress

Claude  ·  terracotta + lavender, the default

Fallout  ·  Pip-Boy green with CRT scanlines

Amber  ·  DEC VT100 glowing amber

Matrix  ·  digital rain with dot dividers

Dracula  ·  dark mode with pastel pink progress

Typography & TUI glyphs

• Developer-first font stack: prefers Cascadia Mono / Cascadia Code, then SF Mono, Menlo, Fira Code, JetBrains Mono, DejaVu Sans Mono, Inconsolata — uses whatever's installed.
• Retro shaded meters: usage rendered with ░▒▓█ glyphs that change shade with warning tier; unused cells are faint terminal middle dots (·).

---

🛠️ Advanced Features

Pin / auto-hide

A pin icon to the right of THEME toggles:

• Pinned (orange, tilted): docked, permanently visible — the default.
• Unpinned (gray, upright): bar slides up off-screen; cursor at the top edge slides it back.

Implementation notes

Go-side cursor polling at 80 ms — WebView2's mouseleave is unreliable on a 28 px window. A 200 ms grace period prevents accidental dismissal on cursor overshoot. The slide animates the OS window's Y position at ~60 fps (ease-out cubic) with a SetWindowRgn clip that masks any portion that would spill onto a monitor sitting above. (Windows only at v1; on macOS / Linux the toggle still affects docked-vs-floating state but the slide is a no-op.)

Multi-monitor docking

Pick the target monitor from the tray menu. On Windows, AppBar mode uses SHAppBarMessage to reserve screen space — maximized windows automatically tile below. On Linux X11 it sets _NET_WM_STRUT_PARTIAL for compatible compositors. On macOS and Linux Wayland the bar floats at the topmost window level without reserving space.

Claude FM (headless Lo-Fi radio)

Embedded YouTube audio stream — no browser windows needed.

• 📻 Masked marquee: when playing, the label scrolls NOW PLAYING CLAUDE FM · horizontally behind a 75 px mask; reverts instantly on pause.
• 🔊 0–200 % volume range: extended headroom mapped linearly to YouTube's 0–100.
• 🎛️ Dual control: scroll-wheel adjusts in 5 % steps; clicking VOL cycles in 10 % steps.
• 💾 State persistence: volume and theme saved to localStorage.

Smart status overrides

Dynamic and static OFFLINE indicators are translated globally into a lavender IDLE badge (#b1b9f9) to preserve your active CLI context.

---

🧭 Architecture

Claude Code (CLI)
       │
       │  statuslineCommand hook
       ▼
~/.claude/rate_limits.json   ←  written every prompt
       │
       │  filesystem poll (refreshSeconds)
       ▼
ClawdPanel backend (Go)
       │
       │  Wails IPC (JSON bindings)
       ▼
WebView frontend (HTML/CSS/JS)
       │
       └── OS integrations: AppBar / NSWindow / X11 dock,
                            system tray, autostart, monitors

---

⚙️ Configuration

Auto-created on first run:

Platform	Path
Windows	%APPDATA%\ClawdPanel\config.json
macOS	~/Library/Application Support/ClawdPanel/config.json
Linux	$XDG_CONFIG_HOME/ClawdPanel/config.json (fallback ~/.config/ClawdPanel/config.json)

{
  "monitor": 0,
  "theme": "claude",
  "opacity": 0.92,
  "refreshSeconds": 15,
  "barHeight": 28,
  "appBarMode": true,
  "startWithWindows": false
}

Accounts are managed inside the app — open Manage accounts from the system tray to add, rename, switch between, or remove Claude account paths. No JSON editing required.

Field	Description
barHeight	Pixel height of the bar
refreshSeconds	Re-read interval for Claude data files
theme	claude, fallout, amber, matrix, dracula
appBarMode	Reserve screen space (Windows / Linux X11 only)

How live usage capture works

ClawdPanel reads ~/.claude/rate_limits.json, populated by Claude Code's statuslineCommand hook. Installers set this hook automatically and clear it on uninstall by editing ~/.claude/settings.json (only the statuslineCommand key — other keys are preserved).

If you built from source or are using the AppImage and want to configure manually:

claude config set statuslineCommand "node -e \"const fs=require('fs');const p=require('path');const os=require('os');const d=fs.readFileSync(0,'utf-8');if(d){const parsed=JSON.parse(d);fs.writeFileSync(p.join(os.homedir(),'.claude','rate_limits.json'),JSON.stringify({...parsed,captured_at:Date.now()}))}\""

Every Claude prompt then writes a tiny JSON payload to rate_limits.json, which ClawdPanel picks up instantly.

---

📁 Project Structure

clawdpanel/
├── main.go                          # Wails bootstrap + embed directives
├── app.go                           # App struct + Wails-exported bindings
├── icon_{windows,darwin,linux}.go   # Per-OS tray icon embedding
├── internal/
│   ├── config/
│   │   ├── config.go                # Config struct, Load/Save, cross-platform AppDataDir
│   │   └── startup_{windows,darwin,linux}.go  # autostart (registry / LaunchAgent / .desktop)
│   ├── claude/                      # Read Claude JSON files, compute BarData
│   ├── platform/                    # Per-OS window + monitor APIs
│   │   ├── window_{windows,darwin,linux}.go
│   │   └── monitor_{windows,darwin,linux}.go
│   └── tray/                        # System tray via fyne.io/systray
├── frontend/                        # Wails webview UI
└── build/
    ├── windows/installer/           # NSIS template + statusline PowerShell script
    ├── darwin/scripts/              # pkgbuild postinstall/preuninstall bash scripts
    └── linux/                       # nfpm.yaml, .desktop, AppDir, AppRun, postinstall.sh

---

⚠️ Known limitations (v1 cross-platform)

• Linux Wayland: no portable protocol for "stay above other windows" or "reserve screen space". KWin honors _NET_WM_WINDOW_TYPE_DOCK; GNOME/Mutter mostly ignores it; wlroots compositors (Hyprland, Sway) vary. X11 sessions work correctly.
• macOS docking: NSWindow at NSStatusWindowLevel floats above other windows but can't reserve screen space the way Windows AppBar does — accepted as macOS-native behavior.
• macOS Gatekeeper (unsigned v1): see First-launch security warnings in Quick Start.
• Settings merge safety: if ~/.claude/settings.json already exists but contains invalid JSON, the installer logs a warning and skips the modification rather than overwriting it.

---

📄 License

MIT — see LICENSE.