AgentDeck AI 物理控制面板

Prerequisites

---

Prerequisites (Windows 11)

Option A: npm install (no clone needed)

npx @agentdeck/setup

Manual Build & Install

Build

cd AgentDeck
pnpm install
pnpm build            # shared → bridge, plugin, hooks
pnpm generate-icons   # SVG → PNG (required on first build)

1. Install Claude Code Hooks

Node CLI install (dev + Homebrew distribution):

node hooks/dist/install.js

Registers 7 hooks in ~/.claude/settings.local.json: SessionStart, SessionEnd, PreToolUse, PostToolUse, Stop, Notification, UserPromptSubmit. Each hook POSTs JSON to the bridge. Remove with node hooks/dist/install.js uninstall.

Mac App Store install: hooks are opt-in — the app shows a Settings → Claude Code Hooks pane with an "Enable Claude Code Hooks…" button that presents an NSAlert explaining what will be written, then an NSOpenPanel so the user explicitly selects ~/.claude/settings.json (the user-global file Claude Code watches; the CLI installer above uses settings.local.json). Only after that consent does AgentDeck write the hook entries (via a security-scoped bookmark). "Remove" in the same pane cleanly unregisters and revokes the bookmark. No command line required.

4. Voice Setup (Zero install)

Voice input uses Apple's on-device SFSpeechRecognizer (Speech framework). No sox, no whisper.cpp, no model downloads — the OS manages the dictation model via Settings → General → Keyboard → Dictation, which AgentDeck piggybacks on. The only user action is granting Microphone + Speech Recognition permission the first time the voice button is pressed (macOS shows the standard TCC prompts backed by NSMicrophoneUsageDescription and NSSpeechRecognitionUsageDescription).

All audio stays on-device (requiresOnDeviceRecognition = true), so the captured WAV — which may contain project/code names — never leaves the machine. See Voice Setup Guide for permission troubleshooting and wake-word details.

---

Install

```powershell git clone https://github.com/puritysb/AgentDeck.git cd AgentDeck pnpm install # postinstall (scripts/postinstall.mjs) is a no-op on Windows pnpm build # shared → bridge, plugin, hooks pnpm test # optional: run the Vitest suite

Setup

Run agentdeck wifi-setup to provision WiFi over serial (see CLI Reference). Once provisioned, the ESP32 connects to the daemon over WiFi WebSocket and displays a compact terrarium with agent status. OTA-capable boards can then be updated with agentdeck esp32-ota <target> --build; 86box and ips10 must first receive a USB full flash with the new 16MB dual-OTA partition table. PlatformIO firmware in esp32/; operational OTA details live in docs/esp32.md.

---

Quick Start

```bash

Usage

Option B: from source

git clone https://github.com/puritysb/AgentDeck.git && cd AgentDeck && pnpm setup

The `pnpm setup` command:
1. Checks required dependencies (Node.js 22+, pnpm, Claude CLI, Stream Deck app)
2. Installs `@elgato/cli` if missing
3. Runs `pnpm install` + `pnpm build`
4. Generates icon assets (16 PNGs)
5. Installs Claude Code hooks
6. Links the Stream Deck plugin
7. Links the `agentdeck` CLI globally
8. (Voice is built-in via Apple SFSpeech on-device — no extra install)

After setup, **restart the Stream Deck app**, then run:

You're steering.

---

Configuration

Link the CLI + Stream Deck plugin

cd bridge; pnpm link --global; cd .. cd plugin; streamdeck link .sdPlugin; cd .. # then restart the Stream Deck app ```

CLI Reference

The CLI command is agentdeck.

Sessions

Flags: -p <port>, -c <command>, -d (debug), --no-update-check Module flags: --local (all off), --no-mdns, --no-adb, --no-serial, --no-pixoo

The -c flag sets the full command AgentDeck spawns inside the session PTY, so any arguments you add are forwarded straight to the underlying agent. For example, to resume an earlier Claude Code session (the interactive picker appears when no id is given):

agentdeck claude -c "claude --resume"

The same pattern passes through any other flag the agent accepts — for instance -c "claude --remote-control".

Daemon

Session Management

Monitoring

Evaluation (APME)

Device Setup

---

2. Link Stream Deck Plugin

cd plugin && streamdeck link .sdPlugin

Creates a symlink in ~/Library/Application Support/com.elgato.StreamDeck/Plugins/. Restart the Stream Deck app to load.

Windows (Bridge + Plugin)

The Node.js bridge, the Claude Code hook installer, and the Stream Deck plugin run on Windows 11. The Apple, Android, and ESP32 native builds are macOS/Linux-only and are out of scope on Windows — but the core "steer Claude Code from a Stream Deck+" experience works.

Two-tier product: App Store app alone vs +CLI

AgentDeck is deliberately a two-tier product:

• Tier 1 — the App Store app alone is a complete monitoring dashboard. It installs Claude Code / Codex hooks itself (explicit NSOpenPanel consent), shows live session state and tool activity, flips a session to "needs attention" + a macOS notification when the agent genuinely waits for your response (you answer in your own terminal), optionally monitors an OpenCode server you run (opencode serve, Settings → Integrations), and drives all sandbox-reachable hardware (D200H, Pixoo, Timebox, iDotMatrix, ESP32) plus iPad pairing, voice input, and APME LLM evaluation.
• Tier 2 — install the agentdeck CLI (npx @agentdeck/setup) and the same app gains the PTY-powered extras: steering (answer Claude's real multi-choice prompts from the dashboard, Stream Deck, or D200H), Claude subscription usage gauges (5h/7d) and Codex credits, passive discovery of already-running sessions, Android/e-ink devices over ADB, and ESP32 firmware flashing. The app detects the CLI daemon automatically on port 9120 — no configuration; quit the daemon and the app seamlessly takes back over.

The upgrade story lives here and in docs/appstore-feature-matrix.md — the app itself never prompts you to install the CLI (App Review 4.2.3).

Troubleshooting