agent-deck
Terminal session manager for AI coding agents. Use when user mentions "agent-deck", "session", "sub-agent", "MCP attach", 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...
SKILL.md
Full skill instructions
Agent Deck
Terminal session manager for AI coding agents. Built with Go + Bubble Tea.
Version: 0.8.14 | Repo: github.com/asheshgoplani/agent-deck
Quick Start
# Launch TUI
agent-deck
# Create and start a session
agent-deck add -t "Project" -c claude /path/to/project
agent-deck session start "Project"
# Send message and get output
agent-deck session send "Project" "Analyze this codebase"
agent-deck session output "Project"
Essential Commands
| Command | Purpose |
|---|---|
agent-deck | Launch interactive TUI |
agent-deck add -t "Name" -c claude /path | Create session |
agent-deck session start/stop/restart <name> | Control session |
agent-deck session send <name> "message" | Send message |
agent-deck session output <name> | Get last response |
agent-deck session current [-q|--json] | Auto-detect current session |
agent-deck session fork <name> | Fork Claude conversation |
agent-deck mcp list | List available MCPs |
agent-deck mcp attach <name> <mcp> | Attach MCP (then restart) |
agent-deck status | Quick status summary |
Status: ● running | ◐ waiting | ○ idle | ✕ error
Sub-Agent Launch
Use when: User says "launch sub-agent", "create sub-agent", "spawn agent"
scripts/launch-subagent.sh "Title" "Prompt" [--mcp name] [--wait]
The script auto-detects current session/profile and creates a child session.
Retrieval Modes
| Mode | Command | Use When |
|---|---|---|
| Fire & forget | (no --wait) | Default. Tell user: "Ask me to check when ready" |
| On-demand | agent-deck session output "Title" | User asks to check |
| Blocking | --wait flag | Need immediate result |
Recommended MCPs
| Task Type | MCPs |
|---|---|
| Web research | exa, firecrawl |
| Code documentation | context7 |
| Complex reasoning | sequential-thinking |
TUI Keyboard Shortcuts
Navigation
| Key | Action |
|---|---|
j/k or ↑/↓ | Move up/down |
h/l or ←/→ | Collapse/expand groups |
Enter | Attach to session |
Session Actions
| Key | Action |
|---|---|
n | New session |
r/R | Restart (reloads MCPs) |
M | MCP Manager |
f/F | Fork Claude session |
d | Delete |
m | Move to group |
Search & Filter
| Key | Action |
|---|---|
/ | Local search |
G | Global search (all Claude conversations) |
!@#$ | Filter by status (running/waiting/idle/error) |
Global
| Key | Action |
|---|---|
? | Help overlay |
Ctrl+Q | Detach (keep tmux running) |
q | Quit |
MCP Management
Default: Do NOT attach MCPs unless user explicitly requests.
# List available
agent-deck mcp list
# Attach and restart
agent-deck mcp attach <session> <mcp-name>
agent-deck session restart <session>
# Or attach on create
agent-deck add -t "Task" -c claude --mcp exa /path
Scopes:
- LOCAL (default) -
.mcp.jsonin project, affects only that session - GLOBAL (
--global) - Claude config, affects all projects
Configuration
File: ~/.agent-deck/config.toml
[claude]
config_dir = "~/.claude-work" # Custom Claude profile
dangerous_mode = true # --dangerously-skip-permissions
[logs]
max_size_mb = 10 # Max before truncation
max_lines = 10000 # Lines to keep
[mcps.exa]
command = "npx"
args = ["-y", "exa-mcp-server"]
env = { EXA_API_KEY = "key" }
description = "Web search"
See config-reference.md for all options.
Troubleshooting
| Issue | Solution |
|---|---|
| Session shows error | agent-deck session start <name> |
| MCPs not loading | agent-deck session restart <name> |
| Flag not working | Put flags BEFORE arguments: -m "msg" name not name -m "msg" |
Report a Bug
If something isn't working, create a GitHub issue with context:
# Gather debug info
agent-deck version
agent-deck status --json
cat ~/.agent-deck/config.toml | grep -v "KEY\|TOKEN\|SECRET" # Sanitized config
# Create issue at:
# https://github.com/asheshgoplani/agent-deck/issues/new
Include:
- What you tried (command/action)
- What happened vs expected
- Output of commands above
- Relevant log:
tail -100 ~/.agent-deck/logs/agentdeck_<session>_*.log
See troubleshooting.md for detailed diagnostics.
Critical Rules
- Flags before arguments:
session start -m "Hello" name(notname -m "Hello") - Restart after MCP attach: Always run
session restartaftermcp attach - Never poll from other agents - can interfere with target session
References
- cli-reference.md - Complete CLI command reference
- config-reference.md - All config.toml options
- tui-reference.md - TUI features and shortcuts
- troubleshooting.md - Common issues and bug reporting