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

bash
# 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"

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

bash
# 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.json in project, affects only that session
• GLOBAL (--global) - Claude config, affects all projects

Configuration

File: ~/.agent-deck/config.toml

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:

bash
# 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:

1. What you tried (command/action)
2. What happened vs expected
3. Output of commands above
4. Relevant log: tail -100 ~/.agent-deck/logs/agentdeck_<session>_*.log

See troubleshooting.md for detailed diagnostics.

Critical Rules

1. Flags before arguments: session start -m "Hello" name (not name -m "Hello")
2. Restart after MCP attach: Always run session restart after mcp attach
3. 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