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 29 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 App Store — macOS, with an iPhone/iPad companion on the same listing. The Mac app carries its own Swift daemon and needs no Node.js.
For the CLI daemon, terminal dashboard, and external integrations:
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.
The two installs compose. Each is complete on its own: the Mac app is a fully standalone dashboard, and the npm CLI is a fully standalone daemon + terminal dashboard. Install both on the same Mac and the app automatically attaches to the CLI daemon, adding the CLI-tier capabilities on top — Claude subscription quota gauges and ADB-driven Android/e-ink surfaces. The legacy managed-terminal tier also retains PTY session launching and cross-machine remote attach while daemon-first replacements are designed and validated. The exact split is documented in docs/appstore-feature-matrix.md.
The CLI path needs: macOS 15+, Windows 11 (guide), or Linux (guide); Node.js 22, 24, or 26; and at least one supported agent. The native App Store dashboard instead requires macOS 26+ and needs no Node.js. iPhone/iPad companions require iOS/iPadOS 17+.
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 daemon install # installs/refreshes hooks and starts the daemon
claude # or: codex · opencode · kiro-cliAgentDeck observes normal agent commands through lifecycle hooks and native event channels.
Check the installed agent versions and the hook compatibility baselines without launching a managed terminal:
agentdeck diag agentsImportant
agentdeck claude, agentdeck codex, agentdeck opencode, and
agentdeck monitor are legacy compatibility commands. They remain functional,
and no removal date is set. For ordinary local sessions, prefer
agentdeck daemon install, then run the agent normally. Managed-only features
such as remote attach, --weight, AGENTDECK_<AGENT>_ARGS, terminal UI
steering, and terminal telemetry do not yet have daemon-first equivalents.
Share workflows and help design replacements in
Discussion #278;
implementation and release work remain tracked in
#273.
Kiro has no managed form at all — see Agents for why, and for what its sessions do and do not report.
The legacy managed compatibility path can attach agents on several machines to
one deck on a main node. --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.
These products are maintained and released by the AgentDeck project. They attach to the same daemon and can be added in any order:
| Official product / integration | How to attach |
|---|---|
| macOS AgentDeck Dashboard | Download on the App Store — the SwiftUI dashboard carries its own daemon, so it needs no Node.js |
| iOS / Android AgentDeck Companion | iPhone/iPad use the same App Store listing; Android installs from Google Play. Both pair with a daemon over the LAN. |
| AgentDeck ESP32 Dashboard Firmware | Flash LCD panels and the TRMNL 7.5" e-ink from puritysb.github.io/AgentDeck/flash/ or run agentdeck esp32 flash <board>. After the first USB flash, supported boards update over Wi-Fi OTA. |
| Official Stream Deck integration | Install for Stream Deck / Mini / XL / Plus / + XL from the Elgato Marketplace. |
| Official Ulanzi integration | Install from the Ulanzi Studio Marketplace. Version 1.2.0 is live; 1.3.0 was submitted for review on 2026-09-12. Both cover D200H keys and D200X LCD keys. D200X encoders remain unsupported. See the listing/review status or build it yourself. |
| Official device integrations | Pixoo64, TC001, Timebox, and iDotMatrix are driven by the daemon — see docs/devices.md. |
Android, Stream Deck, and Ulanzi are companion surfaces. They talk to the AgentDeck daemon the way an OBS plugin talks to OBS, and never embed it. Keep the daemon running on the same computer/network; without it these surfaces show an offline or searching state.
Independent projects keep their own product identity, repository, releases, and support tracker. They integrate through an allow-listed AgentDeck Surface Protocol v1 profile rather than making the daemon's entire internal WebSocket API a public contract.
| Project | Level | Surface profile | What it does |
|---|---|---|---|
| Pocket Daily Reader | Community | portable-reader/v1 |
Independent offline-first e-reader. Pulls bounded cards, Glance, and licensed SD learning-pack updates, records choices offline, and keeps AgentDeck as an invisible sync source. Published manifest remains community / untested. |
| companion-module-agentdeck | Community | companion-control/v1 |
Independent Bitfocus Companion module for session tiles, approval controls, usage gauges, and status creatures (by @houtacheng). |
Pocket Daily's Feed/Outbox/telemetry/resumable-OTA runtime works with both the Node CLI daemon and the macOS app's standalone Swift daemon. Node additionally provides adaptive personal card modules and daemon-rendered Glance Frame pixels; see the runtime status.
Compatibility levels are Community, Verified Compatible, and Official. Verified Compatible means a named release passed the published manifest and conformance suite; it does not transfer maintenance or imply endorsement. Official means AgentDeck-maintained. Definitions, version negotiation, capability policy, OTA isolation, and the integration manifest schema are in the Surface Protocol.
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 |
 |
 |
| TRMNL 7.5" e-ink — 7.5" 800×480, custom firmware, updates over Wi-Fi OTA | Android e-ink — reader-specific layouts with partial refresh |
 |
 |
| EPD47 e-ink — 4.7" 960×540 grayscale with touch, quiet differential repaints | NM-EPD-420 e-ink — 4.2" tri-color glance; red ink is spent only on attention |
 |
 |
| Apple — SwiftUI on macOS, iPhone, and iPad | Pixoo64 — 64×64 pixel-art terrarium and usage HUD |
→ Browse all 29 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
- Weather context — optional Apple Weather conditions on the macOS Dashboard; attributed seven-day Glance and offline cues for portable readers
- Subagent count — how many children a session has running, beside its own state
- 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 | How its state is read |
|---|---|---|
| Claude Code | Supported (primary) | Lifecycle hooks |
| Codex CLI | Supported | Lifecycle hooks + rollout JSONL |
| Codex Desktop | Observed (macOS; Windows verification pending) | Lifecycle hooks + rollout JSONL |
| OpenCode | Supported | Observer plugin (SSE) |
| Kiro CLI / IDE | Observed | Kiro's own transcript, polled |
| Antigravity | Observed (CLI daemon) | Passive process/session observation |
| OpenClaw | Experimental | Gateway |
State comes from agent-native lifecycle and event channels — hooks for Claude Code and Codex, OpenCode SSE, the OpenClaw Gateway, Kiro transcript polling, and passive Antigravity process/session observation — rather than terminal-screen scraping. Deprecated CLI-managed sessions retain an optional terminal UI observer only for real mode/diff/option affordances that those lifecycle payloads do not expose.
Kiro is observed, never managed. Run kiro-cli or the Kiro IDE exactly as
usual; there is no agentdeck kiro command, because Kiro's hook surface does not
fire for a CLI chat turn — its global standalone hooks load and then produce
nothing for a real turn. AgentDeck reads Kiro's own transcript instead, which
sets two honest expectations: a Kiro session shows up seconds late rather than
instantly, and it reads idle rather than processing, because a transcript
only gains its assistant record once the reply has landed. On the sandboxed
macOS app it needs a one-time folder grant in Settings → Integrations → Kiro CLI;
without one it observes nothing rather than guessing.
Whose model answered is a separate question from which agent it is. A Claude Code session pointed at a third-party endpoint is still Claude Code — same binary, same hooks — so it keeps its agent identity and the surfaces mark the provider separately, only when the harness and the endpoint are both known and disagree.
┌── Daemon (port 9120, sole hub) ──┐
Stream Deck Plugin ◄── WS ──►│ │
Ulanzi Studio keys ◄── 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, Ulanzi D200H/D200X keys, Android, Apple) can steer when a
managed session supplies real options, or when an observed session advertises a
real answer-delivery path (liveAnswerable) through an ask-gate or terminal
injection. Otherwise the prompt is display-only. On macOS the SwiftUI app ships a
standalone in-process Swift dashboard daemon with no Node.js. The PTY Session
Bridge remains available as a CLI compatibility feature until its managed-only
workflows have validated daemon-first replacements.
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 · Surface protocol · Internal bridge protocol · Daemon · Gateway protocol · Testing |
| Evaluation | Why APME · APME · Pipeline |
| Design | DESIGN.md · Tokens · Resource map |
| Project | Roadmap · Releasing · Changelog · Agent harness · AI-assisted maintenance |
Bug reports, hardware verification, documentation fixes, and focused pull requests are welcome. Start with CONTRIBUTING.md, use the private process in SECURITY.md for vulnerabilities, and follow the Code of Conduct in project spaces. Maintainer use of coding agents is human-owned and documented in AI-assisted maintenance.
Independent integration submissions are welcome. Start with the Surface Protocol, publish an integration manifest in your own repository, and keep support links pointed at the project that owns the code. Listing an integration does not make AgentDeck its maintainer.
One compatibility major across every artifact; target minor/patch versions and
delivery tags advance independently. A minor adds substantial backward-compatible
features, while a patch carries small fixes. Root VERSION anchors
the compatibility major but is not a minor/patch ceiling — policy in RELEASING.md,
builds on Releases.
Any two numeric X.Y.Z artifacts are mutually compatible exactly when their
major X matches — a 1.0 device keeps working against a 1.2 daemon and vice
versa. The table records publicly available versions; store review candidates are
identified separately below. Matching minor versions are never a requirement.
| Artifact | Publicly available | Connects to |
|---|---|---|
npm CLI + daemon (@agentdeck/*) |
1.3.4 | — (the hub every client dials) |
| Apple app (macOS · iPhone/iPad) | 1.3.0 | its built-in Swift daemon, or any 1.x daemon |
| Android app | 1.3.1 APK / Play | any 1.x daemon |
| Stream Deck plugin | 1.2.0 | any 1.x daemon |
| Ulanzi D200H/D200X plugin | 1.2.0 | any 1.x daemon |
| ESP32 firmware (12 boards) | 1.3.0 | any 1.x daemon (serial or Wi-Fi) |
| Channel | Tag | Status |
|---|---|---|
npm — @agentdeck/setup |
npm-v* |
1.3.5 live — all four package versions, latest tags and source commit registry-verified on 2026-09-15. Windows console-free autostart, safe supervision probes and e-ink broadcast metrics; installed three-mode verification recorded in #314. |
| Apple App Store — macOS + iPhone/iPad | apple-v* |
1.4.0 (7001) submitted for review on both platforms on 2026-09-21; automatic release after approval. Release and verification receipt. 1.3.2 remains the last verified live version. |
| Elgato Marketplace — Stream Deck plugin | streamdeck-v* |
1.4.0 submitted for review on 2026-09-21 (Maker Console: Pending review · 1.4); automatic publication off for the processed-package check. 1.3 remains the last verified public version. Record. |
| Ulanzi Marketplace — D200H / D200X plugin | ulanzi-v* |
1.2.0 remains public, rechecked 2026-09-15. 1.3.0 remains under review, verified on 2026-09-21; the requested in-place 1.4.0 replacement is prepared but has not been saved (record). |
| GitHub Release — Android APK | android-v* |
1.4.0 — versionCode 18, APK published 2026-09-21. Google Play submission is separate. |
| GitHub Release — ESP32 firmware | esp32-v* |
1.3.0 — 62 assets published 2026-09-13 for all 12 boards. All 60 firmware binaries were downloaded and verified against SHA256SUMS and manifest size/hash fields. Adds TTGO Usage default, T-Embed approval queue and T-Display-S3-Pro pinned-session/waiting-list interaction. |
| Google Play — Android AAB | android-v* |
1.3.1 live — versionCode 17, published 2026-09-13 at 21:08 KST after review. Console reports “Available on Google Play”; 100% rollout and 177-country coverage retained. Listing assets and runbook: marketplace/play/. |
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.
Default CI runs Vitest, with path-scoped PR checks compiling Android (Gradle) and the
ESP32 render trees (host sim); 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.