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:

•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