Agent Deck

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.json in 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 (not name -m "Hello")
• Restart after MCP attach: Always run session restart after mcp 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