Ask AI about Agent Deck
Option 1: Claude Code Skill (recommended for Claude Code users)
/plugin marketplace add asheshgoplani/agent-deck
/plugin install agent-deck@agent-deck-helpThen ask: "How do I set up MCP pooling?"
Option 2: OpenCode (has built-in Claude skill compatibility)
# Create skill directory
mkdir -p ~/.claude/skills/agent-deck/references
# Download skill and references
curl -sL https://raw.githubusercontent.com/asheshgoplani/agent-deck/main/skills/agent-deck/SKILL.md \
> ~/.claude/skills/agent-deck/SKILL.md
for f in cli-reference config-reference tui-reference troubleshooting; do
curl -sL "https://raw.githubusercontent.com/asheshgoplani/agent-deck/main/skills/agent-deck/references/${f}.md" \
> ~/.claude/skills/agent-deck/references/${f}.md
doneOpenCode will auto-discover the skill from ~/.claude/skills/.
Option 3: Any LLM (ChatGPT, Claude, Gemini, etc.)
Read https://raw.githubusercontent.com/asheshgoplani/agent-deck/main/llms-full.txt
and answer: How do I fork a session?
agent-deck-overview-web.mp4
Running Claude Code on 10 projects? OpenCode 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.
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 status for every agent instantly
- Switch in milliseconds — jump between any session with a single keystroke
- Stay organized — groups, search, notifications, and git worktrees keep everything manageable
Try different approaches without losing context. Fork any Claude conversation instantly. Each fork inherits the full conversation history.
- Press
ffor quick fork,Fto customize name/group - Fork your forks to explore as many branches as you need
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
Mto open,Spaceto toggle,Tabto cycle scope (LOCAL/GLOBAL) - Define your MCPs once in
~/.agent-deck/config.toml, then toggle per session — see Configuration Reference
Running many sessions? Socket pooling shares MCP processes across all sessions via Unix sockets, reducing MCP memory usage by 85-90%. Connections auto-recover from MCP crashes in ~3 seconds via a reconnecting proxy. Enable with pool_all = true in config.toml.
Press / to fuzzy-search across all sessions. Filter by status with ! (running), @ (waiting), # (idle), $ (error). Press G for global search across all Claude conversations.
Smart polling detects what every agent is doing right now:
| 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 |
Waiting sessions appear right in your tmux status bar. Press Ctrl+b 1-6 to jump directly to them.
⚡ [1] frontend [2] api [3] backend
Multiple agents can work on the same repo without conflicts. Each worktree is an isolated working directory with its own branch.
agent-deck add . -c claude --worktree feature/a --new-branchcreates a session in a new worktreeagent-deck add . --worktree feature/b -b --location subdirectoryplaces the worktree under.worktrees/inside the repoagent-deck worktree finish "My Session"merges the branch, removes the worktree, and deletes the sessionagent-deck worktree cleanupfinds and removes orphaned worktrees
Configure the default worktree location in ~/.agent-deck/config.toml:
[worktree]
default_location = "subdirectory" # "sibling" (default), "subdirectory", or a custom pathsibling creates worktrees next to the repo (repo-branch). subdirectory creates them inside it (repo/.worktrees/branch). A custom path like ~/worktrees or /tmp/worktrees creates repo-namespaced worktrees at <path>/<repo_name>/<branch>. The --location flag overrides the config per session.
Conductors are persistent Claude Code sessions that monitor and orchestrate all your other sessions. They watch for sessions that need help, auto-respond when confident, and escalate to you when they can't. Optionally connect Telegram for mobile control.
Create as many conductors as you need per profile:
# First-time setup (asks about Telegram, then creates the conductor)
agent-deck -p work conductor setup ops --description "Ops monitor"
# Add more conductors to the same profile (no prompts)
agent-deck -p work conductor setup infra --no-heartbeat --description "Infra watcher"
agent-deck conductor setup personal --description "Personal project monitor"Each conductor gets its own directory, identity, and heartbeat settings:
~/.agent-deck/conductor/
├── CLAUDE.md # Shared knowledge (CLI ref, protocols, rules)
├── bridge.py # Telegram bridge (if configured)
├── ops/
│ ├── CLAUDE.md # Identity: "You are ops, a conductor for the work profile"
│ ├── meta.json # Config: name, profile, heartbeat, description
│ ├── state.json # Runtime state
│ └── task-log.md # Action log
└── infra/
├── CLAUDE.md
└── meta.json
CLI commands:
agent-deck conductor list # List all conductors
agent-deck conductor list --profile work # Filter by profile
agent-deck conductor status # Health check (all)
agent-deck conductor status ops # Health check (specific)
agent-deck conductor teardown ops # Stop a conductor
agent-deck conductor teardown --all --remove # Remove everythingTelegram bridge (optional): Connect a Telegram bot for mobile monitoring. The bridge routes messages to specific conductors using a name: message prefix:
ops: check the frontend session → routes to conductor-ops
infra: restart all error sessions → routes to conductor-infra
/status → broadcasts to all conductors
Heartbeat: Conductors with heartbeat enabled receive periodic check-in prompts, keeping them actively monitoring your sessions. Disable per conductor with --no-heartbeat.
Agent Deck works with any terminal-based AI tool:
| Tool | Integration Level |
|---|---|
| Claude Code | Full (status, MCP, fork, resume) |
| Gemini CLI | Full (status, MCP, resume) |
| OpenCode | Status detection, organization |
| Codex | Status detection, organization |
| Cursor (terminal) | Status detection, organization |
| Custom tools | Configurable via [tools.*] in config.toml |
Works on: macOS, Linux, Windows (WSL)
curl -fsSL https://raw.githubusercontent.com/asheshgoplani/agent-deck/main/install.sh | bashThen run: agent-deck
Other install methods
Homebrew
brew install asheshgoplani/tap/agent-deckGo
go install github.com/asheshgoplani/agent-deck/cmd/agent-deck@latestFrom Source
git clone https://github.com/asheshgoplani/agent-deck.git && cd agent-deck && make installInstall the agent-deck skill for AI-assisted session management:
/plugin marketplace add asheshgoplani/agent-deck
/plugin install agent-deck@agent-deckUninstalling
agent-deck uninstall # Interactive uninstall
agent-deck uninstall --keep-data # Remove binary only, keep sessionsSee Troubleshooting for full details.
agent-deck # Launch TUI
agent-deck add . -c claude # Add current dir with Claude
agent-deck session fork my-proj # Fork a Claude session
agent-deck mcp attach my-proj exa # Attach MCP to session| Key | Action |
|---|---|
Enter |
Attach to session |
n |
New session |
f / F |
Fork (quick / dialog) |
M |
MCP Manager |
/ / G |
Search / Global search |
r |
Restart session |
d |
Delete |
? |
Full help |
See TUI Reference for all shortcuts and CLI Reference for all commands.
| Guide | What's Inside |
|---|---|
| CLI Reference | Commands, flags, scripting examples |
| Configuration | config.toml, MCP setup, custom tools, socket pool |
| TUI Reference | Keyboard shortcuts, status indicators, navigation |
| Troubleshooting | Common issues, debugging, recovery, uninstalling |
Additional resources:
- CONTRIBUTING.md — how to contribute
- CHANGELOG.md — release history
- llms-full.txt — full context for LLMs
Agent Deck checks for updates automatically. Run agent-deck update to install, or set auto_update = true in config.toml for automatic updates.
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), session forking with context inheritance, MCP management, global search across conversations, and organized groups. Think of it as tmux plus AI awareness.
Can I use it on Windows?
Yes, via WSL (Windows Subsystem for Linux). Install WSL, then run the installer inside WSL. WSL2 is recommended for full feature support including MCP socket pooling.
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 backs up your ~/.tmux.conf before adding optional config, and you can skip it with --skip-tmux-config.
make build # Build
make test # Test
make lint # LintSee CONTRIBUTING.md for details.
If Agent Deck saves you time, give us a star! It helps others discover the project.
MIT License — see LICENSE
Built with Bubble Tea and tmux
Docs . Discord . Issues . Discussions
