agent-deck
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.zipInstalls 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.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
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 --versionfor 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
| 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.
Rules
- Flags before arguments:
session start -m "Hello" namealways 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); onlyconfig show [path]andopenclaw send <message>stop parsing at the first positional, so there a flag after it is ignored or read as text. Everything after--is positional. - MCPs on request only: attach one when the user asks, then
session restartit; attaching alone does not load it.--globalwrites Claude's config for every project; the default writes the session's.mcp.json. - Leave other sessions to work: read another session with a single
session outputorsession childrencall rather than a polling loop, which can interfere with the target. - 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_FILEfor custom--cmd), so a prompt need not explain who the child is or how to reach its parent. Opt out with--no-identityor[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 involves | Read |
|---|---|
What agent-deck and each session's CLI (claude, codex, gemini) can do; choosing the -c tool for a child | capabilities.md |
Sessions messaging each other, send delivery guarantees, output, children, inbox drain, handoff, send pitfalls | 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 |
| Fanning out several children and supervising them non-blockingly | fleet.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 account | session-workflows.md |
| Self-improvement (transcript mining), goals (goal-driven worker autonomy), trust-but-verify for completion claims | autonomy.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.11 | gotchas.md |
| TUI keys, dialogs, search, and layout | tui-reference.md |
| A session in error, MCPs not loading, diagnostics, getting help, or filing a bug | troubleshooting.md |
| Docker sandboxed sessions | sandbox.md |
Durable session hints and tags, the cross-harness transcript index, recall context --into current, federated search, the recall MCP server | recall.md |
| Exporting or importing a session for another developer | session-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 handoff | retro.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 skills | documentation/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 verdict | contributing.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.
| Skill | Installs | Updated | Safety | Difficulty |
|---|---|---|---|---|
| agent-deck (this skill) | 0 | 4mo | Review | Intermediate |
| opencode-cli | 14 | 10mo | Review | Advanced |
| claude-automation-recommender | 47 | 5mo | Review | Beginner |
| mcp-integration | 21 | 12mo | Review | Intermediate |
Try saying
Example prompts that trigger this skill in your AI assistant.
More by asheshgoplani
View all by asheshgoplani →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.
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.
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.
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.
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
swarm-advanced
ruvnet
Advanced swarm orchestration patterns for research, development, testing, and complex distributed workflows