deck

A tmux session sidebar that lives inside your terminal

Browse and switch agent sessions easily.

Install · Usage · Customize · Develop

---

deck is a tmux enhancement tool — the sidebar lists your sessions and agents.

✅ deck is	🚫 deck is not
A ratatui sidebar that lists, and lets you act on, your tmux sessions	A tmux replacement, a general system terminal app, or a window manager

💪 deck helps you	✋ deck does not help you
Browse, switch, agent sessions	Install or configure tmux, hook your agents

Install

brew install cross-entropy-ai/tap/deck

Or with curl:

curl -fsSL https://raw.githubusercontent.com/cross-entropy-ai/deck/main/install.sh | sh

Or download a pre-built binary from GitHub Releases.

Usage

deck

Note

Requires tmux installed and available on PATH. On startup with no tmux sessions, deck creates a detached bootstrap session named default. The New Session picker suggests the next free session-N name.

deck runs two panes. The sidebar lists your tmux sessions. The main pane stays attached to the focused session.

Configuration lives in ~/.config/deck/config.yaml. Existing deck or tmux-sidebar JSON configuration is migrated on first load.

Tip

Click a session to switch, drag a session to reorder it, right-click to rename or close it, or drag the edge between panes to resize. Use the header chevron to collapse or expand the sidebar.

The Agents tab can generate a cross-session summary with either Claude Code or Codex; choose the CLI under Settings → Agents → Summary agent.

Deck uses standard Unicode icons by default, so a Nerd Font is not required. Set DECK_ICON_STYLE=ascii for the strictest terminal compatibility, or DECK_ICON_STYLE=nerd to opt into Nerd Font glyphs.

Containers

Any container can be a lane of its own, with its own sessions: mount it from the divider of the machine it runs on — the local section for a container on this machine, a host's section for one over ssh. Deck talks to docker, podman, or Apple's container on macOS, and needs only a tmux (and a POSIX sh) inside.

Remote hosts

Add hosts with deck remote add <host> (resolved through ~/.ssh/config), and they appear as their own sidebar sections. Deck reuses one SSH connection per host and owns those options itself — tune them under Settings → Remote, where you can also turn reuse off; saved port forwards stay configured but inactive while it is off, since they run as ssh -O commands against that shared socket.

Important

Deck forwards your ssh-agent to every configured remote by default, so shells and coding agents in a remote session can use your local keys without copying a private key there. Anyone with root on that host can use every loaded key for as long as the connection is open. Turn it off per host in ~/.config/deck/config.yaml:

remotes:
  - host: shared-box
    forward_agent: false

Container lanes get the same thing without a bind mount, root, recreating the container, or anything installed in the image: deck streams a small static relay in and forwards the agent over the container's own exec channel. forward_agent: false turns that off too. See docs/ssh-agent-forwarding.md.

Develop

cargo run

For implementation details, see the Architecture section of CLAUDE.md.

Build from source

cargo build --release
./target/release/deck

You still need tmux installed locally to run it.

To build a Linux deck from a Mac — what the release publishes — use a container engine, Apple's included:

DECK_ENGINE=container scripts/build-app-in-container.sh                  # this machine's arch
DECK_BUILD_ARCH=amd64 DECK_ENGINE=container scripts/build-app-in-container.sh

Both engines emulate the other architecture, so an Apple Silicon Mac can produce either Linux binary the release publishes.