Agent Deck

Your AI agent command center

Features . Conductor . Install . Quick Start . Docs . Discord . FAQ

Option 1: Claude Code Skill (recommended for Claude Code users)

/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)

# 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/llms-full.txt
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), type to jump
• Define your MCPs once in ~/.agent-deck/config.toml, then toggle per session — see Configuration Reference

Skills Manager

Attach/detach Claude skills per project with a managed pool workflow.

• Press s to open Skills Manager for a Claude session
• Available list is pool-only (~/.agent-deck/skills/pool) to keep attach/detach deterministic
• Apply writes project state to .agent-deck/skills.toml and materializes into .claude/skills
• Type-to-jump is supported in the dialog (same pattern as MCP Manager)

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.

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, release, then press 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 finish "My Session" merges the branch, removes the worktree, and deletes the session
• agent-deck worktree cleanup finds and removes orphaned worktrees

Configure the default worktree location in ~/.agent-deck/config.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 <path>/<repo_name>/<branch>. The --location flag overrides the config per session.

Worktree Setup Script

Gitignored files (.env, .mcp.json, etc.) aren't copied into new worktrees. To automate this, create a setup script at .agent-deck/worktree-setup.sh in your repo. Agent-deck runs it automatically after creating a worktree.

#!/bin/sh
for f in .env .env.local .mcp.json; do
    [ -f "$AGENT_DECK_REPO_ROOT/$f" ] && cp "$AGENT_DECK_REPO_ROOT/$f" "$AGENT_DECK_WORKTREE_PATH/$f"
done

The script receives two environment variables:

• AGENT_DECK_REPO_ROOT — path to the main repository
• AGENT_DECK_WORKTREE_PATH — path to the new worktree

The script runs via sh -e with a 60-second timeout. If it fails, the worktree is still created — you'll see a warning but the session proceeds normally.

Docker Sandbox

Run sessions inside isolated Docker containers. The project directory is bind-mounted read-write, so agents work on your code while the rest of the system stays protected.

• Check "Run in Docker sandbox" when creating a session, or set default_enabled = true in config
• Press T on a sandboxed session to open a container shell
• agent-deck try "task description" runs a one-shot sandboxed session

Host tool auth (Claude, Gemini, Codex, etc.) is automatically shared into containers via shared sandbox directories — no re-authentication needed. On macOS, Keychain credentials are extracted too.

[docker]
default_enabled = true
mount_ssh = true
auto_cleanup = true    # Remove containers when sessions end (default: true)

Set auto_cleanup = false to keep containers alive after session termination, which is useful for debugging container state or inspecting logs.

See the Docker Sandbox Guide for the full reference including overlay details, custom images, and troubleshooting.

Conductor

Conductors are persistent agent sessions that monitor and orchestrate all your other sessions. They watch for sessions that need help, auto-respond when confident, and escalate to you when they can't. Optionally connect Telegram and/or Slack for remote control.

Create as many conductors as you need per profile:

# First-time setup (asks about Telegram/Slack, then creates the conductor)
agent-deck -p work conductor setup ops --description "Ops monitor"

# Add more conductors to the same profile (no prompts)
agent-deck -p work conductor setup infra --description "Infra watcher"
agent-deck conductor setup personal --description "Personal project monitor"

# Run a conductor on Codex instead of Claude Code
agent-deck -p work conductor setup review --agent codex --description "Codex reviewer"

# Use a custom agent endpoint via environment variables
agent-deck conductor setup glm-bot \
  -env ANTHROPIC_BASE_URL=https://api.z.ai/api/anthropic \
  -env ANTHROPIC_AUTH_TOKEN=<token> \
  -env ANTHROPIC_DEFAULT_OPUS_MODEL=glm-5

# Or use an env file
agent-deck conductor setup glm-bot -env-file ~/.conductor.env

Each conductor gets its own directory, identity, and settings:

~/.agent-deck/conductor/
├── CLAUDE.md           # Shared knowledge for Claude conductors
├── AGENTS.md           # Shared knowledge for Codex conductors
├── bridge.py           # Bridge daemon (Telegram/Slack, if configured)
├── ops/
│   ├── CLAUDE.m