Skip to content
web-workers-comPublic

About

Control Claude Code from your Elgato Stream Deck: live session status, one-key permission answers, a prompt queue, plan limits and a full-deck alert when Claude needs you.

Topics

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Andon Deck for Claude Code

Control Claude Code from your Elgato Stream Deck. Free, open source, MIT. Website: andondeck.com

Andon Deck on a Stream Deck XL: session status, permission answers, the prompt queue and plan limits

An andon is the signal light over a machine on a factory floor: green while it runs, amber when someone is needed, red when it stopped — readable from across the hall. Every key here works the same way.

See what Claude is doing, queue the next prompt without interrupting the current turn, answer permission requests with one key, switch between projects, fire off background tasks, and keep an eye on context pressure — all from the deck.

Status: 1.0.0. Verified against Claude Code 2.1.319 and Stream Deck 7.4. Download it from Releases or build it yourself with the steps below.

How it works

Claude Code supports HTTP hooks: it POSTs lifecycle events to a URL, and the JSON it gets back is the hook's decision. Andon Deck runs that endpoint inside the Stream Deck plugin itself.

Claude Code                              Stream Deck plugin
     │                                          │
     ├─ SessionStart / UserPromptSubmit ───────►│  status, project, model
     ├─ PreToolUse / PostToolUse ──────────────►│  current tool, counters
     │                                          │
     ├─ PermissionRequest ─────────────────────►│  held open while an
     │◄──────── { behavior: "allow" } ──────────┤  Approve key is on screen
     │                                          │
     ├─ Stop ──────────────────────────────────►│  queue has an entry?
     │◄──── { decision: "block", reason: … } ───┤  → Claude keeps going
     │                                          │
     └─ Stop (async, idle) ────────────────────►│  long-poll; exit 2 wakes
                                                   an idle session

No keystroke injection, no screen scraping, no window focus games. If Stream Deck is closed, every hook is configured with onFailure: "continue" — Claude Code behaves exactly as if the plugin were not there.

Actions

Action What it does
Claude Status Live state: idle, working, waiting on you, compacting, failed. Shows the current tool, elapsed turn time and the queue count. Press to follow whichever session needs attention.
Queue Prompt Stores a prompt locally and hands it over the moment the current turn ends. Can queue whatever you last copied, so an error message goes from clipboard to Claude in one press.
Queue Control Browse, promote, drop or clear queued prompts. On a Stream Deck +, rotate to scroll.
Approve / Deny / Always Answers Claude Code permission requests from the deck, with an optional confirm-twice guard. Always also saves the same rule Claude Code's own "Yes, and don't ask again" would, and shows that rule on the key before you press it.
Prompt One-tap prompts, queued and fed to Claude when its turn ends. Slash commands cannot travel through a hook — Claude Code only runs them when typed — so the bundled layouts use Stream Deck's built-in Text action for /compact, which types it into the focused terminal.
Session Switcher Pin which session the deck controls, or cycle through everything that is open.
Run Task A one-shot claude -p run in the background. Never touches your open session.
Session Slot Gives one session a key of its own, held for that session's whole life. A row of them is a board of everything running.
Launch Claude Opens a terminal with an interactive session in a folder you choose.
Usage & Timer Turn timer, tool calls, token counts, context pressure, and plan limits (5-hour and weekly, with a reset countdown, and a warning when the current pace runs out before the reset) for claude.ai subscriptions. History charts tokens by hour for today and by day for the week, read straight from Claude Code's transcripts, so they are full from the first minute. On a dial, plan limits draw how they moved.
Autopilot Approves tool calls for a set stretch of time, then switches itself back off.
Stop Claude Emergency brake: blocks every further tool call so Claude winds down and reports back.
Model Shows the session's model and switches it at the next turn boundary.
Connect Claude Code One-time setup. Installs the hooks, shows bridge health and every setting.

Autopilot and the brake

Two things only the hook bridge can do.

Autopilot answers PreToolUse with allow for a window you choose — read-only tools, or everything. It differs from a permission mode in the ways that matter when you are not watching: it is armed from a key, the key shows what is armed and counts the window down, and one press turns it off.

Stop Claude is the brake. No hook can interrupt a turn already in flight, but PreToolUse can deny everything that comes next, which stops the agent touching anything further and makes it wind down and report where it got to. The brake outranks autopilot — arming one cannot defeat the other — and it releases itself once the turn ends.

Auto-compact and plan limits

Under Connect Claude Code you can set the point at which Claude Code compacts on its own (it writes Claude Code's autoCompactWindow setting; "Leave as configured" never touches it). The Context key then fills up against that threshold.

Plan limits are only reported to Claude Code's status line, so Andon Deck places a small relay there. It forwards the snapshot to the deck in the background and then runs the status line you already had, unchanged. Unticking Plan limits, or removing the hooks, puts your own status line back.

Plan limit and usage keys, and the same on Stream Deck + dials

Ready-made profiles

Ready-made layouts for Stream Deck Mini, Neo and Stream Deck

Every Stream Deck with keys gets a layout built for its grid rather than cropped from a bigger one — Stream Deck, Mini, XL, +, + XL and Galleon 100 SD (dials wired to the queue, session and usage), Neo, Studio, and the Pedal (allow · stop · deny under your feet). Stream Deck Mobile gets a layout for the 5 × 3 grid it starts with, and the Virtual Stream Deck one for its top-left 4 × 4, which stays whole at any larger size. Hold the Connect key for about a second to switch to the one for your deck. If Stream Deck has not installed it yet (it does not for a developer link), the same hold hands the profile file to Stream Deck, which offers to import it.

Rows are tasks, not categories, because that is how a deck is actually used. On the XL:

The Stream Deck XL layout

Watch     session 1   session 2   session 3   session 4   context  5h limit week limit 7 days
Answer    allow       always      deny        stop        autopilot model   /model    /context
Queue     run tests   review      commit      docs        paste    promote  drop      clear
Start     project 1   project 2   review diff today       /compact continue autopilot connect
                                                                            (all)

Reading along a row is how you work; reading down a column means nothing, so nothing is arranged that way.

How a key looks

State lives on the key's border, information lives in the middle. A Stream Deck key is a 19mm square read from the corner of your eye, so the state has to carry at a distance and the text is for when you actually look:

Key borders for working, waiting, failed, compacting and idle

Border Means
A light running the edge, green Claude is working
The whole edge breathing, amber Claude is waiting on you
A ring with a piece missing, red The turn failed
Dashes drifting, blue Compacting
Thin and still, grey Idle

Colour is reserved for machine state. Keys you press are graphite, so a lit key in a row always means Claude is telling you something rather than Stream Deck decorating a button.

Session and status keys show Clawd, Claude Code's mascot, posed for the state: walking while Claude works, a hand raised while it waits on you, asleep when idle. Action keys carry a faint Clawd behind their words, posed for what they do: cheering on Allow, arms hanging on Deny, a hand up on Stop, walking on queue and launch keys, asleep on Autopilot. Meters stay plain so their numbers have the whole key. Untick Mascot under Connect Claude Code for plain keys everywhere.

The full-screen alert across every key

When Claude asks for permission or has a question, every connected deck switches for a moment to a full-screen Clawd waving across all its keys — whatever profile it was showing. Any key takes you back to where you were, and so does answering in the terminal. A turn simply ending does not raise it. Untick Alert under Connect Claude Code to keep your decks as they are.

Install

From a release

Requires Stream Deck 7.1+.

Download andondeck-<version>.streamDeckPlugin from the latest release and double-click it. Then connect it as described below.

From source

Requires Node.js 20.5+ (24+ recommended) and Stream Deck 7.1+.

git clone https://github.com/web-workers-com/andondeck.git
cd andondeck
npm install
npm run build
npm run link

npm run link also works when the repository lives inside WSL but Stream Deck runs on the Windows host, which the Elgato CLI's own link cannot do.

Connect

  1. Drop a Connect Claude Code key onto your deck.
  2. Press it. It writes a hooks block into Claude Code's settings.json (keeping a .claude-deck.bak copy) and leaves everything else in that file untouched.
  3. Start or restart Claude Code. The status key lights up as soon as the first hook arrives.

The key's property inspector shows exactly which settings file was written, which URL the hooks use and which sessions have reported in.

Queueing, and the one thing to know about it

The Stop hook can only feed a prompt back into a turn that is still running. Queue something while Claude is working and it goes in the moment the turn ends — that is the whole trick, and it needs nothing else.

Once a session has gone idle there is nothing left to block. For that case Andon Deck can install a small generated helper (~/.claude/claude-deck/idle-wake.mjs) registered as an async Stop hook with asyncRewake. It long-polls the bridge and exits 2 with your prompt, which wakes Claude back up. It is on by default and can be switched off in Connect Claude Code → Idle wake.

Without idle wake, a prompt queued against an idle session simply waits until you send something yourself.

Working across installs

Hooks and wsl.exe both spawn commands without a login shell, and Ubuntu's .bashrc returns early when it is not interactive — so a node or claude installed through nvm, fnm, volta or bun is invisible to a bare command name, even though it works perfectly in your own terminal. Andon Deck therefore:

  • generates small shell helpers next to your Claude Code config that locate the executable at run time, covering PATH, nvm, fnm, volta, bun, asdf, Homebrew and the native installer;
  • never passes shell source through wsl.exe — its argument parsing mangles quoting badly enough to blank out $HOME. Scripts are delivered as files and only plain arguments cross the boundary;
  • detects where Claude Code actually lives rather than assuming, ranking a native install against every WSL distribution by which was used most recently;
  • repairs itself when the WSL gateway address moves or the bridge lands on a different port, re-pointing the installed hooks instead of going quietly dead;
  • reports reachability in the setup panel, so a blocking firewall is visible rather than silent.

If detection still picks the wrong install — CLAUDE_CONFIG_DIR, an unusual layout — point Connect Claude Code → Advanced → Settings file at the right settings.json.

Windows and WSL

If Claude Code runs inside WSL — the common Windows setup — two things differ, and the setup action handles both:

  • Settings live in the distribution, not your Windows profile. Hooks are written to \\wsl.localhost\<distro>\home\<you>\.claude\settings.json.
  • 127.0.0.1 inside WSL is not the Windows host under the default NAT networking. The bridge binds to all interfaces and the hook URL uses the WSL gateway address. With mirrored networking (networkingMode=mirrored in .wslconfig) plain loopback is used instead.

Every request carries a random per-installation token; requests without it are rejected with 401.

On macOS none of this applies — Claude Code is reached natively on loopback.

Notifications

Terminal notifications are opt-out: when Claude needs permission or a turn fails, the hook response asks your terminal to raise a notification (OSC 9), which Windows Terminal, iTerm2, ConEmu and others honour.

Privacy

Everything stays on your machine. The plugin talks to 127.0.0.1 (or the WSL gateway), stores queued prompts in memory only, and never sends anything to a remote service. It does not read or modify your Claude credentials. Session transcripts are read only to sample token counters, and only when they are reachable on the local filesystem.

Development

npm run watch      # rebuild and hot-reload into Stream Deck
npm test           # bridge, hook-installation and executable-location tests
npm run validate   # Elgato manifest validation
npm run link       # link the built plugin into Stream Deck (works from WSL too)
npm run profiles   # regenerate the bundled device profiles
npm run pack       # build a .streamDeckPlugin into dist/

The test suite drives the bridge over real HTTP with the same payloads Claude Code sends, including the Stop → decision: "block" chaining and the permission round trip.

See docs/architecture.md for the internals and docs/troubleshooting.md when something does not light up.

Licence

MIT. See LICENSE.

Claude and Claude Code are trademarks of Anthropic. This project is not affiliated with Anthropic or Elgato.

About

Control Claude Code from your Elgato Stream Deck: live session status, one-key permission answers, a prompt queue, plan limits and a full-deck alert when Claude needs you.

Topics

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages