Agent Deck

Keep the way you work consistent across coding agents and workspaces. Agent Deck gives every agent the right playbooks, tools, and credentials from one governed source of truth.

Watch the 100-second overview — one playbook across agents and workspaces.

Why · Quick Start · How learning works · Delegate · Everyday commands · Docs

Bringing a friend (or starting cold)? Follow the one-page friend path: cold machine → first deck switch → first Dealer issue.

You teach one coding agent how you work: how to open a PR, write a ticket, check a release, or use your knowledge base. Then you switch to another agent and teach it all again.

• Consistency across agents. The same playbook can guide Claude Code, Codex, Cursor, or another MCP client. You maintain one procedure instead of separate copies for every agent.
• Consistency across workspaces. Reusable PR rules, ticketing procedures, UI principles, and knowledge-base workflows live in one collection. Attach them to the decks that need them instead of duplicating them across repositories.
• One governed source of truth. A deck bundles the MCP services, credentials, and playbooks for one context. The agent sees only that deck. Switch decks instead of rewiring agents; improve a playbook once and reuse the lesson everywhere.

One MCP endpoint, registered once.

The execution half is agent-dealer: queue tasks against a deck, approve the plan before anything runs, execute headless under budget caps, review results, and gate every outbound send — Dealer runs consume deck playbooks and file patch proposals back.

macOS required. API key secrets, OAuth client secrets, and OAuth tokens are stored in macOS Keychain. Linux and Windows are not supported for production use yet.

Requirements: Node.js 20+ · npm · Dashboard via agent-deck start / agent-deck open (listens on 127.0.0.1:1111) · Agent Deck MCP http://127.0.0.1:1110/mcp

1. Install and launch (managed install — auto-updates, keeps existing ~/.agent-deck data):

npx @agent-deck/cli@latest install
export PATH="$HOME/.local/bin:$PATH"
agent-deck start --daemon

2. Register Agent Deck in your agent (once per machine; <client> is codex, cursor, claude, or muse):

agent-deck setup --client <client>

Per-client details, restart and verify steps, and what setup installs: Agent harness.

3. Create a deck in the dashboard (My Decks → create a deck → drag cards from My Collection), or ask the agent in chat to create one.

4. Register playbooks (agent-first). Describe the procedure in chat — e.g. “Add a release checklist playbook with trigger ‘ship to npm’.” Let the agent register it and attach it to your deck.

5. Add external MCP servers and API keys (Linear, Notion, Slack, …) in the dashboard — OAuth in the browser, API keys pasted once into Keychain — then drag the cards onto your deck.

6. Pick a deck each session. Tell the agent which deck — “use the dev deck”, or mid-session “switch to my personal deck” — and approve the switch as This session only or This workspace by default. Or run agent-deck use <deck> in a repo so the deck binds on session open without naming it.

Same decks on another machine: keep ~/.agent-deck/ in a private Git repository you own, push and pull it yourself, then run agent-deck reindex — see Store format.

When you correct a playbook-driven result, Agent Deck turns the lesson into a reviewable patch proposal so future sessions start from what you taught it. Corrections become proposals you review in the dashboard (Playbook patches); accepted changes update the deck. Every run makes the next one better.

If you use per-repo use stubs and playbook triggers changed, refresh with agent-deck use --refresh.

To delegate a task to a local agent session on a deck, agent-deck run launches a signed-in client bound to that deck:

agent-deck run mydeck --client claude --cwd /path/to/repo --prompt-file ./brief.md --tools readonly

Per-client flags, resume, and trust behavior: DELEGATION.md.

The repo root is one plugin: one skills/ folder (agent-deck-session, agent-deck-playbooks, agent-deck-setup, agent-deck-run) plus .mcp.json, described by a manifest per client. Prerequisites for delegation: agent-deck >= 2.1.0 and the daemon running (see Quick Start), and the client CLI you delegate to, installed and signed in. The agent-deck-setup skill checks these and tells you what is missing.

Skills are never copied by hand: the muse copies come from root skills/ via scripts/copy-muse-skills.mjs at build time and agent-deck setup --client muse at install time.

1. Install agent-deck and start it (Quick Start above): npx @agent-deck/cli@latest install, agent-deck start --daemon, then agent-deck doctor.
2. Install the agent-deck plugin from the Cursor Marketplace (or, for local testing, copy this repo to ~/.cursor/plugins/local/agent-deck and run Developer: Reload Window). The plugin adds the four skills and the agent-deck MCP server (agent-deck mcp-launch, from .mcp.json); it needs the agent-deck CLI on PATH and stores no secrets.
3. Create a deck in the dashboard (agent-deck open), then bind a project folder: agent-deck use <deck> --client cursor, and reload Cursor.
4. Test task: open that folder and ask the agent: "Use the agent-deck-setup skill to check my Agent Deck setup and tell me what is missing." Expected: it runs read-only checks (agent-deck --version, agent-deck status, agent-deck deck list) and reports the result. Then try delegation: "Use agent-deck-run to have a read-only claude session on deck list the files in this folder, and report its answer." Expected: it launches agent-deck run <deck> --client claude --tools readonly --detach, polls agent-deck run status, and reports the session's answer with the runId and sessionId.

agent-deck start --daemon
agent-deck open             # re-open dashboard with a fresh auth cookie
agent-deck use <deck>       # bind this folder to a deck
agent-deck export all -o backup.agent-deck.json
agent-deck credential list
agent-deck exec --connections cred_id -- <command>
agent-deck upgrade
agent-deck stop

Port conflicts: agent-deck status · agent-deck start --force. Full environment reference: Setup.

Index: docs/README.md · Security: SECURITY.md

MIT — see LICENSE.