Agent Deck

Terminal session manager for AI agents

Features • Installation • Usage • Documentation • Contributing

---

Why Agent Deck?

Running multiple AI coding agents across projects gets messy fast. Agent Deck gives you a unified dashboard to manage all your sessions—Claude Code, Gemini CLI, Aider, Codex, or any terminal tool.

• 🔌 Universal — Works with any terminal program, not locked to one AI
• ⚡ Fast — Instant session creation, no forced program startup
• 📁 Organized — Project-based hierarchy with collapsible groups
• 🔍 Searchable — Find any session instantly with fuzzy search
• 🎯 Smart Status — Knows when your agent is busy vs. waiting for input
• 🪨 Rock Solid — Built on tmux, battle-tested for 20+ years

Features

🚀 Claude Code Deep Integration

Agent Deck offers first-class Claude Code integration with powerful session forking:

┌─────────────────────────────────────────────────────────────┐
│ Parent Session │ Forked Sessions │
│ ┌─────────────────┐ │ ┌─────────────────┐ │
│ │ "Build auth" │──── Fork ────►│ │ "Try JWT" │ │
│ │ claude session │ │ └─────────────────┘ │
│ │ │──── Fork ────►│ ┌─────────────────┐ │
│ │ │ │ │ "Try OAuth" │ │
│ └─────────────────┘ │ └─────────────────┘ │
└─────────────────────────────────────────────────────────────┘

Fork a conversation to explore multiple approaches in parallel:

• Press f to quick-fork any Claude session
• Press F to fork with custom name/group
• Each fork inherits full conversation context from parent
• Forks get their own session ID—can be forked again!

Use cases:

• 🔀 Branching explorations — Try different implementation approaches from the same context
• 🧪 Experiment safely — Fork before risky changes, keep original intact
• 👥 Parallel work — Multiple Claude instances working from same knowledge base
• 📚 Learning — Fork to ask "what if" questions without derailing main session

Automatic session detection:

• Detects Claude session ID from .jsonl files
• Tracks sessions across restarts
• Handles multiple Claude sessions in same project
• Works with custom Claude profiles (CLAUDE_CONFIG_DIR)

Intelligent Status Detection

Agent Deck automatically detects what your AI agent is doing:

Status	Symbol	Meaning
Running	● green	Agent is actively working
Waiting	◐ yellow	Prompt detected, needs your input
Idle	○ gray	Session ready, nothing happening
Error	✕ red	Session has an error

Works out-of-the-box with Claude Code, Gemini CLI, Aider, and Codex—detecting busy indicators, permission prompts, and input requests.

Supported Tools

Icon	Tool	Status Detection
🤖	Claude Code	Busy indicators, permission dialogs, prompts
✨	Gemini CLI	Activity detection, prompts
🔧	Aider	Y/N prompts, input detection
💻	Codex	Prompts, continuation requests
🐚	Any Shell	Standard shell prompts

Installation

Works on: macOS • Linux • Windows (WSL)

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

That's it! The installer automatically handles tmux if needed.

Then run: agent-deck

Windows:Install WSL first, then run the command above.

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

Launch the TUI

agent-deck

CLI Commands

# Add a session
agent-deck add .# Current directory
agent-deck add ~/projects/myapp # Specific path
agent-deck add . -t "My App" -g work # With title and group
agent-deck add . -c claude # With command (claude, gemini, aider, codex)# List sessions
agent-deck list # Table format
agent-deck list --json # JSON for scripting# Remove a session
agent-deck remove <id|title># By ID or title

Keyboard Shortcuts

Navigation

Key	Action
j / ↓	Move down
k / ↑	Move up
h / ←	Collapse group
l / → / Tab	Expand group
Enter	Attach to session

Session Management

Key	Action
n	New session
g	New group
R	Rename session/group
m	Move session to group
d	Delete
K / J	Reorder up/down

Claude Code Integration

Key	Action
f	Quick fork Claude session (inherits conversation context)
F	Fork with custom name/group

Fork requires an active Claude Code session with a valid session ID.

Search & Import

Key	Action
/	Search sessions
i	Import existing tmux sessions
r	Refresh

While Attached

Key	Action
Ctrl+Q	Detach (session keeps running)

Documentation

Project Organization

Sessions are organized in a hierarchical folder structure:

▼ Projects (5)
├─ frontend ●
├─ backend ◐
└─ ▼ devops (2)
├─ deploy ○
└─ monitor ○
▼ Personal (2)
└─ blog ○

• Groups can be nested to any depth
• Sessions inherit their parent group
• Empty groups persist until deleted
• Order is preserved and customizable

Session Preview

The preview pane shows:

• Live terminal output (last lines)
• Session metadata (path, tool, group)
• Current status

Import Existing Sessions

Press i to discover tmux sessions not created by Agent Deck. It will:

1. Find all tmux sessions
2. Auto-detect the tool from session name
3. Auto-group by project directory
4. Add to Agent Deck for unified management

Configuration

Data is stored in ~/.agent-deck/:

~/.agent-deck/
├── sessions.json # Sessions, groups, state
├── config.toml # User configuration (optional)
└── hooks/ # Hook scripts (optional)

Recommended tmux Configuration

For optimal experience with mouse copy, scroll, and clipboard integration, use this config in ~/.tmux.conf:

macOS

# ============================================# Minimal tmux Configuration for macOS# Mouse copy, scroll, and clipboard - just works# ============================================# ----- Terminal -----set -g default-terminal "tmux-256color"set -ag terminal-overrides ",*256col*:Tc"# ----- Performance -----set -sg escape-time 0
set -g history-limit 50000
# ----- Mouse (enables scroll + drag-to-copy) -----set -g mouse on
# ----- Clipboard -----set -s set-clipboard external
# Mouse drag automatically copies to system clipboard
bind-key -T copy-mode-vi MouseDragEnd1Pane send-keys -X copy-pipe-and-cancel "pbcopy"
bind-key -T copy-mode MouseDragEnd1Pane send-keys -X copy-pipe-and-cancel "pbcopy"# Double-click selects word, triple-click selects line (auto-copies)
bind-key -T copy-mode-vi DoubleClick1Pane select-pane \; send-keys -X select-word \; run-shell -d 0.3 \; send-keys -X copy-pipe-and-cancel "pbcopy"
bind-key -T copy-mode DoubleClick1Pane select-pane \; send-keys -X select-word \; run-shell -d 0.3 \; send-keys -X copy-pipe-and-cancel "pbcopy"
bind-key -T copy-mode-vi TripleClick1Pane select-pane \; send-keys -X select-line \; run-shell -d 0.3 \; send-keys -X copy-pipe-and-cancel "pbcopy"
bind-key -T copy-mode TripleClick1Pane select-pane \; send-keys -X select-line \; run-shell -d 0.3 \; send-keys -X copy-pipe-and-cancel "pbcopy"

Linux (X11 with xclip)

# ============================================# Minimal tmux Configuration for Linux# Mouse copy, scroll, and clipboard - just works# ============================================# ----- Terminal -----set -g default-terminal "tmux-256color"set -ag terminal-overrides ",*256col*:Tc"# ----- Performance -----set -sg escape-time 0
set -g history-limit 50000
# ----- Mouse (enables scroll + drag-to-copy) -----set -g mouse on
# ----- Clipboard -----set -s set-clipboard external
# Mouse drag automatically copies to system clipboard
bind-key -T copy-mode-vi MouseDragEnd1Pane send-keys -X copy-pipe-and-cancel "xclip -in -selection clipboard"
bind-key -T copy-mode MouseDragEnd1Pane send-keys -X copy-pipe-and-cancel "xclip -in -selection clipboard"# Double-click selects word, triple-click selects line (auto-copies)
bind-key -T copy-mode-vi DoubleClick1Pane select-pane \; send-keys -X select-word \; run-shell -d 0.3 \; send-keys -X copy-pipe-and-cancel "xclip -in -selection clipboard"
bind-key -T copy-mode DoubleClick1Pane select-pane \; send-keys -X select-word \; run-shell -d 0.3 \; send-keys -X copy-pipe-and-cancel "xclip -in -selection clipboard"
bind-key -T copy-mode-vi TripleClick1Pane select-pane \; send-keys -X select-line \; run-shell -d 0.3 \; send-keys -X copy-pipe-and-cancel "xclip -in -selection clipboard"
bind-key -T copy-mode TripleClick1Pane select-pane \; send-keys -X select-line \; run-shell -d 0.3 \; send-keys -X copy-pipe-and-cancel "xclip -in -selection clipboard"

For Wayland, replace xclip -in -selection clipboard with wl-copy.

After adding, reload:

tmux source-file ~/.tmux.conf

What this config does:

Feature	How it works
Drag to copy	Click and drag → auto-copies to clipboard
Double-click	Selects word → auto-copies
Triple-click	Selects line → auto-copies
Mouse scroll	Just scroll with mouse wheel
Paste	Cmd+V (macOS) or Ctrl+Shift+V (Linux)

Why these settings:

Setting	Purpose
escape-time 0	No delay on ESC key (fixes sluggishness)
history-limit 50000	AI agents produce lots of output (default is 2000)
set-clipboard external	Secure clipboard (apps inside tmux can't hijack it)
MouseDragEnd1Pane	Auto-copy on mouse release

Tip: Hold Shift while selecting to bypass tmux and use native terminal selection.

Claude Code Profile (Optional)

If you use a custom Claude profile directory (e.g., dual account setup), configure it in ~/.agent-deck/config.toml:

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

This tells Agent Deck where to find Claude session data for:

• Session ID detection
• Fork functionality
• Session tracking across restarts

Hook Integration (Optional)

For instant status updates without polling, configure hooks in your AI tool:

Claude Code (~/.claude/settings.json):

{
"hooks": {
"Stop": [{"hooks": [{"type": "command", "command": "~/.agent-deck/hooks/claude-code.sh"}]}]
}
}

Development

make build # Build binary
make test# Run tests
make dev # Run with auto-reload (requires 'air')
make fmt # Format code
make lint # Lint code (requires 'golangci-lint')
make release # Cross-platform builds
make clean # Clean build artifacts

Project Structure

agent-deck/
├── cmd/agent-deck/ # CLI entry point
├── internal/
│ ├── ui/ # TUI components (Bubble Tea)
│ ├── session/ # Session & group management
│ └── tmux/ # tmux integration, status detection
├── Makefile
├── go.mod
└── README.md

Debug Mode

AGENTDECK_DEBUG=1 agent-deck

Logs status transitions to stderr for troubleshooting.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Comparison

Feature	Agent Deck	Alternatives
Universal (any tool)	✅	Often tool-specific
Claude Code fork	✅ Context inheritance	❌ Not available
Fast session creation	✅ Instant	Slow startup
Project hierarchy	✅ Nested groups	Flat lists
Session search	✅ Fuzzy search	Limited
Import existing	✅ tmux discovery	Manual only
Smart status	✅ Per-tool detection	Basic
Memory footprint	~20MB	Higher

License

MIT License - see LICENSE for details.

Acknowledgments

Built with:

• Bubble Tea — Terminal UI framework
• Lip Gloss — Style definitions
• tmux — Terminal multiplexer

---

⬆ Back to Top