Agent Deck

Your AI agent command center

Features • Installation • Usage • CLI Commands • Documentation

The Problem

Running Claude Code on 10 projects? Aider 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 - know the status of every agent instantly
⚡ Switch in milliseconds - Jump between any session with a single keystroke
🔍 Never lose track - Search across all conversations, filter by status, find anything in seconds
🌳 Stay organized - Group sessions by project, client, or experiment with collapsible hierarchies
🔌 Zero config switching - Built on tmux - sessions persist through disconnects and reboots

Features

🍴 Explore Multiple Solutions in Parallel

Try different approaches without losing context. Fork any Claude conversation instantly. Each fork inherits the full conversation history - perfect for comparing solutions or experimenting without risk.

Press f for quick fork, F to customize name/group
Fork your forks - explore as many branches as you need
Session IDs auto-detected even after restarts

Why this matters: Ever wished you could try two different approaches to the same problem? Now you can. Fork, experiment, compare results, keep what works.

🔌 Add Superpowers On-Demand

Attach MCP servers without touching config files. Need web search? Browser automation? GitHub integration? Toggle them on per project or globally - Agent Deck handles the restart automatically.

Press M to open, Space to toggle any MCP server
LOCAL scope (just this project) or GLOBAL (everywhere)
Session auto-restarts with new capabilities loaded

Why this matters: Stop editing TOML files. Stop remembering restart commands. Just toggle what you need - Agent Deck takes care of the rest.

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"

More MCP examples

# 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"

🔍 Find Anything in Seconds

Fuzzy search across all sessions. Type a few letters, instantly filter. Need to find that bug fix conversation from last week? The session where you were experimenting with authentication? Just start typing.

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

Why this matters: When you're managing 20+ sessions across different projects, memory fails. Search doesn't.

🎯 Know What's Happening, Instantly

Smart status detection shows you what every agent is doing right now. No more guessing which session is waiting for input, which is thinking, which finished an hour ago.

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

Works with Claude Code, Gemini CLI, Aider, Codex, Cursor, and any terminal tool.

Why this matters: Stop checking every session manually. See the full picture at a glance. Respond when needed. Stay in flow.

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.

Other install methods

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

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

Key	Action
`j/k` or `↑/↓`	Navigate
`Enter`	Attach to session
`n`	New session
`g`	New group
`r`	Rename
`d`	Delete
`f`	Fork Claude session
`M`	MCP Manager
`/`	Search
`Ctrl+Q`	Detach from session
`?`	Help

CLI Commands

Agent Deck provides a full CLI for automation and scripting. All commands support --json for machine-readable output and -p, --profile for profile selection.

Note: Flags must come BEFORE positional arguments (Go flag package standard).

Quick Reference

agent-deck                              # Launch TUI
agent-deck add . -c claude              # Add session with Claude
agent-deck list --json                  # List sessions as JSON
agent-deck status                       # Quick status overview
agent-deck session attach my-project    # Attach to session

Session Commands

Manage individual sessions. Sessions can be identified by:

Title: my-project (exact or partial match)
ID prefix: a1b2c3 (first 6+ chars)
Path: /Users/me/project

# Start/Stop/Restart
agent-deck session start <id>           # Start session's tmux process
agent-deck session stop <id>            # Stop/kill session process
agent-deck session restart <id>         # Restart (Claude: reloads MCPs)

# Fork (Claude only)
agent-deck session fork <id>            # Fork with inherited context
agent-deck session fork <id> -t "exploration"       # Custom title
agent-deck session fork <id> -g "experiments"       # Into specific group

# Attach/Show
agent-deck session attach <id>          # Attach interactively
agent-deck session show <id>            # Show session details
agent-deck session show                 # Auto-detect current session (in tmux)

Fork flags:

Flag	Description
`-t, --title`	Custom title for forked session
`-g, --group`	Target group for forked session

MCP Commands

Manage Model Context Protocol servers for Claude sessions.

# List available MCPs (from config.toml)
agent-deck mcp list
agent-deck mcp list --json

# Show attached MCPs for a session
agent-deck mcp attached <id>
agent-deck mcp attached                 # Auto-detect current session

# Attach/Detach MCPs
agent-deck mcp attach <id> github       # Attach to LOCAL scope
agent-deck mcp attach <id> exa --global # Attach to GLOBAL scope
agent-deck mcp attach <id> memory --restart  # Attach and restart session

agent-deck mcp detach <id> github       # Detach from LOCAL
agent-deck mcp detach <id> exa --global # Detach from GLOBAL

MCP flags:

Flag	Description
`--global`	Apply to global Claude config (all projects)
`--restart`	Restart session after change (loads new MCPs)

Group Commands

Organize sessions into hierarchical groups.

# List groups
agent-deck group list
agent-deck group list --json

# Create groups
agent-deck group create work            # Create root group
agent-deck group create frontend --parent work  # Create subgroup

# Delete groups
agent-deck group delete old-projects    # Delete (fails if has sessions)
agent-deck group delete old-projects --force    # Move sessions to default, then delete

# Move sessions
agent-deck group move my-session work   # Move session to group

Group flags:

Flag	Description
`--parent`	Parent group for creating subgroups
`--force`	Force delete by moving sessions to default group

Status Command

Quick status check without launching the TUI.

agent-deck status                       # Compact: "2 waiting - 5 running - 3 idle"
agent-deck status -v                    # Verbose: detailed list by status
agent-deck status -q                    # Quiet: just waiting count (for prompts)
agent-deck status --json                # JSON output

Global Flags

These flags work with all commands:

Flag	Description
`--json`	Output as JSON (for automation)
`-q, --quiet`	Minimal output, rely on exit codes
`-p, --profile <name>`	Use specific profile

Examples

Scripting with JSON output:

# Get all running sessions
agent-deck list --json | jq '.[] | select(.status == "running")'

# Count waiting sessions
agent-deck status -q  # Returns just the number

# Check if specific session exists
agent-deck session show my-project --json 2>/dev/null && echo "exists"

Automation workflows:

# Start all sessions in a group
agent-deck list --json | jq -r '.[] | select(.group == "work") | .id' | \
  xargs -I{} agent-deck session start {}

# Attach MCP to all Claude sessions
agent-deck list --json | jq -r '.[] | select(.tool == "claude") | .id' | \
  xargs -I{} agent-deck mcp attach {} memory --restart

Current session detection (inside tmux):

# Show current session info
agent-deck session show

# Show MCPs for current session
agent-deck mcp attached

FAQ

How is this different from just using tmux?

Agent Deck adds AI-specific intelligence on top of tmux:

Smart status detection - Knows when Claude is thinking vs. waiting for input (not just "session exists")
Session forking - Duplicate Claude conversations with full context inheritance
MCP manager - Visual interface for attaching/detaching Model Context Protocol servers
Global search - Find conversations across all sessions instantly
Organized groups - Hierarchical project organization instead of flat session lists

Think of it as tmux + AI awareness. The sessions run in tmux (reliability), but Agent Deck adds the layer that understands what AI agents are doing.

Does it work with tools besides Claude Code?

Yes! Agent Deck works with any terminal-based tool:

✅ Claude Code
✅ Aider
✅ Gemini CLI
✅ Cursor (terminal mode)
✅ Codex
✅ Custom shell scripts
✅ Any command-line tool

Some features are Claude-specific (session forking, MCP manager), but status detection, organization, and search work with everything.

Can I use it on Windows?

Yes, via WSL (Windows Subsystem for Linux).

Install WSL (Ubuntu recommended)
Open WSL terminal
Run the installer: curl -fsSL https://raw.githubusercontent.com/asheshgoplani/agent-deck/main/install.sh | bash

Agent Deck runs inside WSL and works exactly like it does on macOS/Linux.

Will it interfere with my existing tmux setup?

No. Agent Deck creates its own tmux sessions with the prefix agentdeck_*. Your existing sessions are untouched.

The installer adds optional tmux config (mouse support, clipboard integration) but:

It backs up your existing ~/.tmux.conf first
You can skip it with --skip-tmux-config flag
It only adds to your config, never removes

How do I add more MCP servers?

Edit ~/.agent-deck/config.toml and add your servers:

[mcps.your-server]
command = "npx"
args = ["-y", "your-mcp-package"]
env = { API_KEY = "your-key" }
description = "What this server does"

Then press M in Agent Deck to toggle it on/off for any session. See MCP examples.

What if a session crashes?

tmux sessions persist even if Agent Deck closes. If a session crashes:

Check logs: ~/.agent-deck/logs/agentdeck_<session-name>_<id>.log
Restart it: agent-deck session restart <session-id>
Or delete and recreate: agent-deck remove <id> then agent-deck add <path>

Sessions are stored in ~/.agent-deck/profiles/default/sessions.json with automatic backups (.bak, .bak.1, .bak.2).

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! Found a bug? Have a feature idea? Want to improve the docs?

Fork the repo
Create a branch (git checkout -b feature/amazing-feature)
Make your changes
Open a PR

See CONTRIBUTING.md for details.

Star History

If Agent Deck saves you time, give us a star! ⭐ It helps others discover the project.

License

MIT License - see LICENSE

Built with Bubble Tea and tmux

Documentation • Issues • Discussions

Name		Name	Last commit message	Last commit date
Latest commit History 127 Commits
.github/workflows		.github/workflows
.playwright-mcp		.playwright-mcp
cmd/agent-deck		cmd/agent-deck
demos		demos
internal		internal
site		site
.gitignore		.gitignore
.goreleaser.yaml		.goreleaser.yaml
.goreleaser.yml		.goreleaser.yml
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
TRACTION_STRATEGY.md		TRACTION_STRATEGY.md
TWITTER_POST_TEMPLATES.md		TWITTER_POST_TEMPLATES.md
go.mod		go.mod
go.sum		go.sum
install.sh		install.sh

License

asheshgoplani/agent-deck

Folders and files

Latest commit

History

Repository files navigation

Agent Deck

The Problem

The Solution

Features

🍴 Explore Multiple Solutions in Parallel

🔌 Add Superpowers On-Demand

🔍 Find Anything in Seconds

🎯 Know What's Happening, Instantly

Installation

Usage

Keyboard Shortcuts

CLI Commands

Quick Reference

Session Commands

MCP Commands

Group Commands

Status Command

Global Flags

Examples

FAQ

How is this different from just using tmux?

Does it work with tools besides Claude Code?

Can I use it on Windows?

Will it interfere with my existing tmux setup?

How do I add more MCP servers?

What if a session crashes?

Documentation

Project Organization

Configuration

tmux Configuration

Development

Contributing

Star History

License

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 13

Packages 0

Languages

Packages