AgentDeck · Handbook

Documentation

A map of the project for the curious and the contributing. HTML surfaces open here on the site; Markdown docs open on GitHub. Numbers, device specs, and conventions live in these files — they are the source of truth.

Start here what the project is and how it's built

Project overview

What AgentDeck is, install paths, the 16-surface story, and the direction shift toward hooks-first observation.

docs/architecture.md

Architecture

Monorepo layout, BridgeCore, the PtyAdapter / AgentAdapter hierarchy, device modules, and the plugin connection model.

docs/agent-harness.md

Multi-agent dev harness

How Claude Code / Codex / OpenCode / Antigravity each enter the repo and discover skills & workflows.

Devices & hardware the 16 surfaces

Hardware & OS spec sheet

The full matrix — SoC, resolution, display IC, flash, transport, and App Store tier for every surface.

Device gallery

The real hardware board by board, each card carrying its live specs.

docs/hardware-compatibility.md

Compatibility SSOT

Canonical resolutions, chips, and OS targets — the source the spec sheet renders from.

docs/devices.md

Device transport matrix

Per-device details — serial vs WiFi WS vs BLE vs HTTP, and how each renders session state.

ESP32 firmware

Boards, flash safety, WiFi provisioning, disconnect recovery, and WiFi OTA.

docs/esp32-client-contract.md

ESP32 client contract

The wire contract a display-only ESP32 client must honour — inbound events and device_info frames.

docs/android.md

Android support

Device matrix (Crema / Onyx / Kobo / tablets) and creature rendering on e-ink.

docs/android-ui.md

Android UI vision

E-ink + tablet layouts, creatures, and GC16 / DU / A2 refresh zones.

Daemon, plugins & protocol how the pieces talk

Daemon hub

Port 9120 singleton, mDNS recovery, usage relay, Gateway isolation, multi-surface monitoring.

docs/protocol.md

Bridge ↔ plugin protocol

The WebSocket dialect shared across every surface.

docs/gateway-protocol.md

OpenClaw Gateway protocol

Frame format, Ed25519 handshake, RPC/event catalog, versioning.

docs/plugin-conventions.md

Plugin conventions

Encoder LCD, wide canvas, button labels, the D200H Ulanzi Studio plugin, sleep/wake.

docs/v4-layout.md

Stream Deck v4 layout

Session-per-button keypad + encoder mapping, v3→v4 changes.

docs/tui-dashboard.md

TUI dashboard

agentdeck dashboard — terrarium, sprites, adaptive layouts.

Evaluation — APME judging agents, not projects

docs/why-apme.md

Why APME

The gut-feel routing problem, per-category evaluation strategy, composite score, and vibe-labeling first.

APME eval module

Schema, collector, deterministic + LLM judge, scorecard/recommender, daemon API, settings.

docs/apme-pipeline.md

APME pipeline

The 8-layer flow — ingestion, collector → store, classifier, runner, tuner, HTTP/WS, device rendering.

Design system the aquarium-tide look

Design spec

Aquarium-tide tokens, type, components, the marketing↔product palette split, hardware surfaces.

design/tokens.css

Token source of truth

Color / type / spacing tokens mirrored into TS, Swift, Kotlin, and browser JS.

docs/wake-word.md · voice-setup.md

Voice & wake word

Porcupine / microWakeWord and Apple SFSpeech permissions setup.

Release & ops shipping the app

Release policy

Per-track tags (apple / android / npm / esp32), monotonic-version constraints, bundle-ID steps.

docs/appstore-feature-matrix.md

App Store feature matrix

What ships in the sandboxed App Store app vs. what needs the terminal-managed daemon.

docs/testing.md · /reports/

Testing

Vitest, JUnit/Robolectric, XCTest, Robot Framework — and the live CI report.