# Agent Deck > Terminal session manager for AI coding agents. One TUI for Claude, Gemini, OpenCode, Codex, and more. - **Type:** MCP server - **Install:** `agentstack add mcp-asheshgoplani-agent-deck` - **Verified:** Pending review - **Seller:** [asheshgoplani](https://agentstack.voostack.com/s/asheshgoplani) - **Installs:** 0 - **Category:** [Communication](https://agentstack.voostack.com/c/communication) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [asheshgoplani](https://github.com/asheshgoplani) - **Source:** https://github.com/asheshgoplani/agent-deck - **Website:** https://discord.gg/e4xSs6NBN8 ## Install ```sh agentstack add mcp-asheshgoplani-agent-deck ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Agent Deck **Your AI agent command center** [](https://github.com/asheshgoplani/agent-deck/stargazers) [](https://github.com/asheshgoplani/agent-deck/releases) [](https://go.dev) [](LICENSE) [](https://github.com/asheshgoplani/agent-deck) [](https://github.com/asheshgoplani/agent-deck/releases) [](https://discord.gg/e4xSs6NBN8) [Install](#installation) . [Quick Start](#quick-start) . [Features](#features) . [Conductor](#conductor) . [Docs](#documentation) . [Discord](https://discord.gg/e4xSs6NBN8) . [FAQ](#faq) **Agent Deck is mission control for your AI coding agents.** Running Claude Code on ten projects, OpenCode on five more, another agent somewhere in the background? One terminal shows every session — running, waiting, or done — and one keystroke switches between them. Groups, search, forking, git worktrees, cost tracking, and a phone-controlled [conductor](#conductor) keep a whole fleet manageable. https://github.com/user-attachments/assets/e4f55917-435c-45ba-92cc-89737d0d1401 ## Installation **Works on:** macOS, Linux, Windows (WSL) ```bash curl -fsSL https://raw.githubusercontent.com/asheshgoplani/agent-deck/main/install.sh | bash ``` Then run: `agent-deck` Other install methods **Homebrew** ```bash brew install asheshgoplani/tap/agent-deck ``` **Go** ```bash go install github.com/asheshgoplani/agent-deck/cmd/agent-deck@latest ``` **From Source** ```bash git clone https://github.com/asheshgoplani/agent-deck.git && cd agent-deck && make install ``` Uninstalling ```bash agent-deck uninstall # Interactive uninstall agent-deck uninstall --keep-data # Remove binary only, keep sessions ``` See [Troubleshooting](skills/agent-deck/references/troubleshooting.md#uninstalling) for full details. ## Quick Start ```bash 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`. ### Key Shortcuts | Key | Action | |-----|--------| | `Enter` | Attach to session | | `n` | New session | | `f` / `F` | Fork (quick / dialog) | | `A` / `Shift+U` | Archive / unarchive session | | `^` | Show archived sessions | | `m` | MCP Manager | | `s` | Skills Manager | | `$` | Cost Dashboard | | `M` | Move session to group | | `S` | Settings | | `/` / `G` | Search / Global search | | `r` / `R` | Rename / Restart session | | `d` | Delete | | `b` | Re-run worktree setup script | | `E` | Container shell (sandboxed sessions) | | `?` | Full help | See [TUI Reference](skills/agent-deck/references/tui-reference.md) for all shortcuts and [CLI Reference](skills/agent-deck/references/cli-reference.md) for all commands. ## Quickstart: orchestrate a fleet of AI agents Five minutes from zero to a Telegram bot that watches every Claude session you have running. ```bash # 1. Create a Telegram bot via @BotFather, grab the token + your user ID from @userinfobot. # 2. Run the wizard — it sets up the conductor, bridge daemon, and heartbeat in one shot. agent-deck conductor setup work --description "Work fleet" agent-deck session start conductor-work # 3. Message your bot: /status ``` That's it. From now on every other agent-deck session you run is supervised by a single "conductor" session that answers routine questions, escalates the interesting ones to your phone, and never lets a `waiting` worker rot. Two short guides to read next: - [**`docs/conductor/`**](docs/conductor/) — two-minute local quickstart, architecture, state files, lifecycle, remote channel setup (Telegram/Slack/Discord), gotchas. - [**`docs/WATCHER-SETUP.md`**](docs/WATCHER-SETUP.md) — add "doorbells" so the outside world (GitHub events, gmail, ntfy pushes, meetings) can wake the conductor up. ## Features ### Fork Sessions Try different approaches without losing context. Fork Claude, OpenCode, Pi, and Codex sessions instantly. Each fork inherits the parent conversation history through the tool's native fork support. - Press `f` for quick fork, `F` to customize name/group - Fork your forks to explore as many branches as you need - Codex forking requires a codex CLI with `codex fork ` support (verified with `codex-cli 0.137.0`) ### MCP Manager Attach MCP servers without touching config files. Need web search? Browser automation? Toggle them on per project or globally. Agent Deck handles the restart automatically. - Press `m` to open, `Space` to toggle, `Tab` to cycle scope (LOCAL/GLOBAL), type to jump - Define your MCPs once in `$XDG_CONFIG_HOME/agent-deck/config.toml` (default `~/.config/agent-deck/config.toml`), then toggle per session — see [Configuration Reference](skills/agent-deck/references/config-reference.md) ### Skills Manager Attach/detach Claude skills per project with a managed pool workflow. - Press `s` to open Skills Manager for a Claude session - Available list is pool-only (`$XDG_CONFIG_HOME/agent-deck/skills/pool`, default `~/.config/agent-deck/skills/pool`) to keep attach/detach deterministic - Apply writes project state to `.agent-deck/skills.toml` and materializes into `.claude/skills` - Type-to-jump is supported in the dialog (same pattern as MCP Manager) ### Declarative groups Declare groups in `config.toml` so they exist on startup. Set `create = true` to ensure a group exists, and `default_path` to set the working directory for new sessions in it: ```toml [groups."staging"] create = true # ensure the group exists [groups."projects/devops"] create = true default_path = "~/repos/devops" # working directory for new sessions ``` On startup each group with `create = true` is created if missing (along with any parent groups). `default_path` is written to the state DB for any group that exists — including groups created from your sessions — so `create = true` is optional when the group is already there. Reconciliation is additive: removing a group from `config.toml` leaves the group and its sessions in place, and omitting `default_path` keeps any value already set. Clear a default with `agent-deck group update --clear-default-path`. ### 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."".claude]` table to `$XDG_CONFIG_HOME/agent-deck/config.toml` (default `~/.config/agent-deck/config.toml`): ```toml [groups."conductor".claude] config_dir = "~/.claude-team" env_file = "~/git/work/.envrc" ``` Lookup priority: `env > group > profile > global > default`. The `env_file` is `source`d 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..claude]` block: ```toml [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 ` — it's the same name that appears in session titles (`conductor-`). **Precedence chain** (most-specific → least-specific): 1. `CLAUDE_CONFIG_DIR` env var 2. `[conductors..claude]` (when the session is a conductor session, i.e. Title starts with `conductor-`) 3. `[groups."".claude]` (PR #578) 4. `[profiles..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..claude]` block continue to resolve via `[groups."conductor".claude]` as they did in v1.5.4 Phase 1–3. Closes [issue #602](https://github.com/asheshgoplani/agent-deck/issues/602). #### Switch a session's account on the fly `agent-deck session switch-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 account ` auto-migrates too. ### MCP Socket Pool Running many sessions? Socket pooling shares MCP processes across all sessions via Unix sockets, reducing MCP memory usage by 85-90%. Connections auto-recover from MCP crashes in ~3 seconds via a reconnecting proxy. Enable with `pool_all = true` in [config.toml](skills/agent-deck/references/config-reference.md). ### Search Press `/` to fuzzy-search across all sessions. Filter by status with `!` (running), `@` (waiting), `#` (idle), `$` (error). Press `G` for global search across all Claude conversations. ### Keyboard navigation (v1.7.60) Two tiers of keybindings move the cursor around the session list. The global tier is unchanged from earlier versions; the `Alt+` tier (added in v1.7.60) restricts movement to the current group only. Press `?` in the TUI to see the full table in-app. | Scope | Keys | What it does | |---|---|---| | **Global (flat list)** | `j` / `k` or `↓` / `↑` | Move cursor down / up through every item | | Global | `gg` | Jump to top of list | | Global | `G` | Open global search across all Claude conversations | | Global | `1`–`9` | Jump to Nth root group header | | Global | `/` | Open fuzzy search across all sessions | | **Group (current group only)** | `Alt+j` / `Alt+k` | Next / previous session in current group (skips group boundaries) | | Group | `Alt+1`–`Alt+9` | Jump to Nth session within the current group | | Group | `Alt+g` / `Alt+G` | First / last session in current group | | Group | `Alt+/` | Open fuzzy search filtered to the current group's sessions | "Current group" is derived from the cursor position: on a session it's that session's group; on a group header it's that group; on a window it's the parent session's group. On a group boundary `Alt+j` / `Alt+k` no-op rather than spilling into the next group. ### Status Detection Smart polling detects what every agent is doing right now: | Status | Symbol | What It Means | |--------|--------|---------------| | **Running** | `●` green | Agent is actively working | | **Waiting** | `◐` yellow | Needs your input | | **Idle** | `○` gray | Ready for commands | | **Error** | `✕` red | Something went wrong | ### Notification Bar Waiting sessions appear right in your tmux status bar. Press `Ctrl+b`, release, then press `1`–`6` to jump directly to them. ``` ⚡ [1] frontend [2] api [3] backend ``` ### Git Worktrees Multiple agents can work on the same repo without conflicts. Each worktree is an isolated working directory with its own branch. - `agent-deck add . -c claude --worktree feature/a --new-branch` creates a session in a new worktree - `agent-deck add . --worktree feature/b -b --location subdirectory` places the worktree under `.worktrees/` inside the repo - `agent-deck worktree finish "My Session"` merges the branch, removes the worktree, and deletes the session - `agent-deck worktree cleanup` finds and removes orphaned worktrees Configure the default worktree location in `$XDG_CONFIG_HOME/agent-deck/config.toml` (default `~/.config/agent-deck/config.toml`): ```toml [worktree] default_location = "subdirectory" # "sibling" (default), "subdirectory", or a custom path ``` `sibling` creates worktrees next to the repo (`repo-branch`). `subdirectory` creates them inside it (`repo/.worktrees/branch`). A custom path like `~/worktrees` or `/tmp/worktrees` creates repo-namespaced worktrees at `//`. The `--location` flag overrides the config per session. #### Copying Gitignored Files (`.worktreeinclude`) Gitignored files (`.env`, `.mcp.json`, etc.) aren't copied into new worktrees by default. To declare which gitignored files should be copied automatically, create a `.worktreeinclude` file in your repo root: ```gitignore # .worktreeinclude — gitignore-syntax patterns .env .env.local .mcp.json secrets/ ``` Only files that are both pattern-matched AND gitignored get copied — tracked files are never duplicated. Directories are copied recursively and merged into existing destinations. Existing files in the worktree are not overwritten. This works for both single-repo and multi-repo worktree sessions. Matches [Claude Code Desktop semantics](https://code.claude.com/docs/en/worktrees#copy-gitignored-files-into-worktrees). #### Worktree Setup Script For imperative setup tasks (installing dependencies, running migrations, etc.), create a script at `.agent-deck/worktree-setup.sh`. Agent-deck runs it automatically after creating a worktree and processing `.worktreeinclude`. ```sh #!/bin/sh npm install ``` The script receives two environment variables: - `AGENT_DECK_REPO_ROOT` — path to the main repository - `AGENT_DECK_WORKTREE_PATH` — path to the new worktree The script runs via `sh -e` with a 60-second timeout. If it fails, the worktree is still created — you'll see a warning but the session proceeds normally. #### Worktree Destruction Script For imperative teardown tasks (stopping containers, removing volumes, releasing ports, etc.), create a script at `.agent-deck/worktree-destruction.sh`. Agent-deck runs it automatically *just before* removing a worktree, while the worktree still exists. ```sh #!/bin/sh docker compose -p "$(basename "$AGENT_DECK_WORKTREE_PATH")" down ``` It receives the same environment variables as the setup script (`AGENT_DECK_REPO_ROOT`, `AGENT_DECK_WORKTREE_PATH`) and runs with the same `sh -e` dispatch and 60-second timeout. If it fails, removal proceeds anyway — you'll see a warning. It does not run for sessions that reuse the main working tree (nothing is removed there). #### Bare repositories and worktrees Agent-deck supports two flavors of the [bare-repo layout](https://git-scm.com/docs/git-worktree) where every worktree is a peer (no "main" checkout). The two are distinguished by convention — the basename of the bare git dir. ##### Nested `.bare/` layout The bare git metadata sits inside a normal-looking project dir at `.bare/`: ``` project/ ├── .bare/ # bare git repo (holds refs, objects, HEAD) ├── .agent-deck/ │ └── worktree-setup.sh # shared setup script (optional) ├── worktree-a/ # linked worktree on branch-a │ └── .git # file: gitdir: ../.bare/worktrees/worktree-a └── worktree-b/ # linked worktree on branch-b └── .git ``` ##### True-bare-at-root layout The result of a plain `git clone --bare repo.git`: the directory itself *is* the bare repo and linked worktrees live as direct children a … ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [asheshgoplani](https://github.com/asheshgoplani) - **Source:** [asheshgoplani/agent-deck](https://github.com/asheshgoplani/agent-deck) - **License:** MIT - **Homepage:** https://discord.gg/e4xSs6NBN8 Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** yes - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** yes - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: flagged — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-asheshgoplani-agent-deck - Seller: https://agentstack.voostack.com/s/asheshgoplani - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.