Agent Deck

Installation

Works on: macOS, Linux, Windows (WSL)

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

Then run: agent-deck

<details> <summary>Other install methods</summary>

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

</details>

<details> <summary>Uninstalling</summary>

agent-deck uninstall              # Interactive uninstall
agent-deck uninstall --keep-data  # Remove binary only, keep sessions

See Troubleshooting for full details.

</details>

All three resolve to project/, create project/.worktrees/feature-c/, run project/.agent-deck/worktree-setup.sh.

Both resolve to project.git/, create project.git/feature-c/, run project.git/.agent-deck/worktree-setup.sh.

```

agent-deck worktree list and agent-deck worktree finish work from any of those locations.

Common gotchas:

• .agent-deck/ must live at the project root. For nested layouts that's next to .bare/; for at-root layouts that's inside the bare dir. If you commit .agent-deck/ into a specific branch's worktree instead, agent-deck will not find it — the lookup resolves to the project root, not the current worktree.
• Detection is by convention: basename .bare ⇒ nested layout, anything else ⇒ at-root. A bare repo named something other than .bare inside a project dir (e.g. project/.git-bare/) is treated as at-root if you point at it directly. For a fully nested layout, use the canonical name .bare.
• If you keep a .git file at the project root pointing to .bare/ (a variant some tutorials recommend), point agent-deck add at .bare/ or at a linked worktree rather than at the project root — the .git file shadows the bare-repo detection path.

Docker Sandbox

Run sessions inside isolated Docker containers. The project directory is bind-mounted read-write, so agents work on your code while the rest of the system stays protected.

• Check "Run in Docker sandbox" when creating a session, or set default_enabled = true in config
• Press T on a sandboxed session to open a container shell
• agent-deck try "task description" runs a one-shot sandboxed session

Host tool auth (Claude, Gemini, Codex, etc.) is automatically shared into containers via shared sandbox directories — no re-authentication needed. On macOS, Keychain credentials are extracted too.

[docker]
default_enabled = true
mount_ssh = true
auto_cleanup = true    # Remove containers when sessions end (default: true)

Set auto_cleanup = false to keep containers alive after session termination, which is useful for debugging container state or inspecting logs.

See the Docker Sandbox Guide for the full reference including overlay details, custom images, and troubleshooting.

First-time setup (asks about Telegram/Slack, then creates the conductor)

agent-deck -p work conductor setup ops --description "Ops monitor"

agent-deck is installed automatically if missing on the remote

agent-deck remote add prod user@prod-server --agent-deck-path /usr/local/bin/agent-deck

Quick Start

agent-deck                        # Launch TUI
agent-deck add . -c claude        # Add current dir with Claude
agent-deck session fork my-proj   # Fork a supported session
agent-deck session remove my-proj # Remove stopped/errored session from registry (transcripts preserved)
agent-deck mcp attach my-proj exa # Attach MCP to session
agent-deck skill attach my-proj docs --source pool --restart # Attach skill + restart
agent-deck web                    # Start web UI on http://127.0.0.1:8420

⚠️ Changed in v1.9.55: in the new-session dialog (n), Enter advances to the next field on the Name and Branch inputs instead of submitting — typing a name and hitting Enter no longer creates a session with all defaults. Ctrl+S creates the session from any field. The dialog also remembers your last-used tool. Restore the old behavior with [ui].new_session_enter_advances = false.

Quickstart: orchestrate a fleet of AI agents

Five minutes from zero to a Telegram bot that watches every Claude session you have running.

```bash

Create, start, test — mirrors the four examples from `agent-deck watcher --help`

agent-deck watcher create webhook --name my-webhook --port 9000 agent-deck watcher create github --name gh-alerts --secret $GITHUB_WEBHOOK_SECRET agent-deck watcher create ntfy --name phone --topic my-private-topic agent-deck watcher create slack --name team-slack --topic my-slack-topic

agent-deck watcher start <name> agent-deck watcher list # health + events/hour per watcher agent-deck watcher status <name> # detail view including recent events agent-deck watcher test <name> # fire a synthetic event to verify routing

Routing rules live in the effective watcher data dir (`${XDG_DATA_HOME:-$HOME/.local/share}/agent-deck/watcher/clients.json` for new users, or legacy `~/.agent-deck/watcher/clients.json` when existing watcher state is present). Edit it to pick which conductor/group receives which events. Use `agent-deck watcher routes` to see the currently-loaded rules across all watchers.

**Conversational setup (recommended for first-time use):**

Then, inside a Claude Code session started by agent-deck, ask: "Use the watcher-creator skill to set up a GitHub watcher". The skill walks through adapter selection, required settings, and emits the exact agent-deck watcher create command to run.

Safety notes: - The GitHub adapter enforces HMAC-SHA256 signature verification on every webhook — a missing/invalid signature drops the event. - Events are deduplicated in SQLite by (watcher_name, event_id), so retries from the sender do not double-fire the conductor. - Watchers keep per-adapter health in <effective watcher data dir>/<name>/state.json; the TUI watcher panel (press w) surfaces this in real time.

Doorbell rule: watchers are triggers, not launchers. They forward a short event string to the conductor and let the conductor decide what to do. A watcher should never call agent-deck launch or agent-deck add directly — those calls run outside any conductor's process and have no $AGENTDECK_INSTANCE_ID, so the spawned session becomes an orphan whose status events never route back. Use agent-deck session send <conductor> "[event] hint" from the watcher and let the conductor fan out from there.

See also

• documentation/WATCHERS.md — full watcher guide with adapter recipes, custom external watchers, security guarantees, and gotchas

Per-group Claude config

Agent Deck supports per-group CLAUDE_CONFIG_DIR and env_file overrides. Useful when a single profile hosts groups that should authenticate against different Claude accounts — for example, a personal profile hosting a conductor group pinned to ~/.claude-team while other groups stay on ~/.claude.

Override any group by adding a [groups."<name>".claude] table to $XDG_CONFIG_HOME/agent-deck/config.toml (default ~/.config/agent-deck/config.toml):

[groups."conductor".claude]
config_dir = "~/.claude-team"
env_file = "~/git/work/.envrc"

Lookup priority: env > group > profile > global > default. The env_file is sourced into the tmux pane before claude (or the custom command) execs, so any exports it contains become part of the session environment.

Human-watchable verification: bash scripts/verify-per-group-claude-config.sh. The harness creates two throwaway groups, launches one normal and one custom-command session, and prints a pass/fail table.

Per-conductor Claude config (v1.5.4)

Conductors are first-class agent-deck entities (see agent-deck conductor setup). Each conductor can carry its own Claude config_dir and env_file via a top-level [conductors.<name>.claude] block:

[conductors.gsd-v154.claude]
config_dir = "~/.claude-team"
env_file = "~/git/work/.envrc"

The conductor name is the string you passed to agent-deck conductor setup <name> — it's the same name that appears in session titles (conductor-<name>).

Precedence chain (most-specific → least-specific):

1. CLAUDE_CONFIG_DIR env var
2. [conductors.<name>.claude] (when the session is a conductor session, i.e. Title starts with conductor-)
3. [groups."<group>".claude] (PR #578)
4. [profiles.<profile>.claude]
5. [claude] (global)
6. ~/.claude (default)

This means a single [conductors.gsd-v154.claude] line replaces the need to duplicate the config into [groups."conductor".claude] — the conductor block scopes to exactly that conductor, not to every conductor that shares the conductor group.

Backward compat: sessions in the conductor group with NO matching [conductors.<name>.claude] block continue to resolve via [groups."conductor".claude] as they did in v1.5.4 Phase 1–3.

Closes issue #602.

Switch a session's account on the fly

agent-deck session switch-account <session> <account> moves an existing session to another Claude account — conversation included. The session stops, its conversation file is migrated into the target account's config dir (copy-only, with a destination backup and size verification), the account is set, and the session restarts with --resume. session set <session> account <name> auto-migrates too.

Use a custom agent endpoint via environment variables

agent-deck conductor setup glm-bot \ -env ANTHROPIC_BASE_URL=https://api.z.ai/api/anthropic \ -env ANTHROPIC_AUTH_TOKEN=<token> \ -env ANTHROPIC_DEFAULT_OPUS_MODEL=glm-5

Or use an env file

agent-deck conductor setup glm-bot -env-file ~/.conductor.env

Each conductor gets its own directory, identity, and settings under the XDG data
root (default `~/.local/share/agent-deck/conductor/`):

Claude conductors use `CLAUDE.md`. Codex conductors use `AGENTS.md`. Shared `POLICY.md` and `LEARNINGS.md` remain agent-neutral.

**CLI commands:**

**Telegram bridge** (optional): Connect a Telegram bot for mobile monitoring. The bridge routes messages to specific conductors using a `name: message` prefix:

**Slack bridge** (optional): Connect a Slack bot for channel-based monitoring via Socket Mode. The bot listens in a dedicated channel and replies in threads to keep the channel clean. Uses the same `name: message` routing, plus slash commands:

<details>
<summary><b>Slack setup</b></summary>

1. Create a Slack app at [api.slack.com/apps](https://api.slack.com/apps)
2. Enable **Socket Mode** → generate an app-level token (`xapp-...`)
3. Under **OAuth & Permissions**, add bot scopes: `chat:write`, `channels:history`, `channels:read`, `app_mentions:read`
4. Under **Event Subscriptions**, subscribe to bot events: `message.channels`, `app_mention`
5. If using slash commands, create: `/ad-status`, `/ad-sessions`, `/ad-restart`, `/ad-help`
6. Install the app to your workspace
7. Invite the bot to your channel (`/invite @botname`)
8. Run `agent-deck conductor setup <name>` and enter your bot token (`xoxb-...`), app token (`xapp-...`), and channel ID (`C01234...`)

</details>

Both Telegram and Slack can run simultaneously — the bridge daemon handles both concurrently and relays responses on-demand, plus periodic heartbeat alerts to configured platforms.

**Built-in status-driven notifications**: conductor setup also installs a transition notifier daemon (`agent-deck notify-daemon`) that watches status transitions and sends parent nudges when child sessions move `running -> waiting|error|idle`.

Dispatch can be suppressed at two scopes (PR #580, v1.7.34):

Global kill switch in $XDG_CONFIG_HOME/agent-deck/config.toml

(default ~/.config/agent-deck/config.toml)

[notifications] transition_events = false

Optional config ($XDG_CONFIG_HOME/agent-deck/config.toml;

default ~/.config/agent-deck/config.toml)

[costs] retention_days = 90

[costs.budgets] daily_limit = 50.00 weekly_limit = 200.00

[costs.pricing.overrides] "custom-model" = { input_per_mtok = 1.0, output_per_mtok = 5.0 }

#### Customizing the status-line cost segment

The home status bar shows a brief cost line drawn from the seven windows below. The default renders `$X.XX today`; configure `cost_line_template` to surface different windows or a per-profile layout. Variables substitute as `$X.XX`; unknown placeholders pass through literally so typos surface in the output.

| Variable | Window |
|---|---|
| `{cost_today}` | Today (00:00 local) |
| `{cost_yesterday}` | Prior day |
| `{cost_this_week}` | Monday-start of this week |
| `{cost_last_week}` | Prior Monday to Sunday |
| `{cost_this_month}` | First of this month |
| `{cost_last_month}` | Prior calendar month |
| `{cost_projected}` | Rolling 7-day average times 30 |

[profiles.work.costs] cost_line_template = "{cost_yesterday} yda | {cost_today} today | {cost_projected}/mo" ```

Resolution chain: profiles.<active>.costs.cost_line_template > [costs].cost_line_template > hardcoded "{cost_today} today". Setting the template to an empty string explicitly disables the segment.

$XDG_CONFIG_HOME/agent-deck/config.toml

default ~/.config/agent-deck/config.toml

[tmux] socket_name = "agent-deck"

With this set, every agent-deck session is spawned as `tmux -L agent-deck …` — a fully isolated tmux server whose socket lives at `$TMUX_TMPDIR/tmux-<uid>/agent-deck` (or `/tmp/tmux-<uid>/agent-deck` when `TMUX_TMPDIR` is unset, the standard tmux fallback). Your regular tmux server at `default` is never touched.

**What this buys you:**
- `[tmux].inject_status_line`, bind-key, and global `set-option` mutations stay on the agent-deck server. Your personal status bar, plugins, and theme are untouched.
- A stray `tmux kill-server` in your shell cannot take agent-deck's managed sessions down with it.
- `tmux -L agent-deck ls` from the shell shows exactly agent-deck's sessions — no mixing with your own work sessions.
- Fixes [#276](https://github.com/asheshgoplani/agent-deck/issues/276) and [#687](https://github.com/asheshgoplani/agent-deck/issues/687) at the root, not via per-option sentinels.

**Default behavior unchanged.** Leave `socket_name` unset (the default) and agent-deck behaves exactly like v1.7.46: it uses your default tmux server. This is a pure opt-in.

**What socket isolation does not cover.** `socket_name` isolates agent-deck from *other* tmux servers on the host — a `tmux kill-server` in your shell, a stray `set-option -g` from your personal config, or an interactive session competing for the same socket. It does **not** harden agent-deck's own tmux server against bugs inside tmux itself. If agent-deck's internal session churn trips a tmux bug (for example, a control-mode race in older tmux builds), that failure happens on the isolated socket just as it would on the default one. The isolation boundary is "other tmux instances," not "all possible tmux crashes." Keep your tmux up to date alongside agent-deck.

**Per-session override.** The `agent-deck add` and `agent-deck launch` commands both accept `--tmux-socket <name>` to override the installation-wide default for one session:

One-off isolated session even though config says otherwise

agent-deck add --tmux-socket experiment -c claude . agent-deck launch --tmux-socket experiment -c claude -m "Try the risky thing"

Precedence at session creation: `--tmux-socket` flag > `[tmux].socket_name` > empty.

**Immutable after creation.** Each session captures its socket name in SQLite at creation time. Changing `socket_name` in config later does **not** migrate existing sessions — they stay on the socket they were created on, so restart/revive cycles keep reaching the right tmux server. This is deliberate: mixing sockets mid-life would strand sessions on an unreachable server.

**Migrating existing sessions.** There's no `migrate-socket` subcommand in this release. To move an existing session onto an isolated socket:

1. Set `[tmux].socket_name = "agent-deck"` in your config.
2. Stop the session (`agent-deck session stop <name>`) — this kills the tmux pane on the old server.
3. Restart it (`agent-deck session start <name>`) — agent-deck will see TmuxSocketName=`""` on the stored Instance, spawn a fresh pane on the old server, and keep it there. To force it onto the new socket, edit the effective profile database (`~/.local/share/agent-deck/<profile>/state.db` for new users, or `~/.agent-deck/<profile>/state.db` for legacy profiles):
   

A proper session migrate-socket subcommand is tracked for phase 2.

TMUX_TMPDIR is honored. Socket path resolution follows tmux's standard rules: if you set TMUX_TMPDIR=/custom/dir, agent-deck's socket lives at /custom/dir/tmux-<uid>/agent-deck. No extra config needed.

List configured remotes

agent-deck remote list

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 done

OpenCode will auto-discover the skill from `~/.claude/skills/`.

**Option 3: Any LLM** (ChatGPT, Claude, Gemini, etc.)

FAQ

<details> <summary><b>How is this different from just using tmux?</b></summary>

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.

</details>

<details> <summary><b>Can I use it on Windows?</b></summary>

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.

</details>

<details> <summary><b>Can I use different Claude accounts/configs per profile?</b></summary>

Yes. Set a global Claude config dir, then add optional per-profile overrides in $XDG_CONFIG_HOME/agent-deck/config.toml (default ~/.config/agent-deck/config.toml):

[claude]
config_dir = "~/.claude"             # Global default

[profiles.work.claude]
config_dir = "~/.claude-team"        # Work account

Run with the target profile:

agent-deck -p work

You can verify which Claude config path is active with:

agent-deck hooks status
agent-deck hooks status -p work

See Configuration Reference for full details. To move an existing session to another account — conversation included — use agent-deck session switch-account <session> <account>.

</details>

<details> <summary><b>Will it interfere with my existing tmux setup?</b></summary>

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.

</details>