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

bash

# 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

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

bash

$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

bash

# 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

bash

$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

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

Examples

bash

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

bash

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

Worktree Workflows

Create Session in Git Worktree

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

bash

# 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

bash

# 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

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:

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.

Session Sharing

Share Claude sessions between developers for collaboration or handoff.

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

bash

# 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

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

agent-deck

NPX Install

Tags

SKILL.md Content

Agent Deck

Script Path Resolution (IMPORTANT)

Quick Start

Essential Commands

Sub-Agent Launch

Retrieval Modes

Recommended MCPs

Consult Another Agent (Codex, Gemini)

Quick Reference

Full Options

Supported Tools

How It Works

Examples

Cleanup

TUI Keyboard Shortcuts

Navigation

Session Actions

Search & Filter

Global

MCP Management

Worktree Workflows

Create Session in Git Worktree

List and Manage Worktrees

When to Use Worktrees

Configuration

Troubleshooting

Get Help

Report a Bug

Session Sharing

Critical Rules

References