Agent Deck Complete Guide 2026: Manage All AI Coding Agents with One TUI

This article is based on Agent Deck v1.9.57 (released 2026-06-12), with PR count reaching #1408 — the project is updating extremely actively.

1. Why Do You Need an AI Agent Manager?

The AI coding tool ecosystem has undergone a dramatic transformation in 2026. A year ago, a developer might have been fine with just Claude Code or Aider. Today, a typical mid-to-senior developer workflow might look like this:

• Claude Code handles core business logic
• OpenCode does code reviews
• Codex writes unit tests
• Gemini CLI runs quick prototypes
• Pi generates documentation

Do the math: 5 AI agents × 3 projects = 15 terminal tabs. And that's not even counting the extra terminals you open manually for debugging, database clients, and log viewers.

Terminal Tab Hell

You've probably been through these scenarios:

• Forgetting which tab belongs to which agent and running git checkout on the wrong branch
• Claude Code is waiting for your reply, but you can't find that tab
• Wanting to copy a conversation thread between two Claude sessions, only to resort to manual copy-paste
• MCP config files getting messier and messier, requiring manual edits every time you switch projects

Problems with Existing Solutions

Agent Deck was born to solve exactly this problem. It's not another AI coding tool — it's the command center for all your AI coding tools.

2. What Is Agent Deck?

Agent Deck (GitHub: asheshgoplani/agent-deck) is an open-source terminal session manager designed specifically for AI coding agents. Built on tmux, it provides a TUI (Terminal User Interface) within a single terminal window, letting you:

• See all AI agent statuses at a glance (running / waiting for input / idle / error)
• Switch between agents with a single keypress
• Fork sessions and branch new ideas from existing conversations
• Visually manage MCP services and Claude Skills
• Remotely monitor and orchestrate multiple AI agents (Conductor feature)

Core philosophy: Not yet another AI coding tool, but the command center for your terminal AI development workflow.

Key Stats

3. Installation & First Steps (5-Minute Setup)

Installation Methods

Agent Deck offers three installation methods. We recommend Homebrew for the easiest experience:

# Method 1: Homebrew (recommended, works on macOS & Linux)
brew install asheshgoplani/tap/agent-deck

# Method 2: Quick install script
curl -fsSL https://raw.githubusercontent.com/asheshgoplani/agent-deck/main/install.sh | bash

# Method 3: Go install
go install github.com/asheshgoplani/agent-deck/cmd/agent-deck@latest

Creating Your First Session

After installation, run the following in your terminal:

# Start Agent Deck TUI and create a session named project-alpha
agent-deck session start project-alpha

You'll see a tmux-based TUI interface. If you haven't configured any AI agents yet, Agent Deck will guide you through setup.

Basic TUI Navigation

Here are the most commonly used navigation shortcuts once you're in the TUI:

Filter search by status (very handy):

In-group navigation (new Alt+ shortcuts in v1.7.60+, stays within the current group):

Smart Status Indicators

Agent Deck uses intelligent polling to detect each agent's status in real time:

Waiting sessions appear directly in the tmux status bar: Press Ctrl+b, release, then press 1-6 to jump straight to the corresponding waiting session. The status bar displays like this:

⚡ [1] frontend [2] api [3] backend

4. Core Features in Action

4.1 Fork Sessions: One Feature, Multiple Implementations, Zero Interference

Forking is one of Agent Deck's most distinctive features. Picture this: you've designed an API interface with Claude Code and now want to try two different implementations. The traditional approach would be opening a new session and re-explaining everything from scratch. With Fork, all you need is:

# In the TUI, position the cursor on the session you want to fork
# Press f → Quick fork (auto-generated name)
# Press F → Custom fork name and group

The core value of Fork:

• The new session inherits the parent's complete conversation history
• Supports native fork for Claude / OpenCode / Pi / Codex (the tool's own fork capability)
• You can fork a fork, exploring as many branches as you want
• Each branch is fully isolated, making comparison easy at any point

⚠️ Note: Codex's fork feature requires codex CLI version ≥ 0.137.0.

4.2 MCP Manager: Managing MCP Services Without Touching Config Files

MCP (Model Context Protocol) services let AI agents access external tools (web search, browser automation, database queries, etc.). The traditional approach requires manually editing JSON config files. Agent Deck turns this into a visual TUI operation:

Press m in the TUI to open MCP Manager:

MCP config location: ~/.config/agent-deck/config.toml

Config example:

[[mcp_servers]]
name = "web-search"
command = "npx"
args = ["-y", "@anthropic/mcp-server-brave-search"]

Once you've configured something in the TUI, Agent Deck automatically restarts the corresponding agent session to apply the change — no manual restarts needed.

4.3 Skills Manager: Project-Level Claude Skills Management

For Claude Code users, Agent Deck includes a built-in Skills Manager for pool-based project-level Claude Skills management:

Press s in the TUI to open Skills Manager (only for Claude sessions):

• Pool-based management: The available skills list comes exclusively from the pool (~/.config/agent-deck/skills/pool), making attach/detach operations predictable
• Project-level state: Project state is written to .agent-deck/skills.toml, and skill files are materialized into the .claude/skills directory
• Type-to-jump: Same interaction pattern as MCP Manager

This means you can configure different Skill combinations for different projects:

• project-alpha: web-search + code-review skills attached
• project-beta: api-testing + docs-generation skills attached

4.4 MCP Socket Pool: Save 85% Memory in Multi-Session Scenarios

When you're running multiple sessions simultaneously and each one connects to the same MCP services, memory consumption multiplies rapidly. Agent Deck's MCP Socket Pool uses Unix Sockets to let multiple sessions share a single MCP process:

# Enable in config.toml
[mcp]
pool_all = true

Results:

• Reduces MCP memory usage by 85-90%
• When an MCP process crashes, it automatically reconnects within ~3 seconds (reconnecting proxy)
• Completely transparent to upstream agents — no code changes required

4.5 Per-Group Claude Configuration

When managing multiple Claude accounts on the same machine (say, a personal account and a work account), Agent Deck lets you configure different Claude auth for different groups:

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

Lookup priority: Environment variables > Group > Config profile > Global > Default

The env_file is loaded before the tmux pane starts, and any export statements become part of the session environment. This is extremely practical for scenarios that need different API keys or different Claude working directories.

5. Advanced Play: Conductor Orchestration

What Is Conductor?

If Agent Deck's session management is "self-driving mode," then Conductor is the "fleet commander." It's a higher-level abstraction that lets you remotely monitor and orchestrate all AI agent sessions via Telegram, Slack, or Discord.

Five-Minute Telegram Monitoring Setup

# 1. Create a Telegram Bot via @BotFather and get your token
# 2. Get your user ID via @userinfobot

# 3. Run the one-shot setup wizard (auto-configures conductor, bridge daemon, heartbeat)
agent-deck conductor setup work --description "Work fleet"

# 4. Start the conductor session
agent-deck session start conductor-work

# 5. Send /status to your bot in Telegram

From this moment on, all your Agent Deck sessions are supervised by a unified conductor session:

• Routine issues are handled automatically
• Important items are pushed to your phone
• Waiting tasks won't rot away and get forgotten

Watcher Setup: Let External Events Wake Up Your AI Agents

Beyond proactive querying, you can set up Watchers so that external events (GitHub events, Gmail, ntfy pushes, calendar reminders, etc.) can "ring the doorbell" to wake the conductor. For specific configuration, see the official Watcher documentation.

6. Agent Deck vs. Alternatives

7. Summary

Agent Deck doesn't answer "which AI coding tool is better" — it solves the problem of how to make multiple AI tools work together without driving you crazy.

Core Value Recap:

1. One-stop control: Manage all AI agents in a single terminal window — goodbye tab hell
2. Fork sessions: Branch new ideas from existing conversations — no need to re-explain requirements
3. Visual MCP/Skills management: No more manual config file editing
4. MCP Socket Pool: Significantly reduce memory consumption in multi-session scenarios
5. Conductor remote monitoring: Stay on top of your AI agents from anywhere via Telegram / Slack
6. Git Worktree integration: Multiple agents collaborating on the same repo without stepping on each other

If you're already facing the "too many AI agents" problem, Agent Deck is currently the most mature open-source solution in this niche. And it's updating incredibly fast (v1.9.56 → v1.9.57 in just 4 hours), with an active community (PR #1408+), making it well worth following.

Related Links:

• 📦 Agent Deck GitHub Repository
• 📋 Latest Release
• 📖 Complete Conductor Setup Guide
• 📖 Watcher Setup Guide
• 💬 Discord Community

Recommended Reading:

• Aider Complete Guide — Git-first Terminal AI Programming Assistant
• CC Switch: Multi-Model AI Coding Management