Agent Deck

Your AI agent command center

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

Agent Deck is mission control for your AI coding agents. Running Claude Code on ten projects, OpenCode on five more, another agent somewhere in the background? One terminal shows every session — running, waiting, or done — and one keystroke switches between them. Groups, search, forking, git worktrees, cost tracking, and a phone-controlled conductor keep a whole fleet manageable.

https://github.com/user-attachments/assets/e4f55917-435c-45ba-92cc-89737d0d1401

Installation

Works on: macOS, Linux, Windows (WSL)

curl -fsSL https://raw.githubusercontent.com/asheshgoplani/agent-deck/main/install.sh | bash

Then run: agent-deck

Homebrew

brew install asheshgoplani/tap/agent-deck

Go

go install github.com/asheshgoplani/agent-deck/cmd/agent-deck@latest

From Source

git clone https://github.com/asheshgoplani/agent-deck.git && cd agent-deck && make install

agent-deck uninstall              # Interactive uninstall
agent-deck uninstall --keep-data  # Remove binary only, keep sessions

See Troubleshooting for full details.

Quick Start

agent-deck                        # Launch TUI
agent-deck add . -c claude        # Add current dir with Claude
agent-deck session fork my-proj   # Fork a supported session
agent-deck session remove my-proj # Remove stopped/errored session from registry (transcripts preserved)
agent-deck mcp attach my-proj exa # Attach MCP to session
agent-deck skill attach my-proj docs --source pool --restart # Attach skill + restart
agent-deck web                    # Start web UI on http://127.0.0.1:8420

⚠️ Changed in v1.9.55: in the new-session dialog (n), Enter advances to the next field on the Name and Branch inputs instead of submitting — typing a name and hitting Enter no longer creates a session with all defaults. Ctrl+S creates the session from any field. The dialog also remembers your last-used tool. Restore the old behavior with [ui].new_session_enter_advances = false.

Key Shortcuts

See TUI Reference for all shortcuts and CLI Reference for all commands.

Quickstart: orchestrate a fleet of AI agents

Five minutes from zero to a Telegram bot that watches every Claude session you have running.

# 1. Create a Telegram bot via @BotFather, grab the token + your user ID from @userinfobot.
# 2. Run the wizard — it sets up the conductor, bridge daemon, and heartbeat in one shot.
agent-deck conductor setup work --description "Work fleet"
agent-deck session start conductor-work
# 3. Message your bot:  /status

That's it. From now on every other agent-deck session you run is supervised by a single "conductor" session that answers routine questions, escalates the interesting ones to your phone, and never lets a waiting worker rot.

Two short guides to read next:

• docs/conductor/ — two-minute local quickstart, architecture, state files, lifecycle, remote channel setup (Telegram/Slack/Discord), gotchas.
• docs/WATCHER-SETUP.md — add "doorbells" so the outside world (GitHub events, gmail, ntfy pushes, meetings) can wake the conductor up.

Features

Fork Sessions

Try different approaches without losing context. Fork Claude, OpenCode, Pi, and Codex sessions instantly. Each fork inherits the parent conversation history through the tool's native fork support.

• Press f for quick fork, F to customize name/group
• Fork your forks to explore as many branches as you need
• Codex forking requires a codex CLI with codex fork <session-id> support (verified with codex-cli 0.137.0)

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 $XDG_CONFIG_HOME/agent-deck/config.toml (default ~/.config/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 ($XDG_CONFIG_HOME/agent-deck/skills/pool, default ~/.config/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)

Declarative groups

Declare groups in config.toml so they exist on startup. Set create = true to ensure a group exists, and default_path to set the working directory for new sessions in it:

[groups."staging"]
create = true                      # ensure the group exists

[groups."projects/devops"]
create = true
default_path = "~/repos/devops"    # working directory for new sessions

On startup each group with create = true is created if missing (along with any parent groups). default_path is written to the state DB for any group that exists — including groups created from your sessions — so create = true is optional when the group is already there. Reconciliation is additive: removing a group from config.toml leaves the group and its sessions in place, and omitting default_path keeps any value already set. Clear a default with agent-deck group update <name> --clear-default-path.

Per-group Claude config

Agent Deck supports per-group CLAUDE_CONFIG_DIR and env_file overrides. Useful when a single profile hosts groups that should authenticate against different Claude accounts — for example, a personal profile hosting a conductor group pinned to ~/.claude-team while other groups stay on ~/.claude.

Override any group by adding a [groups."<name>".claude] table to $XDG_CONFIG_HOME/agent-deck/config.toml (default ~/.config/agent-deck/config.toml):

[groups."conductor".claude]
config_dir = "~/.claude-team"
env_file = "~/git/work/.envrc"

Lookup priority: env > group > profile > global > default. The env_file is sourced into the tmux pane before claude (or the custom command) execs, so any exports it contains become part of the session environment.

Human-watchable verification: bash scripts/verify-per-group-claude-config.sh. The harness creates two throwaway groups, launches one normal and one custom-command session, and prints a pass/fail table.

Per-conductor Claude config (v1.5.4)

Conductors are first-class agent-deck entities (see agent-deck conductor setup). Each conductor can carry its own Claude config_dir and env_file via a top-level [conductors.<name>.claude] block:

[conductors.gsd-v154.claude]
config_dir = "~/.claude-team"
env_file = "~/git/work/.envrc"

The conductor name is the string you passed to agent-deck conductor setup <name> — it's the same name that appears in session titles (conductor-<name>).

Precedence chain (most-specific → least-specific):

1. CLAUDE_CONFIG_DIR env var
2. [conductors.<name>.claude] (when the session is a conductor session, i.e. Title starts with conductor-)
3. [groups."<group>".claude] (PR #578)
4. [profiles.<profile>.claude]
5. [claude] (global)
6. ~/.claude (default)

This means a single [conductors.gsd-v154.claude] line replaces the need to duplicate the config