--- name: agent-deck description: agent-deck, the terminal session manager for AI coding agents. Use when the user mentions "agent-deck", "session", "sub-agent", "MCP attach", or "git worktree", or needs to create, start, message, read, fork, restart, or supervise agent-deck sessions; launch child sessions or consult another CLI through agent-deck; attach MCPs to a session; manage groups, profiles, accounts, or worktree sessions; set up conductors or watchers; configure config.toml; or troubleshoot agent-deck. Not for in-conversation subagents, plain git worktrees, or plain tmux. metadata: compatibility: "claude, codex, opencode" --- # Agent Deck > Run `agent-deck --version` for your installed version. This skill targets v1.16.11+; most patterns work back to v1.7. See [Backward Compatibility](references/gotchas.md#backward-compatibility) for what needs ≥1.16.11. ## Scripts Helper scripts live in this skill's `scripts/` folder. Resolve them from the base directory shown when the skill loaded, not from the user's project: ```bash SKILL_DIR="/path/shown/in/base-directory-line" $SKILL_DIR/scripts/launch-subagent.sh "Title" "Prompt" --wait ``` Plugin installs resolve to `~/.claude/plugins/cache/agent-deck/agent-deck//skills/agent-deck/`; a repo checkout resolves to `/skills/agent-deck/`. ## Essential Commands | Command | Purpose | |---------|---------| | `agent-deck` | Launch interactive TUI | | `agent-deck add -t "Name" -c claude /path` | Create session | | `agent-deck launch . -c claude --account ` | Create and start a session under a named account slot | | `agent-deck session start/stop/restart ` | Control session | | `agent-deck session send "message"` | Send message | | `agent-deck session send --message-file ` | Send message from file (`-` = stdin); no shell quoting. Also on `launch`/`session start` | | `agent-deck session output ` | Get bounded, ANSI-clean last response (JSON/quiet/copy preserve full source) | | `agent-deck session children --json` | Child sessions' live status + asserted completions (non-blocking, read-only) | | `agent-deck session current [-q\|--json]` | Auto-detect current session | | `agent-deck session fork ` | Fork Claude/OpenCode/Pi/Codex/Oh My Pi conversation | | `agent-deck mcp list` | List available MCPs | | `agent-deck mcp attach ` | Attach MCP (then restart) | | `agent-deck status` | Quick status summary | | `agent-deck open report.html` | Show an HTML report to the user in the macOS app Browser panel (works from remote sessions too) | | `agent-deck add --worktree ` | Create session in git worktree | **Status:** `●` running | `◐` waiting | `○` idle | `✕` error Every other command and flag is in [cli-reference.md](references/cli-reference.md). ## Rules 1. **Flags before arguments:** `session start -m "Hello" name`, not `name -m "Hello"`. A flag that seems ignored is almost always in the wrong position. 2. **MCPs on request only:** attach one when the user asks, then `session restart` it; attaching alone does not load it. `--global` writes Claude's config for every project; the default writes the session's `.mcp.json`. 3. **Leave other sessions to work:** read another session with a single `session output` or `session children` call rather than a polling loop, which can interfere with the target. 4. **State only the task in a child's prompt.** Every session agent-deck launches already carries its identity (session id, title, parent, core commands, completion sentinel; `$AGENTDECK_IDENTITY_FILE` for custom `--cmd`), so a prompt need not explain who the child is or how to reach its parent. Opt out with `--no-identity` or `[launch] inject_identity = false`; gemini also needs its identity folder trusted (`documentation/HARNESS_IDENTITY.md`). ## Configuration `$XDG_CONFIG_HOME/agent-deck/config.toml` (default `~/.config/agent-deck/config.toml`; legacy `~/.agent-deck/config.toml` still honored). Every option is in [config-reference.md](references/config-reference.md). ## Where to Look Next Read the matching reference before acting on anything beyond the commands above. | When the task involves | Read | |---|---| | What agent-deck and each session's CLI (claude, codex, gemini) can do; choosing the `-c` tool for a child | [capabilities.md](references/capabilities.md) | | Sessions messaging each other, `send` delivery guarantees, `output`, `children`, `inbox drain`, `handoff`, send pitfalls | [session-communication.md](references/session-communication.md) | | Launching a sub-agent (`launch-subagent.sh`), retrieval modes, worker prompt conventions, the `===AGENTDECK_DONE===` completion sentinel, consulting Codex or Gemini, root-level peers (`-no-parent`) | [sub-agents.md](references/sub-agents.md) | | Fanning out several children and supervising them non-blockingly | [fleet skill](../fleet/SKILL.md) | | Conductors (`conductor setup`), Telegram/Slack channels, watchers (webhook, GitHub, ntfy, Slack) | [conductors.md](references/conductors.md), then [documentation/WATCHERS.md](https://github.com/asheshgoplani/agent-deck/blob/main/documentation/WATCHERS.md) for custom watchers | | Context inspection (`session context`), worktrees, scratch sessions (`try`), runtime health (`health`, dead letters, `remote update --from-build`), recall hints and search, session sharing, switching a session to another Claude account | [session-workflows.md](references/session-workflows.md) | | Self-improvement (transcript mining), goals (goal-driven worker autonomy), trust-but-verify for completion claims | [autonomy.md](references/autonomy.md), then [self-improvement.md](references/self-improvement.md) or [goal.md](references/goal.md) for the deep dive | | Using agent-deck as a daemon supervisor (it is not one), known gotchas and workarounds (`--no-wait` Enter fallback, `text file busy`, `-c "claude "`, config drift, channel subscription, Telegram conductor topology, v1.9.x findings), and what needs a deck newer than 1.16.11 | [gotchas.md](references/gotchas.md) | | TUI keys, dialogs, search, and layout | [tui-reference.md](references/tui-reference.md) | | A session in error, MCPs not loading, diagnostics, getting help, or filing a bug | [troubleshooting.md](references/troubleshooting.md) | | Docker sandboxed sessions | [sandbox.md](references/sandbox.md) | | Durable session hints and tags, the cross-harness transcript index, `recall context --into current`, federated search, the recall MCP server | [recall skill](recall/SKILL.md) | | Exporting or importing a session for another developer | [session-share skill](../session-share/SKILL.md) | | User-level vs pool skills, attaching and detaching skills | [documentation/SKILLS.md](https://github.com/asheshgoplani/agent-deck/blob/main/documentation/SKILLS.md) | | Fixing agent-deck itself and opening a PR | `.github/skills/agent-deck-contributor/SKILL.md` in an agent-deck checkout; it mirrors the PR intake gate and runs tests sandboxed |