SideCrab 🦀

An ambient Claude Code status panel for the Corsair Xeneon Edge.

New here? Read Getting started: a 20-minute walkthrough from nothing installed to a working panel, with what you should see at each step.

SideCrab turns the Xeneon Edge on your desk into a live view of every Claude Code session on your PC. Session cards, rate-limit gauges with a reset countdown, today's token burn, a clock, a "needs your attention" alert, and a pixel crab whose mood is the status. When a session stops to ask you something, you find out from across the room instead of by cycling through terminal windows. Then you can answer it from the panel.

What you need

Everything runs on one PC and talks only over 127.0.0.1. Nothing is sent anywhere.

Two ways to run it

Widget only. Install the widget and run nothing else. You get the crab, the clock, and the CPU and GPU temperatures your iCUE sensors expose. No setup, no background process. Claude Code data is simply absent, and the panel says so.

Widget + companion (the point). Run the small local service, crabd, on the PC where you use Claude Code. The panel comes alive: live session cards, limit gauges with a depletion forecast, burn history and an optional daily token budget, a daily recap with a drillable week strip, and alerts when a session is waiting on you.

How it works

Claude Code hooks ──POST──▶  crabd (127.0.0.1:2722)  ◀──poll── SideCrab widget (iCUE / Xeneon Edge)
~/.claude usage + JSONL ──▶  one /v1/state JSON feed  ──write─▶ /v1/action · /v1/config
                             + blocking hook answers  ◀──poll── notifier (Windows toasts)

1. Claude Code tells crabd what is happening. The installer adds a few hooks to your ~/.claude/settings.json. Each one is a tiny localhost POST that fires when a session starts, when you submit a prompt, when a session stops, and when it needs your attention. They time out in two seconds and never block Claude Code if crabd is not running.
2. crabd keeps the picture. It turns those events into per-session state (working, waiting, finished, needs input), reads your rate limits from the same local credentials Claude Code uses, and reads the session transcripts read-only for token burn and elapsed time. It serves all of that as one JSON document on http://127.0.0.1:2722/v1/state.
3. The widget draws it. Every three seconds the iCUE widget polls that URL and repaints. The crab's posture is the summary: calm when all is well, alert when something waits on you, worried when the feed is stale or gone.
4. Taps go back the same way. Acknowledge, dismiss, pin, "Continue", and (if you turn it on) approve or deny go to crabd on localhost. Nothing free-text is ever sent to a session.

What the companion reads: ~/.claude (session transcripts, hook payloads, the local usage credential). What it never does: write to ~/.claude, log or transmit your OAuth token, listen on a network interface, or send anything off the machine. The only outbound call is the usage-limit check to Anthropic's API with your own token, the same call Claude Code makes.

The panel is honest about not knowing. No companion, a stopped companion, or a feed older than 30 seconds all produce a worried crab and a "data as of HH:MM" banner. Unknown values render as an em-dash, never as zero. A green-looking panel always means the data is fresh.

Install

Step 1 — the widget (5 minutes)

1. Download SideCrab-<version>.icuewidget from the releases page.
2. Import it into iCUE: double-click the file (iCUE 5.46.67+), or in iCUE open the Xeneon Edge's dashboard editor and import the widget from the file.
3. Place it full-screen on the Xeneon Edge.

You now have the crab, the clock and your temperatures. If this is all you want, stop here.

Step 2 — the companion (10 minutes)

Open PowerShell 7 on the PC where you run Claude Code:

git clone https://github.com/Dixie-sketch/Clawdeck.git C:\Dev\sidecrab
cd C:\Dev\sidecrab
pwsh -File .\setup\Install-SideCrab.ps1 -WithToast

The installer:

• registers a logon Scheduled Task for crabd (and the notifier if you asked for it), and starts it,
• backs up ~/.claude/settings.json, then merges in the SideCrab hook entries. Re-running never duplicates them and other hooks are left alone,
• registers the toast identity and the sidecrab-ack: handler for the notifier, under HKCU, no elevation needed,
• asks whether to enable panel approvals. Say no until you have read the section below.

Then check it:

pwsh -File .\setup\Install-SideCrab.ps1 -Status   # read-only status of every piece
pwsh -File .\setup\Test-SideCrab.ps1              # end-to-end smoke test, PASS/FAIL table

Start a Claude Code session. Within a few seconds a card for it appears on the panel.

Updating, uninstalling

git -C C:\Dev\sidecrab pull
pwsh -File C:\Dev\sidecrab\setup\Update-SideCrab.ps1      # restarts the tasks on the new code
pwsh -File C:\Dev\sidecrab\setup\Uninstall-SideCrab.ps1   # removes tasks, hooks and both registry keys

The widget updates separately: import the new .icuewidget from the releases page. The two sides are built to tolerate a version gap, so updating one before the other is fine.

Using it

At a glance

• The crab is the summary. Calm = nothing needs you. Alert with a glow = a session is waiting. Worried and grey = the data is stale or the companion is gone. It sweats when a limit is nearly full, and it has a few tricks it does on its own.
• Session cards show state, model, elapsed time, the repo it is working in, a hairline for how full that session's context window is, and a "queued: …" line when you have sent it a next step.
• Limit gauges show each rate-limit window, how full it is, when it resets, and a forecast of when the recent burn rate would fill it.
• TODAY shows token burn with a sparkline, the daily budget if you set one, and cost when Claude Code's telemetry is flowing to the companion.
• The week strip is the daily recap: sessions, commits in your configured repos, tokens.
• The hardware row shows CPU and GPU temperatures with the name of the sensor each reading comes from, plus this PC's CPU and memory use while the companion runs.

Touch

Sending a session its next step

On a stopped or finished session, tap the card and pick a continue prompt: "Continue", "Run the tests", "Commit + push", or any you add in the config file. It is delivered the next time that session's Stop hook fires. The vocabulary is fixed on purpose. There is no free-text input on the panel and no supported way to inject arbitrary text into a live session.

Approving a permission request from the panel

When a session is waiting on a tool permission, the card shows the request with a countdown, and you can approve or deny it from the panel. This ships off. Read the next section before you turn it on. Turning it on is three steps:

pwsh -File .\setup\Install-SideCrab.ps1 -WithApprovals   # 1. arm it (prints the pairing code)
pwsh -File .\setup\Install-SideCrab.ps1 -PairingCode     #    ...or print the code again later

2. In iCUE, open the SideCrab widget's settings and paste the code into Approval Pairing Code. 3. Tap Approve or Deny on the next request. A tap without the code, or with a wrong one, is refused and the terminal dialog keeps the decision, exactly as if the panel were not there.

Configuration

~/.sidecrab/config.json, all keys optional. Most of these are also editable from the panel's settings sheet.

{
  "quietHours": { "start": "22:00", "end": "07:00" },  // dim panel, no glow, no toasts
  "toast":  { "enabled": true, "thresholdSec": 120, "approvalThresholdSec": 20 },
  "digest": { "enabled": false, "time": "09:00" },     // one "yesterday" toast per day
  "budget": { "dailyOutputTokens": 5000000 },          // null to clear; one toast on crossing
  "continuePrompts": ["Continue", "Run the tests"],    // extra taps on a stopped session
  "panelApprovals": { "enabled": false },              // approve/deny from the panel — see below
  "recapRepos": ["C:\\Dev\\sidecrab"]                  // extra repos to count commits in
}

continuePrompts and recapRepos are hand-edited only. The panel reads them but does not write them.

Before you turn on panel approvals

Approving a tool call from a wall-mounted touchscreen is a real security decision, so the guarantees are worth reading rather than assuming:

• It ships off. The installer asks.
• crabd never decides on its own. There is no code path that answers "allow" without a decide request arriving on localhost first. The normal source of that request is a tap on the panel.
• Only a paired panel can decide (crabd 0.29.0 / widget 0.27.0). crabd mints a ten-character pairing code into ~/.sidecrab/panel-token on first start, and every Approve or Deny must carry it. The code lives in the widget's iCUE settings, which no web page can read, so a page you visit that forges the widget's null Origin gets a 403 and nothing else. Ten wrong codes in a minute lock the gate for a minute. Each tap also names the exact request it saw (requestId), so a tap can never land on a request that replaced it. This closed the SEC-a and WID-a findings recorded in SECURITY.md.
• Every failure is a pass-through. Timeout, no tap, disabled, malformed, companion down: all return no decision, and the normal terminal dialog does its job. The worst case is the behaviour of a machine where SideCrab was never installed.
• The toast has no buttons. When a request goes undecided, the notifier tells you and says "Decide on the panel." A notification action is one click from a lock screen; that is fine for acknowledging a dot and not for allowing a command.
• Verified live, operator present (2026-08-27) via setup\Verify-PanelApproval.ps1: a panel Approve ran the command with no keyboard, a panel Deny blocked it, and a full minute of ignoring both surfaces ended in the pass-through with the terminal dialog in charge. Two behaviours worth knowing: the terminal dialog is raced, not suppressed (whichever surface answers first wins), and the two-button card carries a real mis-tap risk. Run the same script on your own machine before trusting it.

Troubleshooting

Known caveats

• The glow is parked. The Corsair SDK crashes in every non-interactive console context tested, so the SideCrab-glow task ships disabled on purpose, and the panel's fleet dot honestly shows it stopped. The installer will not re-enable it on a re-run.
• The status-line feed is a fallback, not a replacement. It fires only in an interactive terminal session. The credential-based limits path works regardless.
• Cost figures need telemetry. costUSD appears only when Claude Code's OTLP telemetry is flowing to the companion. It is never estimated from token counts.

Known issues

The honest list lives in docs/BACKLOG.md. Worth knowing before you install:

• Panel approvals need pairing - a widget older than 0.27.0 or a companion older than 0.29.0 cannot approve anything: the tap is refused and the terminal dialog decides. Update both, then enter the pairing code (see above). Approvals still ship off.
• GHOST-a - after a crabd restart, a session that was killed by an app restart can read working for up to 15 minutes before transcript aging retires it.
• About two dozen small cosmetic or edge-case items under "Small, known, not yet fixed".

Security and privacy

Localhost-only by design. The companion reads ~/.claude read-only, never writes there, and transmits nothing. There is no telemetry, no crash reporting, no update check. SECURITY.md has the threat model, the disclosed residuals, and how to report a vulnerability.

For developers

Want to contribute? Read CONTRIBUTING.md first: it is short, and it explains the four rules every change is held to.

Design rules that drive most decisions: honest failure (unknown is null or an em-dash, never 0, never a stale value re-served), every alert must survive a healthy night (each threshold is replayed against real data, each gate mutation-proven), contract first (schema marks the last breaking shape; additive fields are detected by presence), and a fixed vocabulary, never free text.

Tests, all headless:

python -m unittest discover -s companion\tests -t companion\tests
python -m unittest discover -s notifier\tests  -t notifier\tests
python -m unittest discover lighting\tests
pwsh -File .\setup\tests\RunTests.ps1
node widget\tests\test_ordering.js

License

MIT. See LICENSE. SideCrab is an independent hobby project and is not affiliated with or endorsed by Anthropic or Corsair; Claude and Claude Code are Anthropic's marks and iCUE and Xeneon are Corsair's, named here only to say what the panel works with.