AgentStreamDeck

A physical dashboard for your AI coding agents. Monitor OpenCode, Claude Code, Codex CLI, GitHub Copilot, Gemini CLI and Cursor CLI on an Elgato Stream Deck. See who is working or needs you, press a key to return to that window, and let Jelly bring your spare buttons to life.

⭐ Find this useful? Star AgentStreamDeck on GitHub to help more developers discover it.

☕ Support Ryan’s projects on Buy Me a Coffee. Any amount, one-time or monthly, helps fund development, hardware testing and videos. Thank you for supporting this hobby.

Get started · Watch the video · All features · CLI reference · UI options · Visual gallery · Documentation

Watch AgentStreamDeck on a real Stream Deck

▶ Watch the YouTube demo: AI coding-agent status and one-touch window switching. This is the original OpenCode hardware walkthrough, recorded before later Jelly and customization additions. The source-rendered hero above and full animation gallery show the broader current feature set. The thumbnail opens YouTube; GitHub README pages do not play embedded YouTube iframes.

Keep your attention on the work

Running several coding agents means several windows to check. AgentStreamDeck gives each session a physical key with its project label, agent icon and live status.

• Know where you're needed. Animated status keys distinguish work in progress, idle sessions and supported input requests.
• Get back with one press. Focus the session's Windows window; minimized windows are maximized and brought forward.
• Keep your usual workflow. Launch your CLI or editor normally after installing its integration. No special launcher, Elgato plugin or MCP server required.
• Give spare keys some personality. Jelly, an offline companion, plays on unused buttons and reacts when you tap him.

The hero above uses the actual renderers on a simulated deck. The video demo shows the OpenCode workflow on hardware.

Get started

1. Check your setup

Plug in your deck and quit the Elgato Stream Deck app from the system tray so AgentStreamDeck can use it.

2. Install and start

python -m pip install --upgrade agentstreamdeck
python -m ocdeck install

The second command registers and starts the background broker for your user, including startup at login. It also installs the OpenCode plugin if opencode is on PATH. No repository checkout is needed. The commands use python -m so a missing Scripts folder on PATH won't get in your way.

3. Connect your agent

For Claude Code, run this from a project you want to monitor:

cd C:\Projects\MyApp
python -m ocdeck harness-install claude
claude

For another agent, choose its profile below. Repeat hook installation for each project you want to monitor. Existing unrelated hooks are preserved. OpenCode uses its global plugin, so just launch opencode after step 2; if it wasn't on PATH during setup, run the install command again once it is.

For example, use python -m ocdeck harness-install codex, then review and trust the hooks in Codex using /hooks. Agent-specific setup and coverage explains prerequisites and limitations.

4. Try a key

Start an agent in the configured project, send it a task and watch its key change. Press the key to return to that session. Use a separate OS window for each monitored session; several tabs in one terminal window can make focus ambiguous.

python -m ocdeck status

Need more detail? Installation guide · Troubleshooting · Remote and WSL setups

Supported agents

Follow the dedicated setup guide for OpenCode, Claude Code, Codex CLI, Copilot CLI, Copilot in VS Code, Gemini CLI, or Cursor CLI. Each includes install commands, exact shipped hook mappings, verification and removal.

The integrations above share the same deck, but their event coverage differs. These are the default visual signals:

Activity-only integrations can still look busy while waiting for approval. A green key doesn't guarantee that no input is needed. Input counts appear only when the integration supplies enough information.

Pressing an agent key requests window focus. It never types a reply or approves a tool. Windows can restrict foreground activation; the status output includes the last focus result for diagnosis.

Make it yours

The physical deck is the UI; preferences are configured through the CLI and JSON. See every UI control, every appearance field and default, and all CLI arguments.

Choose recognizable agent logos, project labels, layouts, color palettes and animation styles. Apply a preset across the deck or give individual keys their own look.

python -m ocdeck appearance --preset neon --layout harness

Restart the broker after saving appearance changes. You can preview changes before saving, export a favorite look, or turn animation off. Sound alerts and Windows notifications are optional and off by default.

Appearance gallery and settings · Configuration, alerts and maintenance

Want your Mini beside your screen? The 3D-printable side monitor mount includes separate STL parts, a reinforced wing, a 5° locking hinge, and printing instructions.

Meet Jelly

Jelly makes a home on your spare buttons. He stretches, dances, naps and changes mood with the rhythm of your coding sessions. Tap him for a wobble, cheer or little “Boop!” His thoughts and personality run offline using session activity metadata, without reading your prompts or source code.

With two free keys, Jelly can point to a steaming coffee cup and ask “Coffee?” at a random interval of 1–3 hours. Tap Jelly five times within one minute to start the same routine early when two keys are free. The invitation lasts 60 seconds; pressing Jelly or the cup opens Ryan's Buy Me a Coffee page and dismisses it. The preview speeds up the wait. Agent controls always take priority.

Prefer a quieter deck? Set "jelly": {"coffee": false} to disable coffee invitations or "jelly": {"enabled": false} to turn Jelly off. Merge these preferences into your existing configuration and restart the broker.

Jelly's personality and behavior · Complete Jelly settings · Every action, mood and hop · Tap and coffee interactions

Stay up to date

When an update is available, Jelly settles down with rainbow colors, a red exclamation point, a green upgrade arrow and “Update available” beneath him. He moves at most once every 30 seconds so you can read it.

Press the marked Jelly to install the detected update and restart the broker. Checking for updates never installs anything by itself. You can also update with:

python -m pip install --upgrade agentstreamdeck

A running broker with upgrade monitoring automatically restarts after the new package finishes installing. Use the same Python environment as the broker. First-time setup still needs python -m ocdeck install; older installations may need one restart to enable monitoring. Upgrade details and opt-outs

Release notes · Upgrading from AgentDeck

Explore every feature

More ways to make it yours

Browse layouts, themes, harness logos, labels, typography, borders, brightness and mixed-key examples. Each gallery links to the settings that produce it. These are renderer demonstrations; physical USB speed depends on your deck and active keys.

Documentation shortcuts

• Start here: first run, practical tutorials, FAQ, troubleshooting.
• Complete references: all commands and flags, broker JSON and environment, appearance settings, Jelly settings.
• Advanced workflows: local-model and compatibility launchers, WSL/SSH/container boundaries, local HTTP API.
• Browse everything: documentation index, feature hub, integration hub, media gallery.

Need a hand?

python -m ocdeck doctor --no-device --json
python -m ocdeck report --output agentstreamdeck-report.zip --lines 200

Start with the troubleshooting guide. On Windows, configuration and logs live under %USERPROFILE%\.opencode-deck unless you've set OCDECK_HOME; the main log is broker.log. Review diagnostic reports before sharing them in a GitHub issue.

The controller runs locally. Online update checks can be disabled with "check_updates": false. Configuration and removal instructions cover alerts, startup, backups and uninstalling integrations.

Build with us

Adapter improvements, bug reports and hardware testing are welcome. See CONTRIBUTING.md for development setup, the architecture for the internals, and the documentation index for deeper guides.

CI tests Windows and Ubuntu with Python 3.11/3.13, including package installation and upgrade behavior. USB hardware and interactive window focus also need real desktop testing; verification details distinguish that from automated coverage.

Licensed under Apache 2.0. Agent names and logos belong to their respective owners; see third-party notices.