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 27 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, 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.
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, ADB-driven Android/e-ink surfaces, PTY session launching, and cross-machine remote attach. The exact split is documented in docs/appstore-feature-matrix.md.
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 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. agentdeck claude, agentdeck codex, and agentdeck opencode remain
available when you specifically want a managed terminal, session weights, or
cross-machine remote attach; they are not required for ordinary local monitoring.
Kiro has no managed form at all — see Agents for why, and for what its
sessions do and do not report.
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.
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 panels and InkDeck 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 — the published 1.0.3 covers the D200H; D200X LCD keys are in the repository and ship with the next submission, and D200X encoders are not supported at all. Building it yourself: plugin-ulanzi/VERIFY.md. |
| 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 and Glance, records choices offline, and keeps AgentDeck as an invisible sync source. |
| companion-module-agentdeck | Community | companion-control/v1 |
Independent Bitfocus Companion module for session tiles, approval controls, usage gauges, and status creatures (by @houtacheng). |
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 |
 |
 |
| 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 27 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
- 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 |
| OpenCode | Supported | Observer plugin (SSE) |
| Kiro | Observed | Kiro's own transcript, polled |
| OpenClaw | Experimental | Gateway |
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. 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 ──►│ │
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 · 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 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.24 live on the registry — all four packages (shared, hooks, bridge, setup) report dist-tags.latest = 1.0.24, read from the registry itself on 2026-08-23. The release workflow publishes over OIDC with no enable flag and re-reads every package from the registry afterwards, so a green npm-v* build and the registry cannot disagree |
| Apple App Store — macOS + iPhone/iPad | apple-v* |
1.0.8 live on both platforms — build 5301, iPhone/iPad released 2026-08-22T18:41Z and macOS within the same window, each read from the store's own record rather than the approval mail. Submitted 2026-08-22; each platform is its own submission draft in App Store Connect, so one click per platform, not one for the app |
| Elgato Marketplace — Stream Deck plugin | streamdeck-v* |
1.0.6 live — published 2026-08-18, status: published on the product page's own payload |
| Ulanzi Marketplace — D200H / D200X plugin | ulanzi-v* |
1.0.3 live — submitted 2026-08-07, published on or before 2026-08-24, and carried in the public Plugins listing. 1.0.4 submitted 2026-08-24 and under review (D200X keypad, Kiro/Antigravity marks, answerable OpenClaw prompts, de/es/pt locales); the portal's new Create review version flow leaves 1.0.3 serving while it is reviewed (details) |
| GitHub Release — Android APK | android-v* |
1.0.10 |
| GitHub Release — ESP32 firmware | esp32-v* |
1.0.7 — 52 assets published 2026-08-22: for each of the 10 boards in shared/src/esp32-boards.ts a merged factory image written at 0x0 plus the four loose parts, and a manifest.json + SHA256SUMS.txt whose sizes and hashes are computed from the artifacts. esp32/src/config.h already declares 1.0.8 (the dense-dashboard readability pass) and its notes are in the CHANGELOG, but no esp32-v1.0.8 tag exists — 1.0.7 is the newest firmware actually delivered |
| Google Play — Android AAB | android-v* |
1.0.10 live (versionCode 12, published 2026-08-19 at 100% across 177 countries), superseding 1.0.9. Listing copy, assets and the console runbook are in 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.