Run 8 Claude Code Agents From One Stream Deck (Free Download)

I had a Stream Deck sitting in a drawer. Bought it for my gaming sessions, ignored it for a year, kept not quite throwing it away.

Meanwhile I’d drifted into running four or five Claude Code sessions at once, and I was spending far too much attention on the wrong thing. Not on the work, on the surveillance of it. Cycling terminal windows to check whether anything had finished, whether anything was stuck, which one had been sitting on a yes/no for eleven minutes while I wrote code in a different tab. Run one agent and the terminal is fine. Run five and the bottleneck stops being the model and becomes your awareness of what is running.

What I wanted was to stop checking and start glancing. Eight things, visible at rest, answerable with one press. Which is a description of a Stream Deck, so the drawer stopped being an option.

There are two halves to it. Seeing the agents, and driving them. Different tools, so I’ll do them in order.

Part 1: Seeing them

1. Install the daemon

npx @agentdeck/setup
agentdeck daemon install

AgentDeck is MIT licensed. The deck is not the product, the daemon is. It runs on port 9120, subscribes to Claude Code’s lifecycle hooks, aggregates every session into one state model, and broadcasts it to any surface you attach. It reads the agent’s own event stream rather than scraping your terminal, which is why the states are true instead of inferred. Node 22+, on macOS 15+, Windows 11 or Linux.

2. Check it with no hardware

agentdeck dashboard
claude

Run your agents exactly as you normally would. The TUI shows live sessions, quota gauges and a timeline. One minute to find out whether ambient agent state changes how you work. If it doesn’t, stop here and you’ve spent nothing.

3. Attach the deck

Install the official AgentDeck plugin from the Elgato Marketplace. It talks to the daemon over WebSocket the way an OBS plugin talks to OBS, so keep the daemon running.

You get one key per session, up to eight on a Stream Deck+, repainting as state changes: agent, project, state, and how many subagents that session has spawned underneath it. YES / NO / ALWAYS on permission prompts, STOP to fire Ctrl+C at a runaway, cycle Plan / Accept Edits / Default, quota gauges with reset countdowns on the encoders.

Part 2: Driving them

That covers monitoring. It does not cover the twenty commands I was still typing by hand every day. So I built a profile and a plugin. Both free for subscribers, both below.

The Download is available only for Subscribers:

4. Install the profile

Double-click the .streamDeckProfile for your device. It appears in the profile dropdown at the top of the Stream Deck app.

You haveUseClassic or MK.2the MK.2 profileXLthe XL profileStream Deck+the Plus profileStream Deck+ and the pluginthe Plus (Plugin Dials) profile

One thing catches everyone: importing a profile you already have adds a second copy rather than replacing it. Delete the

old one first, under Profiles in Stream Deck preferences.

Eight categories, seventy nine actions, every action scored 1 to 5 by how often I actually reach for it. The score isn’t decoration. It decides what gets promoted to the home page and what gets cut when a smaller deck runs out of room, so the layout reorganises itself per device instead of me hand placing keys three times. The whole thing is generated from one spec file, so adding a key is one line and a rebuild.

The category I didn’t expect to use most is Prompts. Keys for things like investigate the root cause before proposing a fix, or finish this end to end, then tell me what you didn’t do. A shortcut deck can only send key combinations. These are sentences I was retyping ten times a day, and they turned out to be the highest leverage keys on the whole thing. On an agent surface the useful unit isn’t the shortcut, it’s the instruction.

5. Install the plugin, if you have dials

Double-click com.nervegna.claude-code.streamDeckPlugin. A Claude Code category appears in the action list.

Then let it type: macOS blocks synthetic keystrokes, so enable Stream Deck under System Settings, Privacy & Security, Accessibility. If you’ve ever used Stream Deck’s Hotkey action it’s already on. macOS only for now, since the keystrokes go through AppleScript.

Why it exists: a profile dial can send keystrokes, but the touch strip stays a static image and you get no feedback as you turn. Drop Command Dial onto a dial and the strip updates live with the command name and a position bar. Turn to scroll, press to run. In its settings, Category picks the list, or choose Custom list and write your own as Label | text to send. Send as Paste is fast and exact but takes your clipboard; Type leaves it alone. Focus app is optional: put Terminal, iTerm or Ghostty there and the dial pulls that app forward before sending, so it fires even from a browser.

For keys, stay on the profile. Only reach for the plugin’s Command Key when you want something the catalog doesn’t have, or a key you can retitle without a rebuild.

6. The Smart Setting actually worth five minutes

In Stream Deck preferences, open Profiles, select the Claude Code profile, and set Application to your terminal. The deck switches to it the moment your terminal is in front and switches away when it isn’t. You stop thinking about profiles entirely.

Organising your own keys

Keep the structure even if you replace every command in it.

Home page holds only what you press without thinking: interrupt, permission mode, plan, rewind, commit. If you have to look for it, it doesn’t belong there. Everything else goes in a folder, one folder per kind of work rather than per tool, because categories like Review and Git+Ship survive a change of CLI and a folder named after one tool doesn’t. On a Stream Deck+ the dials stay live inside folders, so the same four are available wherever you are. On an XL, use fewer folders: thirty two keys keeps two dozen commands flat, and flat beats nested whenever it fits.

Two gotchas. Option+P, Option+T and Option+O (switch model, extended thinking, fast mode) only reach Claude Code if your terminal sends Option as Meta: Terminal.app under Settings, Profiles, Keyboard, or iTerm2 with Left Option set to Esc+. And a few keys deliberately don’t press Return, including Remember, Mention, Add Dir, Set Goal and Side Ask, because you still have something to type.

One design note before you rearrange everything

Consent has ergonomics. Making approval a one-tap gesture is a decision with consequences, because the friction was doing some work for you. If ALWAYS ALLOW sits under your resting hand, you’ve decided something about how carefully you review agent output, whether you meant to or not. My rule: continuation cheap, destructive and irreversible expensive. Don’t put the delete key next to the go key.

If you build a better category layout than mine, send it over. The spec file is the point.

Thanks for reading Sorted Pixels! This post is public so feel free to share it.