Stop Drowning in Terminal Tabs! Agent Deck Is the AI Command Center You Need

How many Claude Code sessions are running right now? Five? Ten? Twenty? If you're like most developers riding the AI coding wave, you've lost count. Your terminal is a graveyard of abandoned tabs. Your tmux sessions have multiplied like rabbits. And somewhere in that mess, a critical agent is waiting for your input while you frantically hunt through windows.

Here's the brutal truth: AI agents have made us more productive and more chaotic simultaneously. Every project gets its own Claude session. Every experiment spawns another terminal. Every microservice demands its own Gemini CLI instance. Before you know it, your development environment looks like a digital tornado hit it.

But what if I told you there's a single terminal interface that transforms this chaos into command-center clarity? A tool that doesn't just manage sessions but understands what your AI agents are actually doing? Meet Agent Deck — the terminal session manager built specifically for the era of AI coding agents. One TUI. Complete visibility. Millisecond switching. And yes, it works with Claude, Gemini, OpenCode, Codex, and virtually every terminal-based AI tool you already use.

Ready to stop managing tabs and start orchestrating agents? Let's dive deep into why developers are abandoning raw tmux for this purpose-built powerhouse.

What Is Agent Deck?

Agent Deck is mission control for AI coding agents. Built by Ashesh Goplani and written in Go (1.24+), it's a Terminal User Interface (TUI) that wraps intelligent session management around the AI tools you already love. Think of it as tmux with AI awareness — it knows when Claude is thinking, when Gemini needs input, when Codex hit an error.

The project exploded onto the scene because it solves a problem that didn't exist two years ago: managing fleets of AI agents across multiple projects, tools, and contexts. Traditional terminal multiplexers were designed for human-driven sessions. Agent Deck is designed for agent-driven workflows where status detection, context inheritance, and rapid switching aren't nice-to-haves — they're essential.

What makes Agent Deck genuinely trend-worthy? It's not just session wrapping. It's the deep integration layer — MCP server management, conversation forking, git worktree isolation, Docker sandboxing, cost tracking, and even autonomous "conductor" agents that monitor and orchestrate your other agents. This isn't a wrapper; it's an operating system for AI-assisted development.

The project supports macOS, Linux, and WSL, with a thriving Discord community and rapid release cycle. The v1.7.x series alone introduced socket isolation, enhanced keyboard navigation, bare-repo worktree support, and refined conductor topologies. Development velocity is aggressive because the problem space is expanding daily as new AI tools emerge.

Key Features That Separate Agent Deck from Raw tmux

Agent Deck isn't "tmux with a skin." It's a fundamentally different architecture with AI-native capabilities:

Intelligent Status Detection

Agent Deck polls sessions and surfaces exactly what each agent is doing: Running (● green — actively working), Waiting (◐ yellow — needs your input), Idle (○ gray — ready for commands), or Error (✕ red — something broke). No more guessing which tab needs attention.

Session Forking with Full Context Inheritance

Hit f to instantly fork any Claude conversation. The new session inherits complete conversation history, letting you explore alternative approaches without losing your original thread. Fork your forks. Branch your branches. It's Git for agent conversations.

MCP Server Management Without Config File Surgery

Press m to toggle MCP servers per-project or globally. Web search, browser automation, custom tools — enable them on demand without hand-editing JSON configs. Agent Deck handles restarts automatically when you toggle.

MCP Socket Pooling for Memory Efficiency

Running 20 sessions? Socket pooling shares MCP processes across all sessions via Unix sockets, slashing memory usage by 85-90%. Connections auto-recover from MCP crashes in ~3 seconds.

Git Worktree Integration

Multiple agents on the same repo without conflicts. Each worktree is an isolated working directory with its own branch. Create, finish, and cleanup worktrees without leaving the TUI.

Docker Sandbox Isolation

Run sessions in containerized environments with automatic credential sharing. Your code is bind-mounted read-write; your system stays protected. Perfect for untrusted code or dependency isolation.

Cost Tracking Dashboard

Real-time token usage and spend monitoring across all sessions. Press $ for TUI costs, or open the web dashboard at /costs for Chart.js visualizations with live SSE updates. Set budget limits with 80% warnings and 100% hard stops.

Conductor: Autonomous Agent Orchestration

Deploy persistent "conductor" sessions that monitor your other agents, auto-respond when confident, escalate when stuck, and notify you via Telegram or Slack. It's an agent managing your agents.

Socket Isolation (v1.7.50+)

Run Agent Deck on its own tmux server so it never touches your interactive tmux configuration. Opt-in via one config line: [tmux] socket_name = "agent-deck".

Real-World Use Cases Where Agent Deck Shines

1. The Polyglot Project Lead

You're managing a microservices architecture with services in Go, Python, and TypeScript. Claude Code handles the Go API, Gemini CLI works on the Python ML pipeline, and Codex tackles the React frontend. Without Agent Deck: three terminal apps, constant alt-tabbing, lost context. With Agent Deck: one TUI, color-coded groups, instant status visibility, and $ to see which agent is burning through your API budget.

2. The Experimental Forker

You're exploring three different database migration strategies with Claude. Strategy A is promising but you want to try B and C without losing A's context. Hit f twice, name your forks, and parallelize your exploration. Each fork is a first-class session you can return to, compare, or abandon.

3. The Security-Conscious Contractor

You're reviewing untrusted third-party code. Spin up a Docker-sandboxed session with auto_cleanup = true, let Claude analyze the code, then destroy the container when done. Host credentials auto-share so Claude stays authenticated, but the filesystem is isolated.

4. The MCP Power User

Your team maintains 12 MCP servers across 8 projects. Previously: editing .mcp.json files, restarting Claude manually, praying nothing breaks. Now: define MCPs once in ~/.agent-deck/config.toml, toggle per-session with Space, scope with Tab (LOCAL/GLOBAL). Agent Deck restarts the agent automatically.

5. The Bare-Repo Git Wizard

You use the bare-repo + worktree pattern for clean branch isolation. Agent Deck v1.7.58+ resolves all three entry points (project/, project/.bare, project/worktree-a) to the same project root, runs your .agent-deck/worktree-setup.sh to copy .env files, and places new worktrees according to your [worktree] config. No manual git worktree add drudgery.

Step-by-Step Installation & Setup Guide

Quick Install (Recommended)

# One-line installer — works on macOS, Linux, WSL
curl -fsSL https://raw.githubusercontent.com/asheshgoplani/agent-deck/main/install.sh | bash

# Verify installation
agent-deck --version

# Launch the TUI
agent-deck

Alternative: Homebrew

brew install asheshgoplani/tap/agent-deck

Alternative: Go Install

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

Alternative: Build from Source

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

Initial Configuration

Create your config file at ~/.agent-deck/config.toml:

# ~/.agent-deck/config.toml

# Optional: isolate from your personal tmux server
[tmux]
socket_name = "agent-deck"

# Optional: auto-enable Docker sandboxing
[docker]
default_enabled = true
mount_ssh = true
auto_cleanup = true

# Optional: enable MCP socket pooling for memory efficiency
[mcp]
pool_all = true

# Optional: cost tracking with budget limits
[costs]
retention_days = 90
cost_line_template = "{cost_today} today | {cost_this_week} wk"

[costs.budgets]
daily_limit = 50.00
weekly_limit = 200.00

# Optional: per-group Claude config overrides
[groups."work".claude]
config_dir = "~/.claude-work"
env_file = "~/git/work/.envrc"

First Session

# Add current directory with Claude Code
agent-deck add . -c claude

# Or with Gemini CLI
agent-deck add . -c gemini

# Or launch with a specific task
agent-deck launch . -c claude -m "Refactor the auth middleware"

Web UI (Optional)

# Start web dashboard at http://127.0.0.1:8420
agent-deck web

# With authentication token
agent-deck web --token my-secret
# Access: http://127.0.0.1:8420/?token=my-secret

REAL Code Examples from Agent Deck

Let's examine actual patterns from the repository, explained in depth.

Example 1: Per-Group Claude Configuration

When a single profile hosts groups that authenticate against different Claude accounts, you need scoped overrides. Here's the exact configuration pattern from Agent Deck's documentation:

# ~/.agent-deck/config.toml

# Global default
[claude]
config_dir = "~/.claude"

# Work group uses separate Claude account
[groups."conductor".claude]
config_dir = "~/.claude-work"
env_file = "~/git/work/.envrc"

What's happening here? The [groups."conductor".claude] table overrides Claude's configuration directory and environment file only for sessions in the conductor group. The env_file is sourced into the tmux pane before claude executes, so any exports become part of that session's environment. The lookup priority is: env var > group > profile > global > default. This means your personal projects use ~/.claude while work conductors authenticate against ~/.claude-work — zero manual switching.

Example 2: Conductor Setup with Custom Agent Endpoint

Conductors are Agent Deck's killer feature for autonomous orchestration. Here's how to configure a conductor using a non-standard API endpoint:

# Setup conductor with environment variable overrides
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 for cleaner management
agent-deck conductor setup glm-bot -env-file ~/.conductor.env

The power here: You're not locked into Anthropic's official API. Any OpenAI-compatible endpoint works. The -env flags inject variables into the conductor's runtime environment, and the meta.json persists them. The conductor gets its own CLAUDE.md or AGENTS.md identity file, state.json for runtime tracking, and optional bridge.py for Telegram/Slack integration. This is how you build sovereign AI infrastructure — self-hosted models, custom endpoints, full control.

Example 3: Git Worktree with Bare Repository Layout

Agent Deck v1.7.58+ elegantly handles the bare-repo pattern. Here's the complete workflow:

# All three paths resolve to the same project root
agent-deck add project/ -c claude --worktree feature/c --new-branch
agent-deck add project/.bare -c claude --worktree feature/c --new-branch
agent-deck add project/worktree-a -c claude --worktree feature/c --new-branch

# With subdirectory location config, creates: project/.worktrees/feature-c/

Why this matters: The bare-repo layout (.bare/ directory with peer worktrees, no "main" checkout) is increasingly popular for clean branch management. Agent Deck's auto-discovery scans <projectRoot>/.bare first, then falls back to direct children. The AGENT_DECK_REPO_ROOT environment variable in your .agent-deck/worktree-setup.sh always points to project/, not the current worktree, so shared files copy correctly:

#!/bin/sh
# .agent-deck/worktree-setup.sh — runs automatically after worktree creation
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

Example 4: Worktree Cleanup and Finish

# Complete a feature: merge branch, remove worktree, delete session
agent-deck worktree finish "My Session"

# Find and remove orphaned worktrees (manual cleanup)
agent-deck worktree cleanup

The finish command is atomic project hygiene. It merges your worktree's branch, removes the working directory, and cleans up the Agent Deck session — no dangling branches, no forgotten directories, no zombie tmux panes.

Example 5: Custom Cost Line Template

# ~/.agent-deck/config.toml — global default
[costs]
cost_line_template = "{cost_today} today | {cost_this_week} wk"

# Per-profile override for work
[profiles.work.costs]
cost_line_template = "{cost_yesterday} yda | {cost_today} today | {cost_projected}/mo"

Template variables substitute actual dollar amounts: {cost_today}, {cost_yesterday}, {cost_this_week}, {cost_last_week}, {cost_this_month}, {cost_last_month}, {cost_projected}. Unknown placeholders pass through literally (typos surface in output). Set to empty string to disable. This lets you surface exactly the financial metrics you care about, right in the status bar.

Advanced Usage & Best Practices

Keyboard Navigation Mastery (v1.7.60)

Agent Deck has two-tier navigation: global keys move through all sessions; Alt+ keys restrict to current group. Master Alt+j/Alt+k for group-local movement, Alt+1–Alt+9 for intra-group jumping, and Alt+/ for filtered search. Press ? anytime for the live reference.

MCP Pooling Strategy

Enable pool_all = true only after stabilizing your MCP setup. Pooled sockets share processes — if one MCP has a memory leak, it affects all sessions. Monitor with agent-deck costs sync and the TUI dashboard.

Conductor Topology Safety

Never enable the Telegram plugin globally in settings.json — this leaks pollers into every Claude session. Use per-session activation via channels = ["plugin:telegram@claude-plugins-official"] and inject TELEGRAM_STATE_DIR through the conductor's env_file. Watch for GLOBAL_ANTIPATTERN, DOUBLE_LOAD, and WRAPPER_DEPRECATED warnings.

Socket Isolation Migration

Existing sessions capture their socket name at creation and never migrate automatically. To move old sessions to an isolated socket, either edit SQLite directly (UPDATE instances SET tmux_socket_name = 'agent-deck' WHERE id = '<session-id>') or delete and recreate. A proper migrate-socket subcommand is planned.

Cost Budget Discipline

Set daily_limit and weekly_limit before scaling to many sessions. The 80% warning gives you time to assess; the 100% hard stop prevents surprise bills. Use agent-deck costs recompute after pricing updates to retroactively price events that landed at $0.

Agent Deck vs. Alternatives: Why Make the Switch?

The verdict: If you're running one occasional AI session, tmux is fine. If you're running multiple agents across multiple projects with MCP servers, cost concerns, and orchestration needs, Agent Deck isn't just better — it's the only tool built for this reality.

FAQ: Your Burning Questions Answered

Q: Will Agent Deck mess with my existing tmux sessions? A: No. By default, Agent Deck creates sessions with the agentdeck_* prefix. With socket isolation ([tmux] socket_name = "agent-deck"), it's completely separate. The installer backs up ~/.tmux.conf and you can skip modifications with --skip-tmux-config.

Q: Can I use different Claude accounts for work and personal projects? A: Absolutely. Use per-profile or per-group [claude] config overrides in ~/.agent-deck/config.toml. The precedence chain is: env var > conductor > group > profile > global > default. Verify active config with agent-deck hooks status.

Q: Does it work on Windows natively? A: Windows native isn't supported, but WSL2 works fully including MCP socket pooling. Install WSL2, then run the Linux installer inside it.

Q: How does MCP socket pooling actually work? A: Instead of each session spawning its own MCP processes, Agent Deck starts shared MCP servers that listen on Unix sockets. Sessions connect via these sockets. If an MCP crashes, the reconnecting proxy restores connections in ~3 seconds. Enable with pool_all = true.

Q: What's the difference between a conductor and a regular session? A: Regular sessions are your standard AI agent interactions. Conductors are persistent monitoring sessions that watch other sessions, auto-respond to simple issues, escalate complex ones, and notify you via Telegram/Slack. They're "agents managing agents."

Q: Can I run Agent Deck entirely offline or air-gapped? A: The core TUI and session management work offline. Features requiring network (MCP servers, AI tool APIs, Telegram/Slack bridges, update checks) obviously need connectivity. Cost tracking works offline for already-cached pricing data.

Q: How do I contribute or report issues? A: Press Ctrl+E in the TUI for feedback, or visit the GitHub Discussions. For bugs, file issues at the GitHub repository. See CONTRIBUTING.md for development setup.

Conclusion: Reclaim Your Terminal, Supercharge Your Agents

Agent Deck isn't another terminal multiplexer. It's a fundamental reimagining of how developers interact with AI coding agents in 2025 and beyond. The raw productivity gains from Claude, Gemini, and Codex are undeniable — but they come with coordination costs that raw tmux simply wasn't designed to solve.

With intelligent status detection, effortless session forking, MCP management without config file surgery, Docker sandboxing, real-time cost tracking, and autonomous conductor orchestration, Agent Deck transforms terminal chaos into command-center clarity. The bare-repo worktree support, socket isolation, and aggressive multi-tool compatibility show a project that evolves as fast as the AI tooling landscape itself.

My take? If you're running more than two AI agent sessions weekly, you're already feeling the pain that Agent Deck solves. The 30-second installation is a trivial investment for the hours of tab-hunting and context-losing it prevents. And with the conductor system, we're glimpsing the future: agents that don't just code, but coordinate.

Stop drowning in terminal tabs. Install Agent Deck today — your future self, managing fifteen agents with millisecond switching and perfect visibility, will thank you.

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

Star the repo, join the Discord, and welcome to the era of agent orchestration.