relaydeck/relaydeck

[!WARNING] Early beta release. relaydeck is brand new and moving fast, so expect rough edges, breaking changes, and the occasional bug. Please open an issue if something breaks, and contributions are always welcome.

curl -fsSL https://relaydeck.ai/install.sh | sh

or with pip:

pip install relaydeck

then start the daemon (dashboard at http://127.0.0.1:8765):

relaydeck daemon start

---

What it is

relaydeck is a local-first fleet OS for CLI coding agents. It wraps the real vendor CLIs you already use (Claude Code, Codex, Cursor, OpenCode, pi), runs them unattended in PTYs, and gives you one place to watch, message, and automate them. Everything runs on your machine; state lives in ~/.relaydeck and a local SQLite db, and secrets stay in a vault on the daemon host.

---

Works with every harness

Each harness maps your agent config (model, autonomy, system prompt) onto the vendor CLI. Install at least one on your $PATH.

---

Bring any provider

Bundled provider plugins for Anthropic, OpenAI, OpenRouter, and Ollama, plus any OpenAI-compatible endpoint (Groq, Together, Fireworks, Cerebras, DeepSeek, xAI, Mistral, vLLM, and more). Keys live in the vault, never in agent configs.

---

Three first-class surfaces — CLI, TUI, web

relaydeck is CLI-first: the shell is the platform, and everything runs against one local daemon. The two UIs are peers over the same HTTP/SSE API, not a privileged layer — pick whichever fits.

relaydeck view              # built-in TUI command center (no deps)

┌ relaydeck ───────────────────────────── ws: api · agent: reviewer ─┐
│ workspaces        │ 1 Terminal  2 Events  3 Messages  4 Tasks  ·C  │
│ ▸ api    3 agents │ reviewer  $ pytest -q ......... [ working ]    │
│   web    1 agent  │ 41 passed in 2.10s                             │
│ agents            │ › builder is applying the diff reviewer filed  │
│  ● reviewer  work │ ────────────────────────────────────────────  │
│  ▲ builder   82%  │ events ▸ agent.context builder 82% (warn)      │
│  ⏸ tester    idle │         ▸ manager.action builder → compact     │
│ ^B 1-4 tabs · ^B C console · ^B M message · ^B D detach            │
└────────────────────────────────────────────────────────────────────┘

The web dashboard is a fleet home with live usage and worker pulse, plus a per-agent lens (live PTY terminal, usage/cost tiles, and panels for identity, context, events, config, inbox, compose). Both UIs read the same SSE stream the CLI’s events tail -f does — no polling, no privileged path.

---

Quickstart

Requirements: Python 3.12+ and at least one harness CLI on your $PATH.

# One gesture: find-or-register this dir as a workspace, ensure the daemon,
# open the command center (TUI; --web opens the dashboard, --no-view for scripts).
relaydeck open .

…or do it step by step:

# Register this project as a workspace with messaging enabled.
relaydeck init . --plugin messaging

# Start the daemon (dashboard at http://127.0.0.1:8765).
relaydeck daemon start

# Create two agents with distinct roles.
relaydeck agent create planner --type claude-code \
  --purpose "Plan changes; do not implement"
relaydeck agent create coder --type codex-cli \
  --purpose "Implement scoped patches from planner specs"
relaydeck agent start planner coder

# Send work; agents discover peers via the identity preamble.
relaydeck workspace message --agent planner \
  "Plan: add --dry-run to relaydeck plugin uninstall. Keep it under 50 LOC."

# Observe
relaydeck view              # built-in TUI
open http://127.0.0.1:8765  # web dashboard (primary UI)

relaydeck --help documents every command. With the daemon running, the OpenAPI docs live at http://127.0.0.1:8765/docs.

Drive it from your agent — the relaydeck skill

relaydeck ships a publishable agent skill (named relaydeck) that teaches any SKILL.md-capable harness (Claude Code, …) to install and drive the fleet. Arm your local agent with one command, then just ask it to “review this repo with three agents in parallel”:

relaydeck skills install            # → ~/.claude/skills/relaydeck
relaydeck skills install --target both   # Claude + Codex skill roots

The skill is self-aware (it won’t bootstrap a fleet-of-fleets from inside one) and finds an existing relaydeck install. See skills/relaydeck/ and the CLI usage guide.

---

Extend with plugins

Everything beyond the core runtime is a RelaydeckPlugin: discovered at startup, capability-gated, and removable without forking the engine. A 30-plugin bundle ships in the box.

relaydeck plugin list
relaydeck plugin new my-plugin          # scaffold: harness | provider | skill
relaydeck plugin dev ./my-plugin        # editable install
relaydeck plugin verify ./my-plugin     # manifest + skill validation

Plugins register CLI commands, HTTP routes, dashboard lenses/tiles, workers, skills, and event subscriptions; capabilities declared in plugin.toml gate SDK access at runtime. See CONTRIBUTING.md for the authoring guide.

---

Core concepts

                    +---------------------------------------+
  CLI / scripts     |          relaydeck daemon             |     Web dashboard
  relaydeck ... --->|  orchestrator . plugins . event bus   |<---- localhost:8765
       HTTP/SSE     |         |              |              |      (live SSE)
                    |    harness PTYs    SQLite state       |
                    |   claude . codex . agents . msgs      |
                    |   cursor . pi  .   usage . events     |
                    +---------------------------------------+

  ~/.relaydeck/   agents/*.yaml   workspaces/*/agent.toml   vault.yaml   runtime/relaydeck.db

One install ships relaydeck/ (engine + host contract) and plugins/ (every official plugin). Core imports zero plugins; plugin authors import public facades only: relaydeck.sdk, relaydeck.harness, relaydeck.provider, and so on.

---

More

---

Acknowledgements

relaydeck is harness-native: it wraps real CLI coding agents rather than shipping its own model runtime. Huge thanks to the pi coding agent (relaydeck’s reference harness), and to Claude Code, Codex, Cursor, OpenCode, and Antigravity. We were also inspired by ideas from across the open agent ecosystem, including Nous Research’s Hermes Agent and OpenClaw, which relaydeck can observe read-only.

The dashboard builds on Lit, xterm.js, IBM Plex & JetBrains Mono, Heroicons, and Simple Icons. Full attributions live in CREDITS.md. Product names, logos, and trademarks belong to their respective owners.

License

MIT