agent-deck

Agent Deck

Terminal session manager for AI agents

Features • Installation • Usage • Documentation

Why Agent Deck?

Managing multiple AI coding sessions across projects can get overwhelming. Agent Deck provides a single dashboard to monitor and switch between all your sessions: Claude Code, Gemini CLI, Aider, Codex, or any terminal tool.

What it does:

• Organize sessions by project with collapsible groups
• See at a glance which agents are running, waiting, or idle
• Switch between sessions instantly with keyboard shortcuts
• Search and filter to find what you need
• Built on tmux for reliability

Features

🚀 Session Forking (Claude Code)

Fork Claude conversations to explore multiple approaches in parallel. Each fork inherits full conversation context.

• Press f to quick-fork, F for custom name/group
• Forks inherit context and can be forked again
• Auto-detects Claude session ID across restarts

🔌 MCP Manager

Attach and detach MCP servers on the fly. No config editing required.

• Press M to open, Space to toggle MCPs
• LOCAL scope (project) or GLOBAL (all projects)
• Session auto-restarts with new MCPs loaded

Adding Available MCPs:

Define your MCPs once in ~/.agent-deck/config.toml, then toggle them per project:

# Web search
[mcps.exa]
command = "npx"
args = ["-y", "exa-mcp-server"]
env = { EXA_API_KEY = "your-api-key" }
description = "Web search via Exa AI"

# GitHub integration
[mcps.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_PERSONAL_ACCESS_TOKEN = "ghp_your_token" }
description = "GitHub repos, issues, PRs"

# Browser automation
[mcps.playwright]
command = "npx"
args = ["-y", "@playwright/mcp@latest"]
description = "Browser automation & testing"

# Memory across sessions
[mcps.memory]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-memory"]
description = "Persistent memory via knowledge graph"

# YouTube transcripts
[mcps.youtube-transcript]
command = "npx"
args = ["-y", "@kimtaeyoon83/mcp-server-youtube-transcript"]
description = "Get YouTube transcripts"

# Web scraping
[mcps.firecrawl]
command = "npx"
args = ["-y", "firecrawl-mcp"]
env = { FIRECRAWL_API_KEY = "your-key" }
description = "Web scraping and crawling"

# Notion
[mcps.notion]
command = "npx"
args = ["-y", "@notionhq/notion-mcp-server"]
env = { NOTION_TOKEN = "your-token" }
description = "Notion workspace access"

# Sequential thinking
[mcps.sequential-thinking]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-sequential-thinking"]
description = "Step-by-step reasoning"

# Context7 - code docs
[mcps.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp@latest"]
description = "Up-to-date code documentation"

# Anthropic docs
[mcps.anthropic-docs]
command = "npx"
args = ["-y", "anthropic-docs-mcp", "--transport", "stdio"]
description = "Search Claude & Anthropic docs"

🔍 Search

Press / to search across sessions with fuzzy matching. Filter by status with ! (running), @ (waiting), # (idle), $ (error).

🎯 Smart Status Detection

Automatically detects what your AI agent is doing:

Works with Claude Code, Gemini CLI, Aider, Codex, and any shell.

Installation

Works on: macOS • Linux • Windows (WSL)

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

The installer downloads the binary, installs tmux if needed, and configures tmux for mouse/clipboard support.

Then run: agent-deck

Windows: Install WSL first.

brew install asheshgoplani/tap/agent-deck

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

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

Usage

agent-deck                    # Launch TUI
agent-deck add .              # Add current directory as session
agent-deck add . -c claude    # Add with Claude Code
agent-deck list               # List all sessions

Keyboard Shortcuts

Documentation

Project Organization

▼ Projects (3)
  ├─ frontend     ●
  ├─ backend      ◐
  └─ api          ○
▼ Personal
  └─ blog         ○

Sessions are organized in collapsible groups. Create nested groups, reorder items, and import existing tmux sessions with i.

Configuration

Data stored in ~/.agent-deck/:

~/.agent-deck/
├── sessions.json     # Sessions and groups
└── config.toml       # User config (optional)

For custom Claude profile directory:

[claude]
config_dir = "~/.claude-work"

tmux Configuration

The installer configures tmux automatically. For manual setup, see the tmux configuration guide.

Development

make build    # Build
make test     # Test
make lint     # Lint

Contributing

Contributions welcome! Fork, create a branch, and open a PR.

License

MIT License - see LICENSE