agent-deck

┌──┬──┬──┐
│● │◐ │○ │
└──┴──┴──┘

┌─────────────────────────────────────────────────────────────────────────┐
│  [●│◐│○] Agent Deck                          8 sessions   [/] Search    │
├────────────────────────┬────────────────────────────────────────────────┤
│  SESSIONS              │  Preview: devops/claude-1                      │
│  ▼ projects (4)     ●  │  $ claude                                      │
│    ▶ devops/claude  ●  │  I'll help you with the deployment...          │
│      devops/shell   ○  │                                                │
│      frontend       ◌  │  ┌─────────────────────────────────────────┐   │
│  ▼ personal (2)        │  │ Proceed with changes? (Y/n)             │   │
│      blog           ◌  │  └─────────────────────────────────────────┘   │
├────────────────────────┴────────────────────────────────────────────────┤
│ [↑↓] Navigate [Enter] Attach [/] Search [n] New [Tab] Fold [d] Del [q]  │
└─────────────────────────────────────────────────────────────────────────┘

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

Intelligent Status Detection

Agent Deck automatically detects what your AI agent is doing:

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

Supported Tools

Installation

Prerequisites

• macOS, Linux, or Windows (via WSL)
• tmux — Terminal multiplexer

  # macOS
  brew install tmux
  
  # Ubuntu/Debian/WSL
  sudo apt install tmux
  
  # Fedora
  sudo dnf install tmux
  

Quick Install (Recommended)

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

This downloads the latest release and installs to ~/.local/bin.

Options:

# Custom binary name
curl -fsSL https://raw.githubusercontent.com/asheshgoplani/agent-deck/main/install.sh | bash -s -- --name ad

# Custom install directory
curl -fsSL https://raw.githubusercontent.com/asheshgoplani/agent-deck/main/install.sh | bash -s -- --dir /usr/local/bin

# Specific version
curl -fsSL https://raw.githubusercontent.com/asheshgoplani/agent-deck/main/install.sh | bash -s -- --version v0.2.0

Homebrew (macOS/Linux)

brew install asheshgoplani/tap/agent-deck

Go Install

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

Requires Go 1.24+ and $GOPATH/bin in your PATH.

From Source

git clone https://github.com/asheshgoplani/agent-deck.git
cd agent-deck
make install          # Install to /usr/local/bin (requires sudo)
# or
make install-user     # Install to ~/.local/bin (no sudo)

Verify Installation

agent-deck version

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

Session Management

Search & Import

While Attached

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
└── hooks/            # Hook scripts (optional)

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

License

MIT License - see LICENSE for details.

Acknowledgments

Built with:

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