ClaudePanel Bridge

Not sure where to start? Begin at the plugin site — that’s the system overview and install walkthrough that gets your Claude Code session talking to the panel.

The bridge is the cross-platform tray app that connects Claude Code to your ClaudePanel hardware. It subscribes to the ClaudePanel plugin’s local broker, watches your Claude Code session lifecycle events, and forwards each state change to your ESP32-S3 over USB serial.

It lives in your system tray (Windows notification area / macOS menu bar / Linux status icon). Right-click for start / stop / pause / logs / quit. You probably don’t need to think about it once it’s installed — it starts on login, runs in the background, and survives reboots.

Install

Windows (x64)

Download ClaudePanelBridge-0.5.0-Setup.exe and double-click it.

Per-user install — no admin password needed. The installer drops the binary into %LOCALAPPDATA%, registers an entry in Apps & Features, writes the standard HKCU\Software\Microsoft\Windows\CurrentVersion\Run autostart entry so the bridge launches at login, and starts the tray icon immediately.

SmartScreen may warn "publisher not verified" on first run; click More info → Run anyway. The binary is self-signed; full Authenticode signing isn't in place yet.

Uninstall: Settings → Apps → ClaudePanel Bridge → Uninstall.

macOS (Apple Silicon or Intel)

Download the matching .dmg:

Open the .dmg, drag ClaudePanelBridge.app into Applications, then double-click it. The app lives in your menu bar — there is no Dock icon.

First launch may need: System Settings → Privacy & Security → Open Anyway. The bundle is ad-hoc signed but not notarized (no Apple Developer cert yet), so Gatekeeper asks for confirmation the first time.

Linux (x64)

Download ClaudePanelBridge-0.5.0-x86_64.AppImage.

chmod +x ClaudePanelBridge-*-x86_64.AppImage
./ClaudePanelBridge-*-x86_64.AppImage

If you want it to start at login, run ./ClaudePanelBridge-*-x86_64.AppImage install once — that writes a systemd user unit (~/.config/systemd/user/claude-status-bridge.service) which resumes the bridge each session.

The tray icon needs a system-tray host on GNOME (the AppIndicator and KStatusNotifierItem Support extension is the usual one). KDE / XFCE / Cinnamon work out of the box.

Find your hardware

The bridge needs to know which USB serial port your ClaudePanel is on.

On first run, if no port is configured (fresh install, or appsettings.json missing / Bridge:ComPort empty), the bridge pops a Connect device dialog automatically before it even starts the tray icon. The dialog scans every plausible serial port the moment it opens, asks each one to identify itself, and shows you a list. Pick the matching ClaudePanel with a click — your choice is written into appsettings.json so subsequent launches go straight to the tray.

Later, if you swap boards or want to re-pick, click Connect device in the tray menu — same scan, same dialog.

For scripting, recovery, or headless setups, the same flow is available as a CLI subcommand (ClaudeStatusBridge find) — see CLI usage below for the exact invocation on your OS.

After install

The bridge runs in the background. To see it working:

  1. Plug your ESP32-S3 ClaudePanel hardware in via USB. Don’t have one yet? Head to the firmware site for a one-click flasher and a parts list.
  2. Right-click the tray icon → use Connect device to pick the detected ClaudePanel (or run find from a terminal).
  3. Send a prompt in any Claude Code session that has the ClaudePanel plugin installed. The matrix should react.

The tray menu also has Resend panel config, which re-reads the panel layout configured via /claude-status:configure and pushes it to the firmware immediately — useful right after changing the layout, or when no session is routed yet so there’s no event traffic for the bridge to piggyback the change on.

CLI usage

The bridge is primarily a tray app — most users never need the command line. But all the same operations are available as subcommands of the binary, which is handy for scripting, CI, or debugging.

On Windows the executable lives at %LOCALAPPDATA%\ClaudePanelBridge\ClaudeStatusBridge.exe. On macOS it’s inside the bundle: /Applications/ClaudePanelBridge.app/Contents/MacOS/ClaudeStatusBridge. On Linux it’s the AppImage you downloaded.

Windows note: the Windows build is a Windows-subsystem binary so the tray launches without a console flash. That means cmd / PowerShell won’t block waiting for it to finish — output still flows to your shell, but it interleaves with the next prompt. For interactive subcommands like find, invoke via Start-Process -Wait:

Start-Process -Wait `
    "$env:LOCALAPPDATA\ClaudePanelBridge\ClaudeStatusBridge.exe" `
    -ArgumentList find
Command What it does
install Register + start the background service.
uninstall Stop + deregister.
start / stop Toggle the running instance without deregistering.
restart Stop then start.
find Scan + identify a connected ClaudePanel; write the
  chosen port to appsettings.json. (interactive)
  Also accepts the legacy alias match.
status Show install state, running state, and version.
version Print the version string.
logs Tail the bridge log (Ctrl-C to exit).
help Show usage.