Stop Chatting. Start Steering.
AgentDeck puts your AI coding agents on a physical control surface. Every key is a session: it shows which agent is running, in which project, and whether it is working, waiting on you, or idle — and it repaints itself as that changes. Press a key to jump in.
It started on an Elgato Stream Deck+ and now drives 26 surfaces at once — decks, tablets, e-ink readers, ESP32 panels, LED matrices, and your terminal.
▶ Watch the demo · 🌊 Project website · Devices · Live preview · Design system
You do not need a Stream Deck to try AgentDeck. The daemon is the product; the decks are one way to look at it. If you have a terminal, you can see it working in about a minute.
For the standalone native dashboard, download AgentDeck Dashboard from the Mac App Store. It carries its own Swift daemon and needs no Node.js.
For the CLI, terminal dashboard, and PTY steering:
npx @agentdeck/setupThis installs the agentdeck CLI and the local daemon, and registers the lifecycle
hooks for whichever agent CLI you already have. Nothing else is required — the
Stream Deck app, Stream Deck hardware, and Xcode tools are checked and reported,
but never block the install.
You need: macOS 15+ (or Windows 11 — see docs/windows.md, or Linux — see docs/linux.md), Node.js 22+, and at least one agent CLI (Claude Code, Codex, or OpenCode).
agentdeck dashboardA full terminal dashboard: your live sessions, a braille-rendered terrarium, usage gauges, and the timeline. This is the zero-hardware way to see whether AgentDeck is useful to you.
agentdeck claude # or: agentdeck codex · agentdeck opencodeYour agent runs exactly as before — the bridge is transparent, and if it is off, nothing changes. Already have an agent running in another terminal? The daemon observes it through hooks; you do not have to launch it through AgentDeck.
Running agents on several machines with one deck on a main node? Sessions can
attach to the main node's daemon. --remote-daemon is the opt-in switch — without
it nothing leaves the machine and the default stays local-only:
agentdeck claude --remote-daemon --daemon-host mainnode.lan # explicit host (recommended)
agentdeck claude --remote-daemon # or auto-discover via mDNS on the LANReverse control rides the worker's own outbound socket (the daemon never dials
back), so a worker only needs to reach the main node's port 9120 — for
SSH-only workers, ssh -L 9120:localhost:9120 mainnode then
agentdeck claude --remote-daemon. The main node must run the Node CLI
daemon (the macOS-app Swift daemon does not support remote attach and is
never auto-selected). See
docs/daemon.md § Remote attach.
Any of these attach to the same daemon, and you can add them in any order:
| Surface | How to attach |
|---|---|
| Stream Deck / Mini / XL / Plus / + XL | One click from the Elgato Marketplace — or cd plugin && streamdeck link bound.serendipity.agentdeck.sdPlugin from a checkout |
| Ulanzi D200H | Install the plugin in Ulanzi Studio — see plugin-ulanzi/VERIFY.md |
| macOS app | Download on the Mac App Store — the SwiftUI dashboard carries its own daemon, so it needs no Node.js. iPhone/iPad companion not released yet |
| Android tablet / e-ink | Signed APK from Releases — see docs/android.md |
| ESP32 panels · InkDeck e-ink | Flash firmware, then Wi-Fi OTA — see docs/esp32.md |
| Pixoo64 · TC001 · Timebox · iDotMatrix | agentdeck pixoo scan / agentdeck timebox scan — see docs/devices.md |
The Stream Deck and Ulanzi plugins are thin clients. They talk to the AgentDeck daemon the way an OBS plugin talks to OBS, and never embed it. With no daemon running they show an OFFLINE state pointing at the install command.
Full build-from-source and manual steps: docs/install.md.
 |
 |
| Stream Deck+ — one key per session, plus encoders for volume, quota, and launch | Ulanzi D200H — 14 keys and a 960×540 LCD, driven by the official Ulanzi Studio plugin |
 |
 |
| InkDeck e-ink — 7.5" 800×480, custom firmware, updates over Wi-Fi OTA | Android e-ink — reader-specific layouts with partial refresh |
 |
 |
| Apple — SwiftUI on macOS, iPhone, and iPad | Pixoo64 — 64×64 pixel-art terrarium and usage HUD |
→ Browse all 26 surfaces, with live renderer previews
- Session per key — agent, project, and state on every key, repainting live
- Distinct attention state — see at a glance which agent is waiting on you
- Answer without switching windows — YES / NO / ALWAYS with semantic colors
- Interrupt — STOP sends Ctrl+C to a runaway agent
- Switch modes — cycle Plan / Accept Edits / Default
- Quick actions — GO ON / REVIEW / COMMIT / CLEAR, plus custom prompt templates
- Usage gauges — subscription quota with reset countdowns
- Voice — push-to-talk and wake word, on-device via Apple SFSpeech, no model download
- Display sync — host sleep dims every surface; wake restores them
| Agent | Status |
|---|---|
| Claude Code | Supported (primary) |
| Codex CLI | Supported |
| OpenCode | Supported |
| OpenClaw | Experimental |
State comes from agent-native lifecycle and event channels — hooks for Claude Code and Codex, OpenCode SSE, and the OpenClaw Gateway — rather than terminal-screen scraping. PTY parsing remains a best-effort assist for CLI-managed sessions.
┌── Daemon (port 9120, sole hub) ──┐
Stream Deck Plugin ◄── WS ──►│ │
D200H via Studio ◄── WS ──►│ │
Android Dashboard ◄── WS ──►│ WS Server + mDNS + Device Mods │
Apple Dashboard ◄── WS ──►│ Gateway Proxy + Usage Relay │
TUI Dashboard ◄── WS ──►│ Pixoo + ESP32 + Timebox + SSE │
ESP32 Display ◄ Serial ►│ │
Pixoo64 LED ◄ HTTP ──►└───────────────┬───────────────────┘
│ aggregates
┌── Session Bridge (port 9121+) ──┐
User's Terminal ◄─ stdio ───►│ PTY Manager → agent CLI │
Agent Hooks ─── HTTP ───►│ Hook Server → State Machine │
└──────────────────────────────────┘
One daemon aggregates every session and broadcasts to every surface. Interactive surfaces (Stream Deck, D200H, Android, Apple) can steer when a PTY-managed session supplies real options; observed sessions remain display-only. On macOS the SwiftUI app ships a standalone in-process Swift dashboard daemon with no Node.js. The PTY Session Bridge remains a CLI feature.
Details: docs/architecture.md.
Start with the website — puritysb.github.io/AgentDeck carries the rendered device catalog, live renderer previews, the design system, and build health.
| Using it | CLI reference · Configuration · Troubleshooting · Windows · Linux |
| Surfaces | Hardware matrix · Stream Deck layout · Devices · ESP32 · Android · Apple · TUI |
| Internals | Architecture · Daemon · Protocol · Gateway protocol · Testing |
| Evaluation | Why APME · APME · Pipeline |
| Design | DESIGN.md · Tokens · Resource map |
| Project | Roadmap · Releasing · Changelog · Agent harness |
One major.minor compatibility line across every artifact; target patches and
delivery tags advance independently without patch-order constraints. Root VERSION anchors the compatibility line but is not a patch ceiling — policy in RELEASING.md,
builds on Releases.
| Channel | Tag | Status |
|---|---|---|
npm — @agentdeck/setup |
npm-v* |
1.0.12 |
| Apple App Store — macOS + iPhone/iPad | apple-v* |
Live on both platforms: macOS 1.0.3 (4101) and iPhone/iPad 1.0.2 (4002); 1.0.4 (4501) in review on both platforms with the local-network security fix (issues #145, #149) |
| Elgato Marketplace — Stream Deck plugin | streamdeck-v* |
1.0.4 live (published 2026-08-05) |
| Ulanzi Marketplace — D200H plugin | ulanzi-v* |
1.0.2 release; submitted, review in progress (details) |
| GitHub Release — Android APK | android-v* |
1.0.6 |
| GitHub Release — ESP32 firmware | esp32-v* |
1.0.3 — one binary per Shipping board |
| Google Play — Android AAB | android-v* |
Account verified; AAB, listing copy, assets and a step-by-step console runbook ready in marketplace/play/ — app record not yet created |
pnpm install && pnpm build # shared must build before bridge/plugin
pnpm -r --parallel dev # watch mode
pnpm test # Vitest (bridge, plugin, shared, hooks)
pnpm test:report # unified: Vitest + Android + Apple + RobotFour test frameworks cover the tree — Vitest for the Node/TS packages, JUnit +
Robolectric for Android, XCTest for Apple, and Robot Framework for ESP32 hardware.
Only Vitest runs in default CI; the rest go through scripts/test-report.sh. Current
results are published at /reports/.
Working on AgentDeck with a coding agent? Start at CLAUDE.md and docs/agent-harness.md — they map how each agent enters the repo and which skills it should use.
Full guide: docs/testing.md · Build from source: docs/install.md.
MIT — see LICENSE.
Independent project. Not affiliated with Anthropic, OpenAI, Google, Elgato, DIVOOM, or any other third party referenced here. All trademarks belong to their respective owners. Full notices in ATTRIBUTION.md.