Agent Deck

Agent Deck CLI

Менеджер терминальных сессий для AI агентов. Позволяет запускать, контролировать и получать результаты от дочерних Claude сессий.

Запуск суб-агента

Триггеры: "запусти агента", "запусти саб-агента", "launch sub-agent"

Простой запуск (CLI команды)

# Создать сессию
agent-deck add -t "Название" -c claude /path/to/workdir

# Создать как дочернюю сессию текущего агента
agent-deck add -t "Название" --parent "Родитель" -c claude /path/to/workdir

# Запустить
agent-deck session start "Название"

# Отправить задачу
agent-deck session send "Название" "Твоя задача..."

Автоматический запуск (скрипт)

scripts/launch-subagent.sh "Название" "Промпт" [--mcp exa] [--wait]

Скрипт автоматически:

• Определяет текущую сессию и профиль
• Создаёт дочернюю сессию
• Ждёт инициализации Claude
• Отправляет промпт

Режимы получения результата

---

Проверка статуса

Триггеры: "проверь сессию", "проверь статус", "check session"

agent-deck status                      # Все сессии (сводка)
agent-deck session show "Название"     # Детали конкретной сессии
agent-deck session show -json "Название"  # JSON формат
agent-deck session current             # Текущая сессия (в которой работаем)
agent-deck session current --json      # Текущая сессия в JSON

Статусы:

• ● работает (running)
• ◐ ждёт ввода (waiting)
• ○ простаивает (idle)
• ✕ ошибка (error)

---

Получение результата

Триггеры: "покажи вывод агента", "что агент ответил", "show agent output"

agent-deck session output "Название"

---

MCP подключение

agent-deck mcp list                        # Доступные MCP серверы
agent-deck mcp attach "Название" exa       # Подключить MCP к сессии
agent-deck session restart "Название"      # ОБЯЗАТЕЛЬНО после подключения!

Рекомендуемые MCP

---

Управление сессиями

# Жизненный цикл
agent-deck session start "Название"
agent-deck session stop "Название"
agent-deck session restart "Название"

# Список всех сессий
agent-deck ls
agent-deck ls -json

# Удалить сессию
agent-deck rm "Название"

---

Важные правила

1. Флаги перед аргументами: session show -json name (не session show name -json) 2. После mcp attach обязательно session restart для применения изменений 3. Избегать polling результатов из других агентов — это может мешать целевой сессии 4. Идентификация сессии: можно использовать название, ID (≥6 символов) или путь

---

Примеры использования

Запуск исследовательского агента

# Создать агента для веб-исследования
agent-deck add -t "Researcher" -c claude --mcp exa /tmp/research
agent-deck session start "Researcher"
agent-deck session send "Researcher" "Найди информацию о последних трендах в AI"

Проверка готовности

# Проверить статус
agent-deck session show "Researcher"

# Если статус ◐ (waiting) — агент закончил, получить результат:
agent-deck session output "Researcher"

Automation Patterns

Sub-Agent Script (Primary)

# Fire and forget (recommended)
scripts/launch-subagent.sh "Research" "Find info about X" --mcp exa

# With blocking wait
scripts/launch-subagent.sh "Query" "Answer Y" --wait --timeout 120

# Multiple MCPs
scripts/launch-subagent.sh "Deep Research" "Analyze Z" --mcp exa --mcp firecrawl

Manual Sub-Agent Pattern

When script unavailable:

PARENT=$(agent-deck session current -q)
PROFILE=$(agent-deck session current --json | jq -r '.profile')

agent-deck -p "$PROFILE" add -t "Task" --parent "$PARENT" -c claude /tmp/task
agent-deck -p "$PROFILE" session start "Task"
sleep 10  # Wait for Claude readiness
agent-deck -p "$PROFILE" session send "Task" "Your prompt"

Check Output

# Check status
agent-deck session show "Task" | grep Status

# Get response when waiting (◐)
agent-deck session output "Task"

Batch Operations

# Start multiple sessions
for name in api frontend backend; do
  agent-deck session start "$name"
done

# Attach MCPs to multiple sessions
for session in proj1 proj2; do
  agent-deck mcp attach "$session" exa
  agent-deck session restart "$session"
done

JSON Scripting

# Get all waiting sessions
agent-deck list --json | jq -r '.[] | select(.status == "waiting") | .title'

# Count by status
agent-deck status --json | jq '.running, .waiting, .idle'

Warnings

1. Avoid external polling agents - They can send messages that interfere with target sessions 2. Use on-demand checks - Let user request output when ready 3. Flags before arguments - session show --json name not session show name --json

CLI Reference

Global Flags

-p <profile>, --profile=<profile>   # Use specific profile
--json                               # JSON output
-q, --quiet                          # Minimal output

Commands

add

agent-deck add [path] [options]

agent-deck add -t "My Project" -c claude .
agent-deck add -t "Child" --parent "Parent" -c claude /tmp/x
agent-deck add -t "Research" -c claude --mcp exa --mcp firecrawl /tmp/r

session

agent-deck session <command> [options] <name>

agent-deck session start "My Project"
agent-deck session send "My Project" "Hello"
agent-deck session output "My Project"
agent-deck session current -q              # Just name
agent-deck session current --json          # Full JSON

mcp

agent-deck mcp <command> [options]

Note: Run session restart after attach/detach.

group

agent-deck group <command> [options]

Other

agent-deck list [--json]     # List sessions
agent-deck status [-v|-q]    # Status summary
agent-deck remove <name>     # Remove session

Session Resolution

Commands accept:

• Title: "My Project"
• ID prefix: abc123 (≥6 chars)
• Path: /path/to/project

Exit Codes

Configuration Reference

All options for ~/.agent-deck/config.toml.

Table of Contents

• Top-Level
• [[claude] Section](#claude-section)
• [[logs] Section](#logs-section)
• [[updates] Section](#updates-section)
• [[global_search] Section](#global_search-section)
• [[mcp_pool] Section](#mcp_pool-section)
• [[mcps.*] Section](#mcps-section)
• [[tools.*] Section](#tools-section)

Top-Level

default_tool = "claude"   # Pre-selected tool when creating sessions

[claude] Section

Claude Code integration settings.

[claude]
config_dir = "~/.claude-work"   # Path to Claude config directory
dangerous_mode = true           # Enable --dangerously-skip-permissions

[logs] Section

Session log file management.

[logs]
max_size_mb = 10        # Max size before truncation
max_lines = 10000       # Lines to keep when truncating
remove_orphans = true   # Delete logs for removed sessions

Logs location: ~/.agent-deck/logs/agentdeck_<session>_<id>.log

[updates] Section

Auto-update settings.

[updates]
auto_update = false           # Auto-install updates
check_enabled = true          # Check on startup
check_interval_hours = 24     # Check frequency
notify_in_cli = true          # Show in CLI commands

[global_search] Section

Search across all Claude conversations.

[global_search]
enabled = true              # Enable global search
tier = "auto"               # "auto", "instant", "balanced"
memory_limit_mb = 100       # Max RAM for index
recent_days = 90            # Limit to last N days (0 = all)
index_rate_limit = 20       # Files/second for indexing

[mcp_pool] Section

Share MCP processes across sessions via Unix sockets.

[mcp_pool]
enabled = false             # Enable socket pooling
auto_start = true           # Start pool on launch
pool_all = false            # Pool ALL MCPs
exclude_mcps = []           # Exclude from pool_all
fallback_to_stdio = true    # Fallback if socket fails
show_pool_status = true     # Show 🔌 indicator

Benefits: 30 sessions x 5 MCPs = 150 processes -> 5 shared processes (90% memory savings).

Socket location: /tmp/agentdeck-mcp-{name}.sock

[mcps.*] Section

Define MCP servers. One section per MCP.

STDIO MCPs (Local)

[mcps.exa]
command = "npx"
args = ["-y", "exa-mcp-server"]
env = { EXA_API_KEY = "your-key" }
description = "Web search via Exa AI"

HTTP/SSE MCPs (Remote)

[mcps.remote]
url = "https://api.example.com/mcp"
transport = "http"   # or "sse"
description = "Remote MCP server"

Common MCP Examples

# Web search
[mcps.exa]
command = "npx"
args = ["-y", "@anthropics/exa-mcp"]
env = { EXA_API_KEY = "xxx" }

# GitHub
[mcps.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_TOKEN = "ghp_xxx" }

# Filesystem
[mcps.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path"]

# Sequential thinking
[mcps.thinking]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-sequential-thinking"]

# Playwright
[mcps.playwright]
command = "npx"
args = ["-y", "@anthropics/playwright-mcp"]

# Memory
[mcps.memory]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-memory"]

[tools.*] Section

Define custom AI tools.

[tools.my-ai]
command = "my-ai-assistant"
icon = "🧠"
busy_patterns = ["thinking...", "processing..."]

Built-in icons: claude=🤖, gemini=✨, opencode=🌐, codex=💻, cursor=📝, shell=🐚

Complete Example

default_tool = "claude"

[claude]
config_dir = "~/.claude-work"
dangerous_mode = true

[logs]
max_size_mb = 10
max_lines = 10000
remove_orphans = true

[updates]
check_enabled = true
check_interval_hours = 24

[global_search]
enabled = true
tier = "auto"
recent_days = 90

[mcp_pool]
enabled = false

[mcps.exa]
command = "npx"
args = ["-y", "exa-mcp-server"]
env = { EXA_API_KEY = "your-key" }
description = "Web search"

[mcps.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_TOKEN = "ghp_xxx" }
description = "GitHub access"

Environment Variables

MCP Management Guide

Guide for managing Model Context Protocol (MCP) servers with agent-deck.

Overview

MCPs extend Claude's capabilities. Agent-deck supports:

• LOCAL - Project-specific (.mcp.json file)
• GLOBAL - All projects (~/.claude-work/.claude.json)

When to Use Which

Use LOCAL when:

• MCP is specific to this project
• Different projects need different configurations

Use GLOBAL when:

• MCP is useful across all projects
• MCP provides general-purpose functionality

Commands

# List available MCPs
agent-deck mcp list

# Check what's attached
agent-deck mcp attached my-project

# Attach locally (default)
agent-deck mcp attach my-project exa

# Attach globally
agent-deck mcp attach my-project memory -global

# Attach and restart to load immediately
agent-deck mcp attach my-project playwright -restart

# Detach
agent-deck mcp detach my-project exa
agent-deck mcp detach my-project memory -global

MCP Configuration

MCPs are defined in ~/.agent-deck/config.toml:

[mcps.exa]
command = "npx"
args = ["-y", "exa-mcp-server"]
env = { EXA_API_KEY = "your-key" }
description = "Web search via Exa AI"

Best Practices

1. Start Local, Promote to Global - Test locally first 2. Use Restart Flag - For immediate effect: -restart 3. Check Attached MCPs - Before debugging tool access issues

Troubleshooting

MCP Not Available:

agent-deck mcp attached my-project  # Check if attached
agent-deck session restart my-project  # Reload MCPs

Changes Not Taking Effect:

agent-deck session restart my-project

Profile Management Guide

Guide for using profiles to organize agent-deck sessions.

Overview

Profiles provide complete isolation between different sets of sessions.

Common Use Cases:

• Personal vs Work separation
• Client isolation
• Testing/demo environments

Commands

# List profiles
agent-deck profile list

# Create profile
agent-deck profile create work

# Set default
agent-deck profile default work

# Use specific profile
agent-deck -p work list
agent-deck -p work session start my-project

# Delete profile
agent-deck profile delete old-profile

Profile Storage

~/.agent-deck/profiles/
├── default/
│   └── sessions.json
├── work/
│   └── sessions.json
└── demo/
    └── sessions.json

Environment Variable

export AGENTDECK_PROFILE=work
agent-deck list  # Uses 'work' profile

Best Practices

1. Use explicit -p flag for important operations 2. Use consistent naming conventions 3. Set a default profile for primary usage

Troubleshooting Guide

Common issues and solutions for agent-deck.

Quick Fixes

Common Issues

Flags Ignored

Problem: Flags after positional arguments are silently ignored.

# WRONG - message not sent
agent-deck session start my-project -m "Hello"

# CORRECT
agent-deck session start -m "Hello" my-project

MCP Not Available

1. Check if attached: agent-deck mcp attached <session> 2. Restart session: agent-deck session restart <session> 3. Verify in config: agent-deck mcp list

Session ID Not Detected

Claude session ID needed for fork/resume. Check:

agent-deck session show <name> --json | jq '.claude_session_id'

If null, restart session and interact with Claude.

High CPU Usage

With many sessions: Normal if batched updates. Check:

agent-deck status  # Should show ~0.5% CPU when idle

With active session: Normal (live preview updates).

Log Files Too Large

Add to ~/.agent-deck/config.toml:

[logs]
max_size_mb = 1
max_lines = 2000

Global Search Not Working

Check config:

[global_search]
enabled = true

Also verify ~/.claude/projects/ exists and has content.

Debugging

Enable debug logging:

AGENTDECK_DEBUG=1 agent-deck

Check session logs:

tail -100 ~/.agent-deck/logs/agentdeck_<session>_*.log

Report a Bug

If something isn't working, please create a GitHub issue with all relevant context.

Step 1: Gather Information

Run these commands and save output:

# Version info
agent-deck version

# Current status
agent-deck status --json

# Session details (if session-related)
agent-deck session show <session-name> --json

# Config (sanitized - removes secrets)
cat ~/.agent-deck/config.toml | grep -v "KEY\|TOKEN\|SECRET\|PASSWORD"

# Recent logs (if error occurred)
tail -100 ~/.agent-deck/logs/agentdeck_<session>_*.log 2>/dev/null

# System info
uname -a
echo "tmux: $(tmux -V 2>/dev/null || echo 'not installed')"

Step 2: Describe the Issue

Prepare clear answers to:

1. What did you try? (exact command or TUI action) 2. What happened? (error message, unexpected behavior) 3. What did you expect? (correct behavior) 4. Can you reproduce it? (steps to trigger)

Step 3: Create GitHub Issue

Go to: https://github.com/asheshgoplani/agent-deck/issues/new

Use this template:

## Description

[Brief description of the issue]

## Steps to Reproduce

1. [First step]
2. [Second step]
3. [What happened]

## Expected Behavior

[What should have happened]

## Environment

- agent-deck version: [output of `agent-deck version`]
- OS: [macOS/Linux/WSL]
- tmux version: [output of `tmux -V`]

## Debug Output

<details>
<summary>Status JSON</summary>

[paste agent-deck status --json]

</details>

<details>
<summary>Config (sanitized)</summary>

[paste sanitized config]

</details>

<details>
<summary>Logs</summary>

[paste relevant log lines]

</details>

Step 4: Follow Up

• Check for responses on your issue
• Test any suggested fixes
• Update issue with results

Recovery

Session Metadata Lost

Backups at:

~/.agent-deck/profiles/default/sessions.json.bak
~/.agent-deck/profiles/default/sessions.json.bak.1
~/.agent-deck/profiles/default/sessions.json.bak.2

Restore:

cp ~/.agent-deck/profiles/default/sessions.json.bak \
   ~/.agent-deck/profiles/default/sessions.json

tmux Sessions Lost

Session logs preserved:

tail -500 ~/.agent-deck/logs/agentdeck_<session>_*.log

Profile Corrupted

Create fresh:

agent-deck profile create fresh
agent-deck profile default fresh

Critical Warnings

NEVER run these commands - they destroy ALL agent-deck sessions:

# DO NOT RUN
tmux kill-server
tmux ls | grep agentdeck | xargs tmux kill-session

Recovery impossible - metadata backups exist but tmux sessions are gone.

TUI Reference

Complete reference for agent-deck Terminal UI features.

Keyboard Shortcuts

Navigation

Session Actions

Group Actions

Search & Filter

Global

Status Indicators

Dialogs

New Session (n)

Fields:

• Session name (required)
• Project path (required, supports ~/)
• Command (claude/gemini/opencode/codex/custom)
• Parent group (auto-selected)

Controls: Tab move fields | Enter create | Esc cancel

MCP Manager (M)

Layout:

• Two columns: Attached | Available
• Two scopes: LOCAL | GLOBAL

Controls:

• Tab - Switch scope
• ←/→ - Switch columns
• ↑/↓ - Navigate
• Space - Toggle MCP
• Enter - Apply changes
• Esc - Cancel

Indicators:

• (l) LOCAL scope
• (g) GLOBAL scope
• (p) PROJECT scope
• 🔌 MCP is pooled
• ⟳ Pending restart

Fork Dialog (F)

Fields:

• Session title (pre-filled)
• Group (auto-selected)

Controls: Enter fork | Esc cancel

Delete Confirmation (d)

For sessions: Warning about tmux kill, process termination

For groups: Sessions move to default (not deleted)

Controls: y confirm | n/Esc cancel

Search

Local Search (/)

• Fuzzy search session titles and groups
• Max 10 results
• ↑/↓ or Ctrl+K/J navigate
• Enter select | Tab switch to global | Esc close

Global Search (G)

• Full content search across ~/.claude/projects/
• Regex + fuzzy matching
• Recency ranking
• Split view: results + preview
• [/] scroll preview
• Enter create/jump to session

Config:

[global_search]
enabled = true
recent_days = 30

Preview Pane

• Shows last ~500 lines of session's tmux pane
• Auto-updates every 2 seconds
• Launch animation: 6-15s for Claude/Gemini

Layout

• < 50 cols: List only
• 50-79 cols: Stacked (list above preview)
• 80+ cols: Side-by-side (default)

Tool Icons

Color Scheme (Tokyo Night)

Hidden Features

• `Ctrl+K/J`: Vim-style navigation in search
• Numbers 1-9: Jump to root groups instantly
• Status filters are toggles: Press again to turn off