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