agent-deck

MCP办公协作

提供方 asheshgoplani · 包名 agent-deck

办公协作 stdio · 本地进程 会话登录 社区 / 第三方 Claude DesktopCursorClineClaude Code
查看接入方式

Terminal session manager for AI coding agents. One TUI for Claude, Gemini, OpenCode, Codex, and more.

一句话选型结论

按资料字段整理

agent-deck 属于办公协作类 MCP 服务器,stdio · 本地进程,会话登录,可直接接入 Claude Desktop、Cursor、Cline 等,有可直接执行的安装命令。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类办公协作 传输方式stdio · 本地进程 鉴权会话登录 部署方式本地部署
GitHub 星标 2,006 仓库热度,无公开仓库时显示未标注
工具数 未标注 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

办公协作
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量未标注暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

agent-deck ai-agent ai-agents ai-coding-assistant aider

支持客户端

适用场景

agent-deckai-agentai-agents

安装与配置

stdio · 本地进程 会话登录
客户端在本机拉起子进程,数据不出本机
go install asheshgoplani/agent-deck@latest

这条命令只是入口,具体启动参数请按官方文档补齐,不要直接照搬到别的服务器。

  1. 1
    准备运行环境

    stdio 服务在本地起进程,需要先装好 Cross-platform,再按安装命令拉取依赖。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后随便调一个只读工具,确认能返回结果,再接入正式流程。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
日程与消息

查日程、发消息、约会议。

表单与审批

填表单、走审批流。

团队协作

同步任务、汇总进展。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 有现成的安装命令,不用自己找入口,照着跑就能起服务。
  • 已适配 Claude Desktop、Cursor、Cline,换客户端不用重新研究配置。
  • 仓库有一定关注度(星标 2,006),遇到问题更容易搜到资料。

先想清楚的地方

  • stdio 方式要求本地装好运行时(如 Node.js),换机器要重新装一遍。
  • 使用前要准备好会话登录对应的凭据,并按最小权限配置。
  • 资料没标注工具数量,实际能力要装好后确认。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在办公协作场景里让模型直接调用外部能力的人。
  • 已经在用 Claude Desktop、Cursor 的用户,接入路径最短。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 完全不想在本地装环境的人。
  • 不方便管理密钥或第三方授权的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
agent-deck当前 未标注 stdio · 本地进程 本地部署 有 2026-04-11
CowAgent 未标注 stdio · 本地进程 本地部署 有 2026-04-11
Karakeep MCP 未标注 未标注 未标注 无 2026-05-17
agentscope 未标注 stdio · 本地进程 本地部署 有 2026-04-11
note-gen 未标注 stdio · 本地进程 本地部署 有 2026-04-11
Everywhere 未标注 stdio · 本地进程 本地部署 有 2026-04-12

服务器档案

办公协作
字段来自项目仓库与公开索引,中文说明由本站标注
提供方asheshgoplani上游标注的维护方 asheshgoplani
分类办公协作本站按上游分类展示
连接方式stdio · 本地进程客户端在本机拉起子进程,数据不出本机
鉴权方式会话登录远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时agent-deck · Cross-platform本地安装时用到的包标识与运行时
部署类型本地部署上游给出的部署形态
最近核验2026-04-11上游最后核验时间

详细介绍

89.4 KB
来自项目仓库与上游目录的原文,未做删改

Agent Deck

Your AI agent command center

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 keep a whole fleet manageable.

https://github.com/user-attachments/assets/e4f55917-435c-45ba-92cc-89737d0d1401

Contributing: start here

agent-deck is actively maintained by Ashesh, and it welcomes both contributors and co-maintainers. PRs here don't sit: every incoming PR is validated (applied, built, tested) within about a day, and good ones merge in the next release batch. Recent releases have shipped dozens of community fixes.

Beyond one-off PRs, we're looking for 1-2 regular co-maintainers: people who want to own an area (a tool integration, the TUI, the web view, CI) and help triage and review. The validation pipeline does the heavy lifting; maintainers steer.

To get started:

  1. Read CONTRIBUTING.md: how the pipeline works, what makes a PR land fast, and the house rules.
  2. Contributing with an AI agent? Point it at .github/INTAKE.md, the machine-readable intake spec — or the contributor workflow in the agent-deck skill, which walks an agent (or you) through building, testing, and shaping a clean PR.
  3. Comment on an issue before starting work so we can tell you if someone (human or agent) is already on it.
  4. Look for issues labeled good first issue: curated to be small and self-contained.

Looking for something specific to work on? docs/ROADMAP.md lists ideas and follow-ups that are real but not yet scheduled.

If you've had a couple of PRs land here and want to help steer, open an issue titled "maintainer: your area". We'd love the help.

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 for full details.

Shell completion

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

# zsh
echo 'source <(agent-deck completion zsh)' >> ~/.zshrc

# fish
agent-deck completion fish > ~/.config/fish/completions/agent-deck.fish

Open a new shell (or re-source the config file) afterwards.

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 send my-proj --message-file task.md # Send a multiline prompt
agent-deck session ref my-proj reviewer # Type a reference to my-proj into reviewer (not sent)
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 again after v1.16.32:** in the new-session dialog (`n`), **Enter creates the session from any row** with what is filled in: this folder, your last-used tool, the selected group, and the folder name when Name is empty. `n` then `Enter` is the whole common case; `N` on the home screen creates without the dialog. Tab/↓ reach the optional rows, `↓`/`Space` open the model list, and a wrong required field takes focus with the reason. To walk the form with Enter down to the **`[ Create session ]`** button instead, set `[ui].new_session_enter_advances = true`; **Ctrl+S** creates from any field in both modes.

### Key Shortcuts

From the main menu, `o` and `Shift+Q` open a message composer above the footer.
Press `Enter` to submit, `Ctrl+J` for a newline, or `Esc` to cancel.
`Ctrl+X`, then `E`, opens the draft in `$VISUAL` / `$EDITOR` (fallback: `vi`);
returning from the editor restores the draft without sending it.
Queueing uses native Claude/OpenCode 2 queueing where available and waits for
the current turn to finish on other commands.
OpenCode 2 queueing uses its session API and requires a detected session ID;
unconfirmed delivery is reported without retrying or falling back to terminal keys.
The main-menu composer currently supports local sessions only, not remote-session rows.

| Key | Action |
|-----|--------|
| `Enter` | Attach to session |
| `Ctrl+Q` | Detach from session |
| `n` | New session |
| `f` / `F` | Fork (quick / dialog) |
| `A` / `Shift+U` | Archive / unarchive session |
| `^` | Show archived sessions |
| `m` | MCP Manager |
| `o` | Send a message to the selected session (a busy Claude session queues it, no interrupt) |
| `Shift+Q` | Queue a message after the current turn |
| `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) |
| `c` / `B` | Copy last AI response / session info (repo, path, branch) |
| `C` | Context inspector (what the session is sent, ranked by cost) |
| `V` / `Y` | Copy visible terminal text / a fenced code block |
| `Shift+drag` | Select text natively (`Option+drag` in iTerm2) — see below |
| `?` | Full help |

> **Why can't I drag-select text?** The TUI holds the terminal in mouse
> reporting mode so clicks, wheel scrolling and the divider drag work, which
> means your terminal never sees a drag as a selection. Hold `Shift` while
> dragging (`Option` in iTerm2) to bypass it, or use the `c` / `B` / `V` / `Y`
> copy keys above. Full detail in
> Terminal shortcuts.

See TUI Reference for all shortcuts and CLI Reference 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/ — two-minute local quickstart, architecture,
    state files, lifecycle, remote channel setup (Telegram/Slack/Discord/Mattermost), gotchas.
  • docs/WATCHER-SETUP.md — add "doorbells" so the outside world
    (GitHub events, gmail, ntfy pushes, meetings) can wake the conductor up.

Features

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 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: account > conductor > group > env > 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..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. The session's account (`--account ` → `[profiles..claude]`)
2. `[conductors..claude]` (when the session is a conductor session, i.e. Title starts with `conductor-`)
3. `[groups."".claude]`
4. `CLAUDE_CONFIG_DIR` env var
5. `[profiles..claude]`
6. `[claude]` (global)
7. `~/.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]`.

#### 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=` 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 `.
Run `agent-deck accounts` (or `agent-deck accounts --json`) to list named slots
configured under `[profiles..claude].config_dir`.

To put every *new* Claude session on one slot until you change it (say, while
another account is near its weekly limit), set a default account:
`agent-deck config set claude.default_account work`, or Settings (`S`) →
Claude → Default account. The New Session dialog then starts on
`work (default)`, and `add` / `launch` without `--account` use it too.
Existing sessions keep their account, a group or conductor `config_dir` still
wins, and this machine's default never travels to a remote (a remote server
applies its own `default_account`, if it has one). See
`default_account`.

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

### Session naming

Titles and groups answer different questions — "what is this, at a glance?" versus "why do these sessions belong together?" — and each has its own controls.

#### Stable titles

By default, agent-deck syncs a session's displayed title from the tool's own session name (Claude's `/rename`, `claude --name`, etc.), which is useful for watching a list of live agents but means a title you set can later be overwritten. Pick the control that matches how stable you need the title to be:

| You want | Do this |
| --- | --- |
| This one session keeps the title I gave it | `--title-lock` (alias `--no-title-sync`) on `agent-deck add` / `agent-deck launch`, or `agent-deck session set-title-lock  on` at runtime |
| No session in this installation ever gets renamed by its agent | `sync_title = false` in `config.toml` |
| Claude should receive the exact deck title at startup | supported Claude launch/restart/resume commands get `--name`; `push_title = false` opts out. A deck rename takes effect on the next start, not immediately. |
| A throwaway session where the live task description matters more than a fixed name | `agent-deck add --quick` (`-Q` short flag) — the list shows the session's current Claude task in place of the generated handle |

An explicit `-t/--title` locks the title automatically, the same as passing `--title-lock` — there's no separate opt-in needed. There's also no create-time opt-out: if you want a session with an explicit title to still pick up the agent's renames, unlock it afterward with `agent-deck session set-title-lock  off`. A locked title is never silently overwritten by the sync path — it only changes via an explicit rename or `session set-title-lock  off`.

#### Groups vs. parent linkage

Groups carry real policy — `max_concurrent` (serial vs. bounded parallelism), `default_path`, and per-group Claude account/config (see Declarative groups and Per-group Claude config above). Treat that policy as the test for whether a new group is warranted:

- **Don't encode dispatch relationships in a group name.** A conductor fanning out workers doesn't need `work`, `work-infra`, `work-hygiene` siblings to say "these came from the same orchestrator" — that's what parent linkage is for. Launch with `--parent ` (or let `agent-deck launch` auto-parent), and read the fleet back with `agent-deck session children`.
- **Create a new group when something policy-shaped differs** from the parent group — a different concurrency cap, working directory, or Claude account. If nothing enforced differs, the thing you have is a topic, not a group; carry it in the title and parent linkage instead.
- **Don't rely on titles or group names as machine keys.** Both are user-editable; a script or agent matching on either is relying on something that can change under it.

There's no automated warning or enforcement for group sprawl yet — this is a documented convention, not a gate. See `docs/design/2026-07-26-session-identity-and-group-purpose.md` for the fuller design writeup (task-identity field, group `--purpose`, advisory sprawl warning) if you hit a concrete gap this section doesn't cover.

### MCP Socket Pool

Running many sessions? Socket pooling shares MCP processes across all sessions via Unix sockets, so each server runs once instead of once per session. A health check every 3 seconds restarts a crashed MCP behind a reconnecting proxy. Enable with `pool_all = true` in config.toml.

### Search

Press `/` to fuzzy-search across all sessions. Filter by status with `!` (running), `@` (waiting), `#` (idle), `&` (error). Press `0` to clear the filter. Press `$` for the Cost Dashboard and `G` for Recall search across every conversation on this machine.

### 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 | `Home` / `End` | Jump to top / bottom of list |
| Global | `G` | Open Recall search across every conversation on this machine |
| 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.

#### Sparse Checkout (large monorepos)

If the session you create the worktree from uses sparse checkout, a new worktree normally checks out the *whole* repository first — minutes of I/O on a monorepo with hundreds of thousands of files. Opt into inheriting the sparse configuration instead:```toml
[worktree]
sparse_checkout = "inherit"   # "off" (default) keeps git's normal checkout

With inherit, agent-deck reads the sparse mode (cone / non-cone, sparse index) and patterns from the worktree you invoked from, creates the new worktree with --no-checkout, and materializes it directly with those patterns — the excluded tree is never written. .worktreeinclude and .agent-deck/worktree-setup.sh still run afterwards, so the setup script sees the same sparse paths the source session has.

A non-sparse source, or off/unset, keeps today's behavior exactly. Inheritance replays the patterns through git sparse-checkout set and pins the sparse-index setting explicitly, so it needs git 2.32 or newer; the default (off) has no version requirement.

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.

#### Worktree Setup Script

For imperative setup tasks (installing dependencies, running migrations, etc.), create a script at `.agent-deck/worktree-setup.sh`.
Once you have approved it (see Approving worktree hooks), agent-deck runs it 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

It runs in the new worktree with your full environment. An executable script runs directly (its #! line picks the interpreter); a non-executable one runs via sh -e. Under the default approval policy, agent-deck runs a private copy of the approved bytes, so a hook changed while you answer the prompt cannot execute instead. Use the working directory and the two environment variables above to locate project files; the script's own $0 path points to that temporary copy. The timeout is 60 seconds ([worktree] setup_timeout_seconds). If it fails or is skipped, the worktree is still created: you'll see a warning and 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.
Once approved, agent-deck runs it 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 uses the same dispatch and a 60-second timeout. If it fails or is skipped, removal proceeds anyway and you'll see a warning. It does not run for sessions that reuse the main working tree (nothing is removed there).

#### Approving worktree hooks

These two hooks are code from the repository, and they run as you. Creating or removing a worktree does not by itself approve them, so a repository you just cloned cannot run anything on your machine until you say so.

**What is approved.** An approval covers one hook (setup and destruction are separate) in one repository, and is bound to the script's exact bytes (sha256), its real location (symlinks resolved) and how it runs (directly via `#!`, or `sh -e`). Editing the script, retargeting a symlink or flipping its executable bit asks again. Approvals live in agent-deck's data directory (`~/.local/share/agent-deck/worktree-script-consent.json`), never in the repository.

**When you are asked.** The first time a hook would run, and after any change:

- **TUI:** a dialog shows the repository, the hook, the command that will run, its sha256 and up to the first 20 lines (with an omitted-line count when space is tight), with **Run once**, **Always trust this version** and **Skip** (the default).
- **CLI on a terminal:** the same details, then `[o]nce, [a]lways trust this version, [N]o/skip`.
- **CLI without a terminal** (scripts, CI, `remote`), and requests from the web UI: the hook is skipped with a one-line notice naming the command that approves it.

**Approving ahead of time.**```bash
agent-deck worktree trust-hooks .                          # show each hook, ask y/N
agent-deck worktree trust-hooks . --hook setup --yes       # scripts: approve after reviewing
agent-deck worktree trust-hooks . --revoke                 # forget the approvals
agent-deck launch . -w feat -b --run-hooks                 # run unapproved hooks this once (prints sha256)
agent-deck launch . -w feat -b --run-hooks --trust         # ...and remember that version

[worktree] run_repo_scripts sets the policy: "prompt" (default), "never" (hooks never run), or "always" (every hook runs without asking; only for machines where you own every repository you open, because any repository you create a worktree in can then run code as you). Remote hosts apply their own policy and approvals: run trust-hooks on the remote host.

Bare repositories and worktrees

Agent-deck supports two flavors of the bare-repo layout 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 alongside its internal files:```
project.git/                       # this dir IS the bare repo
├── HEAD, config, objects/, refs/, packed-refs, worktrees/, ...
├── .agent-deck/
│   └── worktree-setup.sh          # shared setup script (optional)
├── main/                          # linked worktree on main
│   └── .git                       # file: gitdir: ../worktrees/main
└── feature-x/                     # linked worktree on feature-x
    └── .git

How agent-deck resolves these layouts (v1.7.58+ for nested, v1.9.10+ for at-root):

  • All three handles work. agent-deck add, agent-deck add, and agent-deck add all resolve to the same project root. For the nested layout that's the dir holding .bare/. For the at-root layout that's the bare dir itself (project.git/). Every linked worktree is treated as equal.
  • The project root is where shared config lives. Place .agent-deck/worktree-setup.sh at /.agent-deck/worktree-setup.sh. Agent-deck looks for it at exactly that path — it does not search individual worktrees. In the at-root layout that means .agent-deck/ lives inside the bare dir alongside HEAD and objects/.
  • AGENT_DECK_REPO_ROOT inside the setup script points to the project root. Same as above — for at-root that's the bare dir itself.

…(正文过长,页面只展示前面部分,完整内容见仓库)

常见问题

8 问
答案由本站依据条目字段整理,不引用上游原文
agent-deck 怎么安装?

在客户端按下面的安装命令接入:go install asheshgoplani/agent-deck@latest。对应的包名是 agent-deck。装完在客户端配置里引用同一个包或端点。

agent-deck 怎么在 Claude Desktop、Cursor、Cline 里配置?

它的传输方式是stdio · 本地进程,在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,配置才会生效。

agent-deck 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

agent-deck 需要 API Key 吗?

资料标注需要会话登录认证,使用前准备好对应凭据,并按最小权限配置。

agent-deck 支持哪些客户端?

资料标注支持 Claude Desktop、Cursor、Cline、Claude Code;其他客户端只要能配置 MCP Server,也能用同样的命令或地址接入。

agent-deck 能提供哪些能力?

资料显示能力标签包括 agent-deck、ai-agent、ai-agents、ai-coding-assistant、aider。具体工具清单以官方文档为准。

agent-deck 需要什么运行环境?

运行时为 Cross-platform;属于本地进程,需要在本机装好运行环境。

agent-deck 是本地还是远程?

它是本地进程(stdio),由客户端在本机拉起。传输方式为stdio · 本地进程。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 2026-04-11。