AgentDeck

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.

Start here

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.

1. Install

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/setup

This 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).

2. Look at it — no hardware required

agentdeck dashboard

A 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.

3. Run a session

agentdeck claude      # or: agentdeck codex · agentdeck opencode

Your 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 LAN

Reverse 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.

Then add surfaces

Any of these attach to the same daemon, and you can add them in any order:

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.

What it looks like on real hardware

What it does

• 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

Agents

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.

How it fits together

                              ┌── 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.

Documentation

Start with the website — puritysb.github.io/AgentDeck carries the rendered device catalog, live renderer previews, the design system, and build health.

Releases

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.

Development

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 + Robot

Four 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.

License & attribution

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.