/agent-deck

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; fan out a fleet of child sessions and check them non-blockingly; export or import a session for a teammate ("share session"); tag sessions and find past conversations (recall); run a local retrospective over their own transcripts, or reproduce an agent-deck bug and prove its fix; set up conductors or watchers; switch to a session by name ("go to X", "X par jao"); configure config.toml; troubleshoot agent-deck; or work on the agent-deck repo itself (fix, add or review its code or docs, open or fix a PR). Not for in-conversation subagents, plain git worktrees, plain tmux, team or sprint retrospectives, or bugs in projects other than agent-deck.
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:

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/<hash>/skills/agent-deck/`; a repo checkout resolves to `<repo>/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 <name>` | Create and start a session under a named account slot | | `agent-deck session start/stop/restart <name>` | Control session | | `agent-deck session send <name> "message"` | Send message | | `agent-deck session send <name> --message-file <file>` | Send message from file (`-` = stdin); no shell quoting. Also on `launch`/`session start` | | `agent-deck session command --json <name> "/compact"` | Run a Claude Code slash command or skill (`/model`, `/compact`, `/clear`, `/exit`) safely and verify it; never via `session send`. `session commands --json <name>` lists them | | `agent-deck session ref <source> <target>` | Type a short reference to `<source>` (title, id, path, status, how to read it) into `<target>`'s composer, not sent; `--print` only prints it | | `agent-deck session output <name>` | 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 <name>` | Fork Claude/OpenCode/Pi/Codex/Oh My Pi conversation | | `agent-deck mcp list` | List available MCPs | | `agent-deck mcp attach <name> <mcp>` | 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 <branch>` | 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` always works. Since 0.12.0 nearly every subcommand (`session`, `add`, `launch`, `group`, `worktree`, `try`, ...) also accepts flags after the positional, so on a current build a flag after the name is not why it was ignored (older builds dropped it); only `config show [path]` and `openclaw send <message>` stop parsing at the first positional, so there a flag after it is ignored or read as text. Everything after `--` is positional. 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, but only when the XDG file does not exist; once it does, the legacy file is ignored). 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,