asheshgoplani/agent-deck

Agent Deck

Terminal session manager for AI coding agents. Built with Go + Bubble Tea.

Version: 0.8.98 | Repo: github.com/asheshgoplani/agent-deck | Discord: discord.gg/e4xSs6NBN8

Script Path Resolution (IMPORTANT)

This skill includes helper scripts in its scripts/ subdirectory. When Claude Code loads this skill, it shows a line like:

Base directory for this skill: /path/to/.../skills/agent-deck

You MUST use that base directory path to resolve all script references. Store it as SKILL_DIR:

# Set SKILL_DIR to the base directory shown when this skill was loaded
SKILL_DIR="/path/shown/in/base-directory-line"

# Then run scripts as:
$SKILL_DIR/scripts/launch-subagent.sh "Title" "Prompt" --wait

Common mistake: Do NOT use <project-root>/scripts/launch-subagent.sh. The scripts live inside the skill's own directory (plugin cache or project skills folder), NOT in the user's project root.

For plugin users, the path looks like: ~/.claude/plugins/cache/agent-deck/agent-deck/<hash>/skills/agent-deck/scripts/ For local development, the path looks like: <repo>/skills/agent-deck/scripts/

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 | | agent-deck add --worktree <branch> | Create session in git worktree | | agent-deck worktree list | List worktrees with sessions | | agent-deck worktree cleanup | Find orphaned worktrees/sessions |

Status: ● running | ◐ waiting | ○ idle | ✕ error

Sub-Agent Launch

Use when: User says "launch sub-agent", "create sub-agent", "spawn agent"

$SKILL_DIR/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 |

Consult Another Agent (Codex, Gemini)

Use when: User says "consult with codex", "ask gemini", "get codex's opinion", "what does codex think", "consult another agent", "brainstorm with codex/gemini", "get a second opinion"

IMPORTANT: You MUST use the --tool flag to specify which agent. Without it, the script defaults to Claude.

Quick Reference

# Consult Codex (MUST include --tool codex)
$SKILL_DIR/scripts/launch-subagent.sh "Consult Codex" "Your question here" --tool codex --wait --timeout 120

# Consult Gemini (MUST include --tool gemini)
$SKILL_DIR/scripts/launch-subagent.sh "Consult Gemini" "Your question here" --tool gemini --wait --timeout 120

DO NOT try to create Codex/Gemini sessions manually with agent-deck add. Always use the script above. It handles tool-specific initialization, readiness detection, and output retrieval automatically.

Full Options

$SKILL_DIR/scripts/launch-subagent.sh "Title" "Prompt" \
  --tool codex|gemini \     # REQUIRED for non-Claude agents
  --path /project/dir \     # Working directory (auto-inherits parent path if omitted)
  --wait \                  # Block until response is ready
  --timeout 180 \           # Seconds to wait (default: 300)
  --mcp exa                 # Attach MCP servers (can repeat)

Supported Tools

| Tool | Flag | Notes | |------|------|-------| | Claude | --tool claude | Default, no flag needed | | Codex | --tool codex | Requires codex CLI installed | | Gemini | --tool gemini | Requires gemini CLI installed |

How It Works

1. Script auto-detects current session and profile
2. Creates a child session with the specified tool in the parent's project directory
3. Waits for the tool to initialize (handles Codex approval prompts automatically)
4. Sends the question/prompt
5. With --wait: polls until the agent responds, then returns the full output
6. Without --wait: returns immediately, check output later with agent-deck session output "Title"

Examples

# Code review from Codex
$SKILL_DIR/scripts/launch-subagent.sh "Codex Review" "Read cmd/main.go and suggest improvements" --tool codex --wait --timeout 180

# Architecture feedback from Gemini
$SKILL_DIR/scripts/launch-subagent.sh "Gemini Arch" "Review the project structure and suggest better patterns" --tool gemini --wait --timeout 180

# Both in parallel (consult both, compare answers)
$SKILL_DIR/scripts/launch-subagent.sh "Ask Codex" "Best way to handle errors in Go?" --tool codex --wait --timeout 120 &
$SKILL_DIR/scripts/launch-subagent.sh "Ask Gemini" "Best way to handle errors in Go?" --tool gemini --wait --timeout 120 &
wait

Cleanup

After getting the response, remove the consultation session:

agent-deck remove "Consult Codex"
# Or remove multiple at once:
agent-deck remove "Codex Review" && agent-deck remove "Gemini Arch"

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 | | s | Skills Manager (Claude) | | 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

Worktree Workflows

Create Session in Git Worktree

When working on a feature that needs isolation from main branch:

# Create session with new worktree and branch
agent-deck add /path/to/repo -t "Feature Work" -c claude --worktree feature/my-feature --new-branch

# Create session in existing branch's worktree
agent-deck add . --worktree develop -c claude

List and Manage Worktrees

# List all worktrees and their associated sessions
agent-deck worktree list

# Show detailed info for a session's worktree
agent-deck worktree info "My Session"

# Find orphaned worktrees/sessions (dry-run)
agent-deck worktree cleanup

# Actually clean up orphans
agent-deck worktree cleanup --force

When to Use Worktrees

| Use Case | Benefit | |----------|---------| | Parallel agent work | Multiple agents on same repo, different branches | | Feature isolation | Keep main branch clean while agent experiments | | Code review | Agent reviews PR in worktree while main work continues | | Hotfix work | Quick branch off main without disrupting feature work |

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

Get Help

• Discord: discord.gg/e4xSs6NBN8 for quick questions and community support
• GitHub Issues: For bug reports and feature requests

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:

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.

Session Sharing

Share Claude sessions between developers for collaboration or handoff.

Use when: User says "share session", "export session", "send to colleague", "import session"

# Export current session to file (session-share is a sibling skill)
$SKILL_DIR/../session-share/scripts/export.sh
# Output: ~/session-shares/session-<date>-<title>.json

# Import received session
$SKILL_DIR/../session-share/scripts/import.sh ~/Downloads/session-file.json

See: session-share skill for full documentation.

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
• session-share skill - Export/import sessions for collaboration