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>

<details> <summary>Shell completion</summary>

agent-deck completion <bash|zsh|fish> prints a completion script for commands and subcommands (agent-deck se<Tab> → session, agent-deck session st<Tab> → start/stop), plus live resource names where it matters — agent-deck remote update <Tab> offers your configured remotes, agent-deck session set-parent <Tab> <Tab> offers session titles at both positions, and agent-deck -p <Tab> offers your profiles.

```bash

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. The exception is the Claude Code login on macOS, which lives in the Keychain: copying it would fork the host's OAuth refresh chain and log the host out, so the sandbox keeps a login of its own. Run /login once in your first sandbox session (or pass a claude setup-token credential as CLAUDE_CODE_OAUTH_TOKEN via environment); see the single-owner rule in the sandbox reference.

[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"

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 send my-proj --message-file task.md # Send a multiline prompt
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, extended after v1.16.5: in the new-session dialog (n), Enter advances to the next field on every row — Name, Tool, Model, Reasoning effort, Path, checkboxes and each Claude Options row — and only the trailing [ Create session ] button (or Ctrl+S from any field) creates the session, so walking the form with Enter never launches a session before you have chosen the model, path or options. ↓/Space open the model list. The dialog also remembers your last-used tool. Restore the old Enter-creates-from-any-row 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

Provider Quota (`agent-deck usage`)

Cost tracking answers "how many dollars"; this answers "how much of my subscription is left". When you run several agents at once, the limit you hit first is usually the provider's 5-hour or weekly plan window, not a dollar budget.

The numbers come from the providers themselves — nothing here is estimated from token counts.

$ agent-deck usage
Claude  updated 2m ago
  5h       23.5%  resets in 2h14m
  7d       41.2%  resets in 3d6h
Z.ai (pro)  updated 1m ago
  5h        0.0%
  7d       22.0%  resets in 4d3h

agent-deck usage --json prints the same report for scripting. --refresh

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.

Context window and the proactive /clear

The session analytics context bar divides the current prompt size by the model's context window. A model id does not carry its window, so a size read off the model-id table is shown as ≈49.5% (window inferred from model id), a reading larger than that table figure is shown as over-limit with the figure named (the window is then unknown, not 100% full), and an id the table has never seen shows window unknown. Set AGENTDECK_CONTEXT_WINDOW=<tokens> in the deck's environment to supply the real size; it renders plain, with no ≈.

A conductor's proactive /clear (clear_on_compact) only arms on an established window — that variable, or a size the harness reported. On an inferred, unknown or disproved window it stays off and the conductor falls back to Claude's own compaction; the reason is logged once per session as conductor_clear_on_compact_disarmed. See issue #2026.

Switch a session's account on the fly

For a new one-shot session, use agent-deck launch . -c claude --account <name>. Run agent-deck accounts (or agent-deck accounts --json) to list named slots configured under [profiles.<name>.claude].config_dir.

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. Claude Code may key one working directory under several project directories (the path as typed, its macOS /private form, its realpath); every copy of the conversation under those keys in both accounts is considered, the newest by last event wins (tie: longest), it is installed under every key in the target, each copy it replaces is backed up next to it, and a newer target copy is never overwritten. The receipt names the chosen copy; --json lists every candidate under transcript.

The TUI exposes the same two moments. The New Session dialog's Claude options carry an Account row (←/→ or Space to cycle, inherit = today's conductor/group/env chain), so a session can be created straight onto the right login. The Edit Session dialog (Shift+P) carries an account row for a session that already exists; saving it asks "Switch Account?" first, then runs the same migrate-and-resume flow as session switch-account, and the session card's [account:"…"] badge follows. Both rows are hidden when no [profiles.<name>.claude].config_dir blocks are configured.

Rows of a remote deck get the same dialog: Shift+P on a remote session lists that remote's own slots, previews the switch there (session switch-preview) and, once confirmed, runs the remote's own session switch; transcripts and credentials never leave the remote. See docs/REMOTE-COMMANDS.md.

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] enabled = true # default; false turns cost tracking off (also [profiles.<name>.costs]) retention_days = 90

[costs.budgets] enforce = true # refuse agent sends and wakes once a limit is spent (default false: display-only) daily_limit = 50.00 weekly_limit = 200.00

[costs.run_budget] # per-run defaults for goals (0 = no cap) max_tokens = 80000 max_turns = 12 max_minutes = 30

[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.