Manage multi-session environments, sub-agents, and MCP tool attachments for AI coding agents.

Install

mkdir -p .claude/skills/agent-deck && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/7977" && unzip -o skill.zip -d .claude/skills/agent-deck && rm skill.zip

Installs to .claude/skills/agent-deck

Activation

This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.

Terminal session manager for AI coding agents. Use when user mentions "agent-deck", "session", "sub-agent", "MCP attach", "git worktree", or needs to (1) create/start/stop/restart/fork sessions, (2) attach/detach MCPs, (3) manage groups/profiles, (4) get session output, (5) configure agent-deck, (6) troubleshoot issues, (7) launch sub-agents, or (8) create/manage worktree sessions. Covers CLI commands, TUI shortcuts, config.toml options, and automation.
457 chars✓ has a “when” triggerlonger than Claude Code's old 250-char listing cap (fine on current versions)
Intermediate

Key capabilities

  • →Create, start, stop, restart, fork, send, output, and remove sessions
  • →Launch child Claude sessions with parent linkage and inherited directories
  • →Manage groups to organize sessions hierarchically
  • →Attach and detach MCP plugins globally or per-session
  • →Create isolated git-worktree-backed sessions for parallel branch work
  • →Export and import Claude conversations for developer handoff

How it works

Agent Deck manages AI coding agent sessions through CLI commands and a TUI, allowing users to create, control, and configure sessions, attach tools, and manage worktrees. It persists state across restarts.

Inputs & outputs

You give it
Session commands, messages, configuration options, group names, MCP plugin details
You get back
Managed agent sessions, sub-agent launches, session output, configured agent-deck, worktree sessions

When to use agent-deck

  • →Create and manage multiple agent sessions
  • →Attach and detach MCP tool servers
  • →Launch sub-agents for specific coding tasks
  • →Manage git worktree sessions via terminal

About this skill

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 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

CommandPurpose
agent-deckLaunch interactive TUI
agent-deck add -t "Name" -c claude /pathCreate 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 --jsonChild 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 listList available MCPs
agent-deck mcp attach <name> <mcp>Attach MCP (then restart)
agent-deck statusQuick status summary
agent-deck open report.htmlShow 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.

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.

Where to Look Next

Read the matching reference before acting on anything beyond the commands above.

When the task involvesRead
What agent-deck and each session's CLI (claude, codex, gemini) can do; choosing the -c tool for a childcapabilities.md
Sessions messaging each other, send delivery guarantees, output, children, inbox drain, handoff, send pitfallssession-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
Fanning out several children and supervising them non-blockinglyfleet.md
Conductors (conductor setup), Telegram/Slack channels, watchers (webhook, GitHub, ntfy, Slack)conductors.md, then documentation/WATCHERS.md for custom watchers
Switching the AgentDeck app or this terminal to a session by name: "go to X", "switch to X", "X par jao", "X pe chalo" (agent-deck switch)switch.md
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 accountsession-workflows.md
Self-improvement (transcript mining), goals (goal-driven worker autonomy), trust-but-verify for completion claimsautonomy.md, then self-improvement.md or 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 <subcommand>", config drift, channel subscription, Telegram conductor topology, v1.9.x findings), and what needs a deck newer than 1.16.11gotchas.md
TUI keys, dialogs, search, and layouttui-reference.md
A session in error, MCPs not loading, diagnostics, getting help, or filing a bugtroubleshooting.md
Docker sandboxed sessionssandbox.md
Durable session hints and tags, the cross-harness transcript index, recall context --into current, federated search, the recall MCP serverrecall.md
Exporting or importing a session for another developersession-share.md
A local retrospective over the user's own transcripts, Recall index and logs (repeated failures, retries, stuck sessions); privacy rules and the pause-for-the-user-to-file handoffretro.md, metrics in retro-metrics.md
Reproducing an agent-deck bug in isolation and proving a fix (reproduced / not reproduced / fixed verdicts, receipts, the result contract)repro.md, then repro-contract.md
User-level vs pool skills, attaching and detaching skillsdocumentation/SKILLS.md
Working on the agent-deck repo itself: fix, add or review something in its code or docs, open a PR, answer an intake or review verdictcontributing.md; it mirrors the PR intake gate and runs scripts/contributing/self-check.sh (tests only in a container)

When not to use it

  • →When using the short-flag parser for `agent-deck launch -m` as it misroutes text after `-m`
  • →When using `session update --no-parent`, `group remove`, or `launch -parent` due to CLI verb inconsistency

Limitations

  • →The `agent-deck launch -m` short-flag parser misroutes text after `-m`
  • →CLI verbs like `session update --no-parent` are rejected; correct verbs are `session unset-parent`
  • →The `launch` command does not accept `-parent` as parent linkage is automatic

How it compares

Agent Deck provides a dedicated terminal session manager for AI coding agents, offering structured control over multiple sessions, sub-agents, and worktrees, which is more organized than managing individual agent processes manually.

Compared to similar skills

agent-deck side by side with the closest alternatives in the catalog.

SkillInstallsUpdatedSafetyDifficulty
agent-deck (this skill)04moReviewIntermediate
opencode-cli1410moReviewAdvanced
claude-automation-recommender475moReviewBeginner
mcp-integration2112moReviewIntermediate

Try saying

Example prompts that trigger this skill in your AI assistant.

You might also like

opencode-cli

SpillwaveSolutions

This skill should be used when configuring or using the OpenCode CLI for headless LLM automation. Use when the user asks to "configure opencode", "use opencode cli", "set up opencode", "opencode run command", "opencode model selection", "opencode providers", "opencode vertex ai", "opencode mcp servers", "opencode ollama", "opencode local models", "opencode deepseek", "opencode kimi", "opencode mistral", "fallback cli tool", or "headless llm cli". Covers command syntax, provider configuration, Vertex AI setup, MCP servers, local models, cloud providers, and subprocess integration patterns.

14174

claude-automation-recommender

anthropics

Analyze a codebase and recommend Claude Code automations (hooks, subagents, skills, plugins, MCP servers). Use when user asks for automation recommendations, wants to optimize their Claude Code setup, mentions improving Claude Code workflows, asks how to first set up Claude Code for a project, or wants to know what Claude Code features they should use.

47140

mcp-integration

anthropics

This skill should be used when the user asks to "add MCP server", "integrate MCP", "configure MCP in plugin", "use .mcp.json", "set up Model Context Protocol", "connect external service", mentions "${CLAUDE_PLUGIN_ROOT} with MCP", or discusses MCP server types (SSE, stdio, HTTP, WebSocket). Provides comprehensive guidance for integrating Model Context Protocol servers into Claude Code plugins for external tool and service integration.

21123

hook-development

anthropics

This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.

11122

agent-factory

alirezarezvani

Claude Code agent generation system that creates custom agents and sub-agents with enhanced YAML frontmatter, tool access patterns, and MCP integration support following proven production patterns

8109

swarm-advanced

ruvnet

Advanced swarm orchestration patterns for research, development, testing, and complex distributed workflows

7110

Search skills

Search the agent skills registry