.json # Import received session $SKILL_DIR/../session-share/scripts/import.sh ~/Downloads/session-file.json ``` **See:** [session-share skill](../session-share/SKILL.md) 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](references/cli-reference.md) - Complete CLI command reference - [config-reference.md](references/config-reference.md) - All config.toml options - [tui-reference.md](references/tui-reference.md) - TUI features and shortcuts - [troubleshooting.md](references/troubleshooting.md) - Common issues and bug reporting - [session-share skill](../session-share/SKILL.md) - Export/import sessions for collaboration --- # CLI REFERENCE # CLI Command Reference Complete reference for all agent-deck CLI commands. ## Table of Contents - [Global Options](#global-options) - [Basic Commands](#basic-commands) - [Session Commands](#session-commands) - [MCP Commands](#mcp-commands) - [Group Commands](#group-commands) - [Profile Commands](#profile-commands) ## Global Options ```bash -p, --profile <name> Use specific profile --json JSON output -q, --quiet Minimal output ``` ## Basic Commands ### add - Create session ```bash agent-deck add [path] [options] ``` | Flag | Description | |------|-------------| | `-t, --title` | Session title | | `-g, --group` | Group path | | `-c, --cmd` | Command (claude, gemini, opencode, codex, custom) | | `--parent` | Parent session (creates child) | | `--mcp` | Attach MCP (repeatable) | ```bash 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 ``` ### list - List sessions ```bash agent-deck list [--json] [--all] agent-deck ls # Alias ``` ### remove - Remove session ```bash agent-deck remove <id|title> agent-deck rm # Alias ``` ### status - Status summary ```bash agent-deck status [-v|-q|--json] ``` - Default: `2 waiting - 5 running - 3 idle` - `-v`: Detailed list by status - `-q`: Just waiting count (for scripts) ## Session Commands ### session start ```bash agent-deck session start <id|title> [-m "message"] [--json] [-q] ``` `-m` sends initial message after agent is ready. **CRITICAL:** Flags MUST come BEFORE session name! ```bash # Correct agent-deck session start -m "Hello" my-project # WRONG - flag ignored! agent-deck session start my-project -m "Hello" ``` ### session stop ```bash agent-deck session stop <id|title> ``` ### session restart ```bash agent-deck session restart <id|title> ``` Reloads MCPs without losing conversation (Claude/Gemini). ### session fork (Claude only) ```bash agent-deck session fork <id|title> [-t "title"] [-g "group"] ``` Creates new session with same Claude conversation. **Requirements:** - Session must be Claude tool - Must have valid Claude session ID ### session attach ```bash agent-deck session attach <id|title> ``` Interactive PTY mode. Press `Ctrl+Q` to detach. ### session show ```bash agent-deck session show [id|title] [--json] [-q] ``` Auto-detects current session if no ID provided. **JSON output includes:** - Session details (id, title, status, path, group, tool) - Claude/Gemini session ID - Attached MCPs (local, global, project) - tmux session name ### session current ```bash agent-deck session current [--json] [-q] ``` Auto-detect current session and profile from tmux environment. ```bash # Human-readable agent-deck session current # Session: test, Profile: work, ID: c5bfd4b4, Status: running # For scripts agent-deck session current -q # test # JSON agent-deck session current --json # {"session":"test","profile":"work","id":"c5bfd4b4",...} ``` **Profile auto-detection priority:** 1. `AGENTDECK_PROFILE` env var 2. Parse from `CLAUDE_CONFIG_DIR` (`~/.claude-work` -> `work`) 3. Config default or `default` ### session set ```bash agent-deck session set <id|title> <field> <value> ``` **Fields:** title, path, command, tool, claude-session-id, gemini-session-id ### session send ```bash agent-deck session send <id|title> "message" [--no-wait] [-q] [--json] ``` Default: Waits for agent readiness before sending. ### session output ```bash agent-deck session output [id|title] [--json] [-q] ``` Get last response from Claude/Gemini session. ### session set-parent / unset-parent ```bash agent-deck session set-parent <session> <parent> agent-deck session unset-parent <session> ``` ## MCP Commands ### mcp list ```bash agent-deck mcp list [--json] [-q] ``` ### mcp attached ```bash agent-deck mcp attached [id|title] [--json] [-q] ``` Shows MCPs from LOCAL, GLOBAL, PROJECT scopes. ### mcp attach ```bash agent-deck mcp attach <session> <mcp> [--global] [--restart] ``` - `--global`: Write to Claude config (all projects) - `--restart`: Restart session immediately ### mcp detach ```bash agent-deck mcp detach <session> <mcp> [--global] [--restart] ``` ## Group Commands ### group list ```bash agent-deck group list [--json] [-q] ``` ### group create ```bash agent-deck group create <name> [--parent <group>] ``` ### group delete ```bash agent-deck group delete <name> [--force] ``` `--force`: Move sessions to parent and delete. ### group move ```bash agent-deck group move <session> <group> ``` Use `""` or `root` to move to default group. ## Profile Commands ```bash agent-deck profile list agent-deck profile create <name> agent-deck profile delete <name> agent-deck profile default [name] ``` ## Session Resolution Commands accept: - **Title:** `"My Project"` (exact match) - **ID prefix:** `abc123` (6+ chars) - **Path:** `/path/to/project` - **Current:** Omit ID in tmux (uses env var) ## Exit Codes | Code | Meaning | |------|---------| | 0 | Success | | 1 | Error | | 2 | Not found | --- # CONFIG REFERENCE # Configuration Reference All options for `~/.agent-deck/config.toml`. ## Table of Contents - [Top-Level](#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 ```toml default_tool = "claude" # Pre-selected tool when creating sessions ``` ## [claude] Section Claude Code integration settings. ```toml [claude] config_dir = "~/.claude-work" # Path to Claude config directory dangerous_mode = true # Enable --dangerously-skip-permissions ``` | Key | Type | Default | Description | |-----|------|---------|-------------| | `config_dir` | string | `~/.claude` | Claude config directory. Override with `CLAUDE_CONFIG_DIR` env. | | `dangerous_mode` | bool | `false` | Skip Claude permission dialogs. Required for automation. | ## [logs] Section Session log file management. ```toml [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 ``` | Key | Type | Default | Description | |-----|------|---------|-------------| | `max_size_mb` | int | `10` | Max log file size in MB. | | `max_lines` | int | `10000` | Lines to keep after truncation. | | `remove_orphans` | bool | `true` | Clean up logs for deleted sessions. | **Logs location:** `~/.agent-deck/logs/agentdeck_<session>_<id>.log` ## [updates] Section Auto-update settings. ```toml [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 ``` | Key | Type | Default | Description | |-----|------|---------|-------------| | `auto_update` | bool | `false` | Install updates without prompting. | | `check_enabled` | bool | `true` | Enable startup update checks. | | `check_interval_hours` | int | `24` | Hours between checks. | | `notify_in_cli` | bool | `true` | Show updates in CLI (not just TUI). | ## [global_search] Section Search across all Claude conversations. ```toml [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 ``` | Key | Type | Default | Description | |-----|------|---------|-------------| | `enabled` | bool | `true` | Enable `G` key global search. | | `tier` | string | `"auto"` | Strategy: `instant` (fast, more RAM), `balanced` (LRU cache). | | `memory_limit_mb` | int | `100` | Max memory for balanced tier. | | `recent_days` | int | `90` | Only search recent conversations. | | `index_rate_limit` | int | `20` | Indexing speed (reduce for less CPU). | ## [mcp_pool] Section Share MCP processes across sessions via Unix sockets. ```toml [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 ``` | Key | Type | Default | Description | |-----|------|---------|-------------| | `enabled` | bool | `false` | Master switch for pooling. | | `pool_all` | bool | `false` | Pool all available MCPs. | | `exclude_mcps` | array | `[]` | MCPs to exclude when `pool_all=true`. | | `fallback_to_stdio` | bool | `true` | Use stdio if socket unavailable. | **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) ```toml [mcps.exa] command = "npx" args = ["-y", "exa-mcp-server"] env = { EXA_API_KEY = "your-key" } description = "Web search via Exa AI" ``` | Key | Type | Required | Description | |-----|------|----------|-------------| | `command` | string | Yes | Executable (npx, docker, node, python). | | `args` | array | No | Command arguments. | | `env` | map | No | Environment variables. | | `description` | string | No | Help text in MCP Manager. | ### HTTP/SSE MCPs (Remote) ```toml [mcps.remote] url = "https://api.example.com/mcp" transport = "http" # or "sse" headers = { Authorization = "Bearer token" } # Optional auth headers description = "Remote MCP server" ``` | Key | Type | Required | Description | |-----|------|----------|-------------| | `url` | string | Yes | HTTP/SSE endpoint URL. | | `transport` | string | No | "http" (default) or "sse". | | `headers` | map | No | HTTP headers (e.g., Authorization). | | `description` | string | No | Help text in MCP Manager. | ### HTTP MCPs with Auto-Start Server For MCPs that require a local server process (e.g., `piekstra/slack-mcp-server`), add a `[mcps.NAME.server]` block: ```toml [mcps.slack] url = "http://localhost:30000/mcp/" transport = "http" description = "Slack 23+ tools" [mcps.slack.headers] Authorization = "Bearer xoxb-token" [mcps.slack.server] command = "uvx" args = ["--python", "3.12", "slack-mcp-server", "--port", "30000"] startup_timeout = 5000 health_check = "http://localhost:30000/health" [mcps.slack.server.env] SLACK_API_TOKEN = "xoxb-token" ``` | Key | Type | Required | Description | |-----|------|----------|-------------| | `command` | string | Yes | Server executable. | | `args` | array | No | Command arguments. | | `env` | map | No | Server environment variables. | | `startup_timeout` | int | No | Timeout in ms (default: 5000). | | `health_check` | string | No | Health endpoint URL (defaults to main URL). | **How it works:** - Agent-deck starts the server automatically when the MCP is attached - If the URL is already reachable (external server), uses it without spawning - Health monitor restarts failed servers automatically - CLI: `agent-deck mcp server status/start/stop` ### Common MCP Examples ```toml # 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. ```toml [tools.my-ai] command = "my-ai-assistant" icon = "🧠" busy_patterns = ["thinking...", "processing..."] ``` | Key | Type | Required | Description | |-----|------|----------|-------------| | `command` | string | Yes | Command to run. | | `icon` | string | No | Emoji for TUI (default: 🐚). | | `busy_patterns` | array | No | Strings indicating busy state. | **Built-in icons:** claude=🤖, gemini=✨, opencode=🌐, codex=💻, cursor=📝, shell=🐚 ## Complete Example ```toml 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 | Variable | Purpose | |----------|---------| | `AGENTDECK_PROFILE` | Override default profile | | `CLAUDE_CONFIG_DIR` | Override Claude config dir | | `AGENTDECK_DEBUG=1` | Enable debug logging | --- # TROUBLESHOOTING # Troubleshooting Guide Common issues and solutions for agent-deck. ## Quick Fixes | Issue | Solution | |-------|----------| | Session shows `✕` error | `agent-deck session start <name>` | | MCPs not loading | `agent-deck session restart <name>` | | CLI changes not in TUI | Press `Ctrl+R` to refresh | | Flag not working | Put flags BEFORE arguments | | Fork fails | Check session has valid Claude session ID | | Status stuck | Wait 2 seconds or press `u` to mark unread | ## Common Issues ### Flags Ignored **Problem:** Flags after positional arguments are silently ignored. ```bash # 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: ```bash 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: ```bash 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`: ```toml [logs] max_size_mb = 1 max_lines = 2000 ``` ### Global Search Not Working Check config: ```toml [global_search] enabled = true ``` Also verify `~/.claude/projects/` exists and has content. ## Debugging Enable debug logging: ```bash AGENTDECK_DEBUG=1 agent-deck ``` Check session logs: ```bash 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: ```bash # 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: ```markdown ## 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> ```json [paste agent-deck status --json] ``` </details> <details> <summary>Config (sanitized)</summary> ```toml [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: ```bash ~/.agent-deck/profiles/default/sessions.json.bak ~/.agent-deck/profiles/default/sessions.json.bak.1 ~/.agent-deck/profiles/default/sessions.json.bak.2 ``` Restore: ```bash cp ~/.agent-deck/profiles/default/sessions.json.bak \ ~/.agent-deck/profiles/default/sessions.json ``` ### tmux Sessions Lost Session logs preserved: ```bash tail -500 ~/.agent-deck/logs/agentdeck_<session>_*.log ``` ### Profile Corrupted Create fresh: ```bash agent-deck profile create fresh agent-deck profile default fresh ``` ## Uninstalling Remove agent-deck from your system: ```bash agent-deck uninstall # Interactive uninstall agent-deck uninstall --dry-run # Preview what would be removed agent-deck uninstall --keep-data # Remove binary only, keep sessions ``` Or use the standalone script: ```bash curl -fsSL https://raw.githubusercontent.com/asheshgoplani/agent-deck/main/uninstall.sh | bash ``` **What gets removed:** - **Binary:** `~/.local/bin/agent-deck` or `/usr/local/bin/agent-deck` - **Homebrew:** `agent-deck` package (if installed via brew) - **tmux config:** The `# agent-deck configuration` block in `~/.tmux.conf` - **Data directory:** `~/.agent-deck/` (sessions, logs, config) Use `--keep-data` to preserve your sessions and configuration. ## Critical Warnings **NEVER run these commands - they destroy ALL agent-deck sessions:** ```bash # 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 # TUI Reference Complete reference for agent-deck Terminal UI features. ## Keyboard Shortcuts ### Navigation | Key | Action | |-----|--------| | `j` / `↓` | Move down | | `k` / `↑` | Move up | | `h` / `←` | Collapse group / go to parent | | `l` / `→` / `Tab` | Toggle expand/collapse group | | `1-9` | Jump to Nth root group | ### Session Actions | Key | Action | |-----|--------| | `Enter` | Attach to session OR toggle group | | `n` | New session (inherits current group) | | `r` | Rename session or group | | `R` | Restart session (reloads MCPs) | | `K` / `J` | Move item up/down in order | | `m` | Move session to different group | | `M` | Open MCP Manager (Claude/Gemini) | | `d` | Delete session or group | | `u` | Mark unread (idle -> waiting) | | `f` | Quick fork (Claude only) | | `F` | Fork with options (Claude only) | ### Group Actions | Key | Action | |-----|--------| | `g` | Create group (subgroup if on group) | | `e` | Rename group (alias for `r`) | ### Search & Filter | Key | Action | |-----|--------| | `/` | Local search (fuzzy) | | `G` | Global search (all Claude conversations) | | `Tab` | Switch between local/global search | | `0` | Clear filter (show all) | | `!` | Filter: running only (toggle) | | `@` | Filter: waiting only (toggle) | | `#` | Filter: idle only (toggle) | | `$` | Filter: error only (toggle) | ### Global | Key | Action | |-----|--------| | `?` | Help overlay | | `i` | Import existing tmux sessions | | `Ctrl+R` | Manual refresh | | `Ctrl+Q` | Detach (keep tmux running) | | `q` / `Ctrl+C` | Quit | ## Status Indicators | Symbol | Status | Color | Meaning | |--------|--------|-------|---------| | `●` | Running | Green | Active, content changed in last 2s | | `◐` | Waiting | Yellow | Stopped, unacknowledged | | `○` | Idle | Gray | Stopped, acknowledged | | `✕` | Error | Red | tmux session doesn't exist | | `⟳` | Starting | Yellow | Session launching | ## 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:** ```toml [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 | Tool | Icon | Color | |------|------|-------| | Claude | 🤖 | Orange | | Gemini | ✨ | Purple | | OpenCode | 🌐 | Cyan | | Codex | 💻 | Cyan | | Cursor | 📝 | Blue | | Shell | 🐚 | Default | ## Color Scheme (Tokyo Night) | Element | Color | |---------|-------| | Accent (selection) | #7aa2f7 | | Running | #9ece6a | | Waiting | #e0af68 | | Error | #f7768e | | Groups | #7dcfff | | Background | #1a1b26 | | Surface | #24283b | ## 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

# Agent Deck - Complete Documentation for AI Assistants This file contains complete documentation for AI/LLM consumption. --- # README

# Agent Deck **Your AI agent command center** [![GitHub Stars](https://img.shields.io/github/stars/asheshgoplani/agent-deck?style=for-the-badge&logo=github&color=yellow&labelColor=1a1b26)](https://github.com/asheshgoplani/agent-deck/stargazers) [![Go Version](https://img.shields.io/badge/Go-1.24+-00ADD8?style=for-the-badge&logo=go&labelColor=1a1b26)](https://go.dev) [![License](https://img.shields.io/badge/License-MIT-9ece6a?style=for-the-badge&labelColor=1a1b26)](LICENSE) [![Platform](https://img.shields.io/badge/Platform-macOS%20%7C%20Linux%20%7C%20WSL-7aa2f7?style=for-the-badge&labelColor=1a1b26)](https://github.com/asheshgoplani/agent-deck) [![Latest Release](https://img.shields.io/github/v/release/asheshgoplani/agent-deck?style=for-the-badge&color=e0af68&labelColor=1a1b26)](https://github.com/asheshgoplani/agent-deck/releases) [Features](#features) . [Install](#installation) . [Quick Start](#quick-start) . [Docs](#documentation) . [FAQ](#faq)

Ask AI about Agent Deck

**Option 1: Claude Code Skill** (recommended for Claude Code users) ```bash /plugin marketplace add asheshgoplani/agent-deck /plugin install agent-deck@agent-deck-help ``` Then ask: *"How do I set up MCP pooling?"* **Option 2: OpenCode** (has built-in Claude skill compatibility) ```bash # Create skill directory mkdir -p ~/.claude/skills/agent-deck/references # Download skill and references curl -sL https://raw.githubusercontent.com/asheshgoplani/agent-deck/main/skills/agent-deck/SKILL.md \ > ~/.claude/skills/agent-deck/SKILL.md for f in cli-reference config-reference tui-reference troubleshooting; do curl -sL "https://raw.githubusercontent.com/asheshgoplani/agent-deck/main/skills/agent-deck/references/${f}.md" \ > ~/.claude/skills/agent-deck/references/${f}.md done ``` OpenCode will auto-discover the skill from `~/.claude/skills/`. **Option 3: Any LLM** (ChatGPT, Claude, Gemini, etc.) ``` Read https://raw.githubusercontent.com/asheshgoplani/agent-deck/main/README.md and answer: How do I fork a session? ```

https://github.com/user-attachments/assets/e4f55917-435c-45ba-92cc-89737d0d1401 ## The Problem Running Claude Code on 10 projects? OpenCode on 5 more? Another agent somewhere in the background? **Managing multiple AI sessions gets messy fast.** Too many terminal tabs. Hard to track what's running, what's waiting, what's done. Switching between projects means hunting through windows. ## The Solution **Agent Deck is mission control for your AI coding agents.** One terminal. All your agents. Complete visibility. - **See everything at a glance** — running, waiting, or idle status for every agent instantly - **Switch in milliseconds** — jump between any session with a single keystroke - **Stay organized** — groups, search, notifications, and git worktrees keep everything manageable ## Features ### Fork Sessions Try different approaches without losing context. Fork any Claude conversation instantly. Each fork inherits the full conversation history. - Press `f` for quick fork, `F` to customize name/group - Fork your forks to explore as many branches as you need ### MCP Manager Attach MCP servers without touching config files. Need web search? Browser automation? Toggle them on per project or globally. Agent Deck handles the restart automatically. - Press `M` to open, `Space` to toggle, `Tab` to cycle scope (LOCAL/GLOBAL) - Define your MCPs once in `~/.agent-deck/config.toml`, then toggle per session — see [Configuration Reference](skills/agent-deck/references/config-reference.md) ### MCP Socket Pool Running many sessions? Socket pooling shares MCP processes across all sessions via Unix sockets, reducing MCP memory usage by 85-90%. Connections auto-recover from MCP crashes in ~3 seconds via a reconnecting proxy. Enable with `pool_all = true` in [config.toml](skills/agent-deck/references/config-reference.md). ### Search Press `/` to fuzzy-search across all sessions. Filter by status with `!` (running), `@` (waiting), `#` (idle), `$` (error). Press `G` for global search across all Claude conversations. ### Status Detection Smart polling detects what every agent is doing right now: | Status | Symbol | What It Means | |--------|--------|---------------| | **Running** | `●` green | Agent is actively working | | **Waiting** | `◐` yellow | Needs your input | | **Idle** | `○` gray | Ready for commands | | **Error** | `✕` red | Something went wrong | ### Notification Bar Waiting sessions appear right in your tmux status bar. Press `Ctrl+b 1-6` to jump directly to them. ``` ⚡ [1] frontend [2] api [3] backend ``` ### Git Worktrees Multiple agents can work on the same repo without conflicts. Each worktree is an isolated working directory with its own branch. - `agent-deck add . -c claude --worktree feature/a --new-branch` creates a session in a new worktree - `agent-deck add . --worktree feature/b -b --location subdirectory` places the worktree under `.worktrees/` inside the repo - `agent-deck worktree cleanup` finds and removes orphaned worktrees Configure the default worktree location in `~/.agent-deck/config.toml`: ```toml [worktree] default_location = "subdirectory" # "sibling" (default), "subdirectory", or a custom path ``` `sibling` creates worktrees next to the repo (`repo-branch`). `subdirectory` creates them inside it (`repo/.worktrees/branch`). A custom path like `~/worktrees` or `/tmp/worktrees` creates repo-namespaced worktrees at `//`. The `--location` flag overrides the config per session. ### Multi-Tool Support Agent Deck works with any terminal-based AI tool: | Tool | Integration Level | |------|-------------------| | **Claude Code** | Full (status, MCP, fork, resume) | | **Gemini CLI** | Full (status, MCP, resume) | | **OpenCode** | Status detection, organization | | **Codex** | Status detection, organization | | **Cursor** (terminal) | Status detection, organization | | **Custom tools** | Configurable via `[tools.*]` in config.toml | ## Installation **Works on:** macOS, Linux, Windows (WSL) ```bash curl -fsSL https://raw.githubusercontent.com/asheshgoplani/agent-deck/main/install.sh | bash ``` Then run: `agent-deck`

Other install methods

**Homebrew** ```bash brew install asheshgoplani/tap/agent-deck ``` **Go** ```bash go install github.com/asheshgoplani/agent-deck/cmd/agent-deck@latest ``` **From Source** ```bash git clone https://github.com/asheshgoplani/agent-deck.git && cd agent-deck && make install ```

### Claude Code Skill Install the agent-deck skill for AI-assisted session management: ```bash /plugin marketplace add asheshgoplani/agent-deck /plugin install agent-deck@agent-deck ```

Uninstalling

```bash agent-deck uninstall # Interactive uninstall agent-deck uninstall --keep-data # Remove binary only, keep sessions ``` See [Troubleshooting](skills/agent-deck/references/troubleshooting.md#uninstalling) for full details.

## Quick Start ```bash agent-deck # Launch TUI agent-deck add . -c claude # Add current dir with Claude agent-deck session fork my-proj # Fork a Claude session agent-deck mcp attach my-proj exa # Attach MCP to session ``` ### Key Shortcuts | Key | Action | |-----|--------| | `Enter` | Attach to session | | `n` | New session | | `f` / `F` | Fork (quick / dialog) | | `M` | MCP Manager | | `/` / `G` | Search / Global search | | `r` | Restart session | | `d` | Delete | | `?` | Full help | See [TUI Reference](skills/agent-deck/references/tui-reference.md) for all shortcuts and [CLI Reference](skills/agent-deck/references/cli-reference.md) for all commands. ## Documentation | Guide | What's Inside | |-------|---------------| | [CLI Reference](skills/agent-deck/references/cli-reference.md) | Commands, flags, scripting examples | | [Configuration](skills/agent-deck/references/config-reference.md) | config.toml, MCP setup, custom tools, socket pool | | [TUI Reference](skills/agent-deck/references/tui-reference.md) | Keyboard shortcuts, status indicators, navigation | | [Troubleshooting](skills/agent-deck/references/troubleshooting.md) | Common issues, debugging, recovery, uninstalling | Additional resources: - [CONTRIBUTING.md](CONTRIBUTING.md) — how to contribute - [CHANGELOG.md](CHANGELOG.md) — release history ### Updates Agent Deck checks for updates automatically. Run `agent-deck update` to install, or set `auto_update = true` in [config.toml](skills/agent-deck/references/config-reference.md) for automatic updates. ## FAQ

How is this different from just using tmux?

Agent Deck adds AI-specific intelligence on top of tmux: smart status detection (knows when Claude is thinking vs. waiting), session forking with context inheritance, MCP management, global search across conversations, and organized groups. Think of it as tmux plus AI awareness.

Can I use it on Windows?

Yes, via WSL (Windows Subsystem for Linux). [Install WSL](https://learn.microsoft.com/en-us/windows/wsl/install), then run the installer inside WSL. WSL2 is recommended for full feature support including MCP socket pooling.

Will it interfere with my existing tmux setup?

No. Agent Deck creates its own tmux sessions with the prefix `agentdeck_*`. Your existing sessions are untouched. The installer backs up your `~/.tmux.conf` before adding optional config, and you can skip it with `--skip-tmux-config`.

## Development ```bash make build # Build make test # Test make lint # Lint ``` See [CONTRIBUTING.md](CONTRIBUTING.md) for details. ## Star History If Agent Deck saves you time, give us a star! It helps others discover the project. [![Star History Chart](https://api.star-history.com/svg?repos=asheshgoplani/agent-deck&type=Date)](https://star-history.com/#asheshgoplani/agent-deck&Date) ## License MIT License — see [LICENSE](LICENSE) ---

Built with [Bubble Tea](https://github.com/charmbracelet/bubbletea) and [tmux](https://github.com/tmux/tmux) **[Docs](skills/agent-deck/references/) . [Issues](https://github.com/asheshgoplani/agent-deck/issues) . [Discussions](https://github.com/asheshgoplani/agent-deck/discussions)**

--- # SKILL GUIDE --- name: agent-deck description: Terminal session manager for AI coding agents. Use when user mentions "agent-deck", "session", "sub-agent", "MCP attach", "git worktree", or needs to (1) create/start/stop/restart/fork sessions, (2) attach/detach MCPs, (3) manage groups/profiles, (4) get session output, (5) configure agent-deck, (6) troubleshoot issues, (7) launch sub-agents, or (8) create/manage worktree sessions. Covers CLI commands, TUI shortcuts, config.toml options, and automation. compatibility: claude, opencode --- # Agent Deck Terminal session manager for AI coding agents. Built with Go + Bubble Tea. **Version:** 0.8.98 | **Repo:** [github.com/asheshgoplani/agent-deck](https://github.com/asheshgoplani/agent-deck) ## 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 `/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//skills/agent-deck/scripts/` **For local development**, the path looks like: `/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 ` | Control session | | `agent-deck session send "message"` | Send message | | `agent-deck session output ` | Get last response | | `agent-deck session current [-q\|--json]` | Auto-detect current session | | `agent-deck session fork ` | Fork Claude conversation | | `agent-deck mcp list` | List available MCPs | | `agent-deck mcp attach ` | Attach MCP (then restart) | | `agent-deck status` | Quick status summary | | `agent-deck add --worktree ` | 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 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 ```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

agent-deck session restart # 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](references/config-reference.md) for all options. ## Troubleshooting | Issue | Solution | |-------|----------| | Session shows error | `agent-deck session start ` | | MCPs not loading | `agent-deck session restart ` | | 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:** 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__*.log` See [troubleshooting.md](references/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--.json # Import received session $SKILL_DIR/../session-share/scripts/import.sh ~/Downloads/session-file.json ``` **See:** [session-share skill](../session-share/SKILL.md) 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](references/cli-reference.md) - Complete CLI command reference - [config-reference.md](references/config-reference.md) - All config.toml options - [tui-reference.md](references/tui-reference.md) - TUI features and shortcuts - [troubleshooting.md](references/troubleshooting.md) - Common issues and bug reporting - [session-share skill](../session-share/SKILL.md) - Export/import sessions for collaboration --- # CLI REFERENCE # CLI Command Reference Complete reference for all agent-deck CLI commands. ## Table of Contents - [Global Options](#global-options) - [Basic Commands](#basic-commands) - [Session Commands](#session-commands) - [MCP Commands](#mcp-commands) - [Group Commands](#group-commands) - [Profile Commands](#profile-commands) ## Global Options ```bash -p, --profile <name> Use specific profile --json JSON output -q, --quiet Minimal output ``` ## Basic Commands ### add - Create session ```bash agent-deck add [path] [options] ``` | Flag | Description | |------|-------------| | `-t, --title` | Session title | | `-g, --group` | Group path | | `-c, --cmd` | Command (claude, gemini, opencode, codex, custom) | | `--parent` | Parent session (creates child) | | `--mcp` | Attach MCP (repeatable) | ```bash 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 ``` ### list - List sessions ```bash agent-deck list [--json] [--all] agent-deck ls # Alias ``` ### remove - Remove session ```bash agent-deck remove <id|title> agent-deck rm # Alias ``` ### status - Status summary ```bash agent-deck status [-v|-q|--json] ``` - Default: `2 waiting - 5 running - 3 idle` - `-v`: Detailed list by status - `-q`: Just waiting count (for scripts) ## Session Commands ### session start ```bash agent-deck session start <id|title> [-m "message"] [--json] [-q] ``` `-m` sends initial message after agent is ready. **CRITICAL:** Flags MUST come BEFORE session name! ```bash # Correct agent-deck session start -m "Hello" my-project # WRONG - flag ignored! agent-deck session start my-project -m "Hello" ``` ### session stop ```bash agent-deck session stop <id|title> ``` ### session restart ```bash agent-deck session restart <id|title> ``` Reloads MCPs without losing conversation (Claude/Gemini). ### session fork (Claude only) ```bash agent-deck session fork <id|title> [-t "title"] [-g "group"] ``` Creates new session with same Claude conversation. **Requirements:** - Session must be Claude tool - Must have valid Claude session ID ### session attach ```bash agent-deck session attach <id|title> ``` Interactive PTY mode. Press `Ctrl+Q` to detach. ### session show ```bash agent-deck session show [id|title] [--json] [-q] ``` Auto-detects current session if no ID provided. **JSON output includes:** - Session details (id, title, status, path, group, tool) - Claude/Gemini session ID - Attached MCPs (local, global, project) - tmux session name ### session current ```bash agent-deck session current [--json] [-q] ``` Auto-detect current session and profile from tmux environment. ```bash # Human-readable agent-deck session current # Session: test, Profile: work, ID: c5bfd4b4, Status: running # For scripts agent-deck session current -q # test # JSON agent-deck session current --json # {"session":"test","profile":"work","id":"c5bfd4b4",...} ``` **Profile auto-detection priority:** 1. `AGENTDECK_PROFILE` env var 2. Parse from `CLAUDE_CONFIG_DIR` (`~/.claude-work` -> `work`) 3. Config default or `default` ### session set ```bash agent-deck session set <id|title> <field> <value> ``` **Fields:** title, path, command, tool, claude-session-id, gemini-session-id ### session send ```bash agent-deck session send <id|title> "message" [--no-wait] [-q] [--json] ``` Default: Waits for agent readiness before sending. ### session output ```bash agent-deck session output [id|title] [--json] [-q] ``` Get last response from Claude/Gemini session. ### session set-parent / unset-parent ```bash agent-deck session set-parent <session> <parent> agent-deck session unset-parent <session> ``` ## MCP Commands ### mcp list ```bash agent-deck mcp list [--json] [-q] ``` ### mcp attached ```bash agent-deck mcp attached [id|title] [--json] [-q] ``` Shows MCPs from LOCAL, GLOBAL, PROJECT scopes. ### mcp attach ```bash agent-deck mcp attach <session> <mcp> [--global] [--restart] ``` - `--global`: Write to Claude config (all projects) - `--restart`: Restart session immediately ### mcp detach ```bash agent-deck mcp detach <session> <mcp> [--global] [--restart] ``` ## Group Commands ### group list ```bash agent-deck group list [--json] [-q] ``` ### group create ```bash agent-deck group create <name> [--parent <group>] ``` ### group delete ```bash agent-deck group delete <name> [--force] ``` `--force`: Move sessions to parent and delete. ### group move ```bash agent-deck group move <session> <group> ``` Use `""` or `root` to move to default group. ## Profile Commands ```bash agent-deck profile list agent-deck profile create <name> agent-deck profile delete <name> agent-deck profile default [name] ``` ## Session Resolution Commands accept: - **Title:** `"My Project"` (exact match) - **ID prefix:** `abc123` (6+ chars) - **Path:** `/path/to/project` - **Current:** Omit ID in tmux (uses env var) ## Exit Codes | Code | Meaning | |------|---------| | 0 | Success | | 1 | Error | | 2 | Not found | --- # CONFIG REFERENCE # Configuration Reference All options for `~/.agent-deck/config.toml`. ## Table of Contents - [Top-Level](#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 ```toml default_tool = "claude" # Pre-selected tool when creating sessions ``` ## [claude] Section Claude Code integration settings. ```toml [claude] config_dir = "~/.claude-work" # Path to Claude config directory dangerous_mode = true # Enable --dangerously-skip-permissions ``` | Key | Type | Default | Description | |-----|------|---------|-------------| | `config_dir` | string | `~/.claude` | Claude config directory. Override with `CLAUDE_CONFIG_DIR` env. | | `dangerous_mode` | bool | `false` | Skip Claude permission dialogs. Required for automation. | ## [logs] Section Session log file management. ```toml [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 ``` | Key | Type | Default | Description | |-----|------|---------|-------------| | `max_size_mb` | int | `10` | Max log file size in MB. | | `max_lines` | int | `10000` | Lines to keep after truncation. | | `remove_orphans` | bool | `true` | Clean up logs for deleted sessions. | **Logs location:** `~/.agent-deck/logs/agentdeck_<session>_<id>.log` ## [updates] Section Auto-update settings. ```toml [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 ``` | Key | Type | Default | Description | |-----|------|---------|-------------| | `auto_update` | bool | `false` | Install updates without prompting. | | `check_enabled` | bool | `true` | Enable startup update checks. | | `check_interval_hours` | int | `24` | Hours between checks. | | `notify_in_cli` | bool | `true` | Show updates in CLI (not just TUI). | ## [global_search] Section Search across all Claude conversations. ```toml [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 ``` | Key | Type | Default | Description | |-----|------|---------|-------------| | `enabled` | bool | `true` | Enable `G` key global search. | | `tier` | string | `"auto"` | Strategy: `instant` (fast, more RAM), `balanced` (LRU cache). | | `memory_limit_mb` | int | `100` | Max memory for balanced tier. | | `recent_days` | int | `90` | Only search recent conversations. | | `index_rate_limit` | int | `20` | Indexing speed (reduce for less CPU). | ## [mcp_pool] Section Share MCP processes across sessions via Unix sockets. ```toml [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 ``` | Key | Type | Default | Description | |-----|------|---------|-------------| | `enabled` | bool | `false` | Master switch for pooling. | | `pool_all` | bool | `false` | Pool all available MCPs. | | `exclude_mcps` | array | `[]` | MCPs to exclude when `pool_all=true`. | | `fallback_to_stdio` | bool | `true` | Use stdio if socket unavailable. | **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) ```toml [mcps.exa] command = "npx" args = ["-y", "exa-mcp-server"] env = { EXA_API_KEY = "your-key" } description = "Web search via Exa AI" ``` | Key | Type | Required | Description | |-----|------|----------|-------------| | `command` | string | Yes | Executable (npx, docker, node, python). | | `args` | array | No | Command arguments. | | `env` | map | No | Environment variables. | | `description` | string | No | Help text in MCP Manager. | ### HTTP/SSE MCPs (Remote) ```toml [mcps.remote] url = "https://api.example.com/mcp" transport = "http" # or "sse" headers = { Authorization = "Bearer token" } # Optional auth headers description = "Remote MCP server" ``` | Key | Type | Required | Description | |-----|------|----------|-------------| | `url` | string | Yes | HTTP/SSE endpoint URL. | | `transport` | string | No | "http" (default) or "sse". | | `headers` | map | No | HTTP headers (e.g., Authorization). | | `description` | string | No | Help text in MCP Manager. | ### HTTP MCPs with Auto-Start Server For MCPs that require a local server process (e.g., `piekstra/slack-mcp-server`), add a `[mcps.NAME.server]` block: ```toml [mcps.slack] url = "http://localhost:30000/mcp/" transport = "http" description = "Slack 23+ tools" [mcps.slack.headers] Authorization = "Bearer xoxb-token" [mcps.slack.server] command = "uvx" args = ["--python", "3.12", "slack-mcp-server", "--port", "30000"] startup_timeout = 5000 health_check = "http://localhost:30000/health" [mcps.slack.server.env] SLACK_API_TOKEN = "xoxb-token" ``` | Key | Type | Required | Description | |-----|------|----------|-------------| | `command` | string | Yes | Server executable. | | `args` | array | No | Command arguments. | | `env` | map | No | Server environment variables. | | `startup_timeout` | int | No | Timeout in ms (default: 5000). | | `health_check` | string | No | Health endpoint URL (defaults to main URL). | **How it works:** - Agent-deck starts the server automatically when the MCP is attached - If the URL is already reachable (external server), uses it without spawning - Health monitor restarts failed servers automatically - CLI: `agent-deck mcp server status/start/stop` ### Common MCP Examples ```toml # 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. ```toml [tools.my-ai] command = "my-ai-assistant" icon = "🧠" busy_patterns = ["thinking...", "processing..."] ``` | Key | Type | Required | Description | |-----|------|----------|-------------| | `command` | string | Yes | Command to run. | | `icon` | string | No | Emoji for TUI (default: 🐚). | | `busy_patterns` | array | No | Strings indicating busy state. | **Built-in icons:** claude=🤖, gemini=✨, opencode=🌐, codex=💻, cursor=📝, shell=🐚 ## Complete Example ```toml 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 | Variable | Purpose | |----------|---------| | `AGENTDECK_PROFILE` | Override default profile | | `CLAUDE_CONFIG_DIR` | Override Claude config dir | | `AGENTDECK_DEBUG=1` | Enable debug logging | --- # TROUBLESHOOTING # Troubleshooting Guide Common issues and solutions for agent-deck. ## Quick Fixes | Issue | Solution | |-------|----------| | Session shows `✕` error | `agent-deck session start <name>` | | MCPs not loading | `agent-deck session restart <name>` | | CLI changes not in TUI | Press `Ctrl+R` to refresh | | Flag not working | Put flags BEFORE arguments | | Fork fails | Check session has valid Claude session ID | | Status stuck | Wait 2 seconds or press `u` to mark unread | ## Common Issues ### Flags Ignored **Problem:** Flags after positional arguments are silently ignored. ```bash # 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: ```bash 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: ```bash 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`: ```toml [logs] max_size_mb = 1 max_lines = 2000 ``` ### Global Search Not Working Check config: ```toml [global_search] enabled = true ``` Also verify `~/.claude/projects/` exists and has content. ## Debugging Enable debug logging: ```bash AGENTDECK_DEBUG=1 agent-deck ``` Check session logs: ```bash 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: ```bash # 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: ```markdown ## 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> ```json [paste agent-deck status --json] ``` </details> <details> <summary>Config (sanitized)</summary> ```toml [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: ```bash ~/.agent-deck/profiles/default/sessions.json.bak ~/.agent-deck/profiles/default/sessions.json.bak.1 ~/.agent-deck/profiles/default/sessions.json.bak.2 ``` Restore: ```bash cp ~/.agent-deck/profiles/default/sessions.json.bak \ ~/.agent-deck/profiles/default/sessions.json ``` ### tmux Sessions Lost Session logs preserved: ```bash tail -500 ~/.agent-deck/logs/agentdeck_<session>_*.log ``` ### Profile Corrupted Create fresh: ```bash agent-deck profile create fresh agent-deck profile default fresh ``` ## Uninstalling Remove agent-deck from your system: ```bash agent-deck uninstall # Interactive uninstall agent-deck uninstall --dry-run # Preview what would be removed agent-deck uninstall --keep-data # Remove binary only, keep sessions ``` Or use the standalone script: ```bash curl -fsSL https://raw.githubusercontent.com/asheshgoplani/agent-deck/main/uninstall.sh | bash ``` **What gets removed:** - **Binary:** `~/.local/bin/agent-deck` or `/usr/local/bin/agent-deck` - **Homebrew:** `agent-deck` package (if installed via brew) - **tmux config:** The `# agent-deck configuration` block in `~/.tmux.conf` - **Data directory:** `~/.agent-deck/` (sessions, logs, config) Use `--keep-data` to preserve your sessions and configuration. ## Critical Warnings **NEVER run these commands - they destroy ALL agent-deck sessions:** ```bash # 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 # TUI Reference Complete reference for agent-deck Terminal UI features. ## Keyboard Shortcuts ### Navigation | Key | Action | |-----|--------| | `j` / `↓` | Move down | | `k` / `↑` | Move up | | `h` / `←` | Collapse group / go to parent | | `l` / `→` / `Tab` | Toggle expand/collapse group | | `1-9` | Jump to Nth root group | ### Session Actions | Key | Action | |-----|--------| | `Enter` | Attach to session OR toggle group | | `n` | New session (inherits current group) | | `r` | Rename session or group | | `R` | Restart session (reloads MCPs) | | `K` / `J` | Move item up/down in order | | `m` | Move session to different group | | `M` | Open MCP Manager (Claude/Gemini) | | `d` | Delete session or group | | `u` | Mark unread (idle -> waiting) | | `f` | Quick fork (Claude only) | | `F` | Fork with options (Claude only) | ### Group Actions | Key | Action | |-----|--------| | `g` | Create group (subgroup if on group) | | `e` | Rename group (alias for `r`) | ### Search & Filter | Key | Action | |-----|--------| | `/` | Local search (fuzzy) | | `G` | Global search (all Claude conversations) | | `Tab` | Switch between local/global search | | `0` | Clear filter (show all) | | `!` | Filter: running only (toggle) | | `@` | Filter: waiting only (toggle) | | `#` | Filter: idle only (toggle) | | `$` | Filter: error only (toggle) | ### Global | Key | Action | |-----|--------| | `?` | Help overlay | | `i` | Import existing tmux sessions | | `Ctrl+R` | Manual refresh | | `Ctrl+Q` | Detach (keep tmux running) | | `q` / `Ctrl+C` | Quit | ## Status Indicators | Symbol | Status | Color | Meaning | |--------|--------|-------|---------| | `●` | Running | Green | Active, content changed in last 2s | | `◐` | Waiting | Yellow | Stopped, unacknowledged | | `○` | Idle | Gray | Stopped, acknowledged | | `✕` | Error | Red | tmux session doesn't exist | | `⟳` | Starting | Yellow | Session launching | ## 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:** ```toml [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 | Tool | Icon | Color | |------|------|-------| | Claude | 🤖 | Orange | | Gemini | ✨ | Purple | | OpenCode | 🌐 | Cyan | | Codex | 💻 | Cyan | | Cursor | 📝 | Blue | | Shell | 🐚 | Default | ## Color Scheme (Tokyo Night) | Element | Color | |---------|-------| | Accent (selection) | #7aa2f7 | | Running | #9ece6a | | Waiting | #e0af68 | | Error | #f7768e | | Groups | #7dcfff | | Background | #1a1b26 | | Surface | #24283b | ## 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