agent-deck

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Agent Deck

Terminal session manager for AI coding agents. Built with Go + Bubble Tea.

Version: 0.8.98 | Repo: github.com/asheshgoplani/agent-deck | Discord: discord.gg/e4xSs6NBN8

面向AI编码Agent的终端会话管理器，基于Go + Bubble Tea构建。

版本： 0.8.98 | 仓库： github.com/asheshgoplani/agent-deck | Discord社区： discord.gg/e4xSs6NBN8

Script Path Resolution (IMPORTANT)

脚本路径解析（重要）

This skill includes helper scripts in its

scripts/

subdirectory. When Claude Code loads this skill, it shows a line like:

Base directory for this skill: /path/to/.../skills/agent-deck

You MUST use that base directory path to resolve all script references. Store it as

SKILL_DIR

bash

undefined

本Skill在其

scripts/

子目录中包含辅助脚本。当Claude Code加载本Skill时，会显示如下内容：

Base directory for this skill: /path/to/.../skills/agent-deck

你必须使用该基础目录路径来解析所有脚本引用，并将其存储为

SKILL_DIR

：

bash

undefined

Set SKILL_DIR to the base directory shown when this skill was loaded

将SKILL_DIR设置为加载本Skill时显示的基础目录

SKILL_DIR="/path/shown/in/base-directory-line"

Then run scripts as:

然后按如下方式运行脚本：

$SKILL_DIR/scripts/launch-subagent.sh "Title" "Prompt" --wait


**Common mistake:** Do NOT use `<project-root>/scripts/launch-subagent.sh`. The scripts live inside the skill's own directory (plugin cache or project skills folder), NOT in the user's project root.

**For plugin users**, the path looks like: `~/.claude/plugins/cache/agent-deck/agent-deck/<hash>/skills/agent-deck/scripts/`
**For local development**, the path looks like: `<repo>/skills/agent-deck/scripts/`

$SKILL_DIR/scripts/launch-subagent.sh "Title" "Prompt" --wait


**常见错误：** 请勿使用`<project-root>/scripts/launch-subagent.sh`。脚本位于Skill自身的目录中（插件缓存或项目Skills文件夹），而非用户的项目根目录。

**插件用户**的路径格式为：`~/.claude/plugins/cache/agent-deck/agent-deck/<hash>/skills/agent-deck/scripts/`
**本地开发**的路径格式为：`<repo>/skills/agent-deck/scripts/`

Quick Start

快速开始

bash

undefined

bash

undefined

Launch TUI

启动TUI界面

agent-deck

Create and start a session

创建并启动会话

agent-deck add -t "Project" -c claude /path/to/project agent-deck session start "Project"

Send message and get output

发送消息并获取输出

agent-deck session send "Project" "Analyze this codebase" agent-deck session output "Project"

undefined

agent-deck session send "Project" "分析此代码库" agent-deck session output "Project"

undefined

Essential Commands

核心命令

Command	Purpose
`agent-deck`	Launch interactive TUI
`agent-deck add -t "Name" -c claude /path`	Create session
`agent-deck session start/stop/restart <name>`	Control session
`agent-deck session send <name> "message"`	Send message
`agent-deck session output <name>`	Get last response
`agent-deck session current [-q\|--json]`	Auto-detect current session
`agent-deck session fork <name>`	Fork Claude conversation
`agent-deck mcp list`	List available MCPs
`agent-deck mcp attach <name> <mcp>`	Attach MCP (then restart)
`agent-deck status`	Quick status summary
`agent-deck add --worktree <branch>`	Create session in git worktree
`agent-deck worktree list`	List worktrees with sessions
`agent-deck worktree cleanup`	Find orphaned worktrees/sessions

Status:

●

running |

◐

waiting |

○

idle |

✕

error

命令	用途
`agent-deck`	启动交互式TUI界面
`agent-deck add -t "Name" -c claude /path`	创建会话
`agent-deck session start/stop/restart <name>`	控制会话状态
`agent-deck session send <name> "message"`	发送消息
`agent-deck session output <name>`	获取最新响应
`agent-deck session current [-q\|--json]`	自动检测当前会话
`agent-deck session fork <name>`	复刻Claude对话
`agent-deck mcp list`	列出可用的MCP
`agent-deck mcp attach <name> <mcp>`	挂载MCP（之后需重启会话）
`agent-deck status`	快速查看状态摘要
`agent-deck add --worktree <branch>`	在Git工作树中创建会话
`agent-deck worktree list`	列出关联会话的工作树
`agent-deck worktree cleanup`	查找孤立的工作树/会话

状态标识：

●

运行中 |

◐

等待中 |

○

空闲 |

✕

异常

Sub-Agent Launch

子Agent启动

Use when: User says "launch sub-agent", "create sub-agent", "spawn agent"

bash

$SKILL_DIR/scripts/launch-subagent.sh "Title" "Prompt" [--mcp name] [--wait]

The script auto-detects current session/profile and creates a child session.

适用场景： 用户提及“launch sub-agent”、“create sub-agent”、“spawn agent”时

bash

$SKILL_DIR/scripts/launch-subagent.sh "Title" "Prompt" [--mcp name] [--wait]

该脚本会自动检测当前会话/配置文件并创建子会话。

Retrieval Modes

结果获取模式

Mode	Command	Use When
Fire & forget	(no --wait)	Default. Tell user: "Ask me to check when ready"
On-demand	`agent-deck session output "Title"`	User asks to check
Blocking	`--wait` flag	Need immediate result

模式	命令	适用场景
即发即忘	（不加--wait参数）	默认模式。告知用户：“准备就绪后可让我查看结果”
按需获取	`agent-deck session output "Title"`	用户主动要求查看结果时
阻塞等待	添加 `--wait` 参数	需要立即获取结果时

Recommended MCPs

Task Type	MCPs
Web research	`exa` , `firecrawl`
Code documentation	`context7`
Complex reasoning	`sequential-thinking`

任务类型	MCP
网页调研	`exa` , `firecrawl`
代码文档生成	`context7`
复杂推理	`sequential-thinking`

Consult Another Agent (Codex, Gemini)

咨询其他Agent（Codex、Gemini）

Use when: User says "consult with codex", "ask gemini", "get codex's opinion", "what does codex think", "consult another agent", "brainstorm with codex/gemini", "get a second opinion"

IMPORTANT: You MUST use the

--tool

flag to specify which agent. Without it, the script defaults to Claude.

适用场景： 用户提及“consult with codex”、“ask gemini”、“get codex's opinion”、“what does codex think”、“consult another agent”、“brainstorm with codex/gemini”、“get a second opinion”时

重要提示： 必须使用

--tool

参数指定目标Agent。若不指定，脚本默认使用Claude。

Quick Reference

快速参考

bash

undefined

bash

undefined

Consult Codex (MUST include --tool codex)

咨询Codex（必须添加--tool codex参数）

$SKILL_DIR/scripts/launch-subagent.sh "Consult Codex" "Your question here" --tool codex --wait --timeout 120

$SKILL_DIR/scripts/launch-subagent.sh "Consult Codex" "你的问题内容" --tool codex --wait --timeout 120

Consult Gemini (MUST include --tool gemini)

咨询Gemini（必须添加--tool gemini参数）

$SKILL_DIR/scripts/launch-subagent.sh "Consult Gemini" "Your question here" --tool gemini --wait --timeout 120


**DO NOT** try to create Codex/Gemini sessions manually with `agent-deck add`. Always use the script above. It handles tool-specific initialization, readiness detection, and output retrieval automatically.

$SKILL_DIR/scripts/launch-subagent.sh "Consult Gemini" "你的问题内容" --tool gemini --wait --timeout 120


**请勿**尝试使用`agent-deck add`命令手动创建Codex/Gemini会话。请始终使用上述脚本，它会自动处理工具特定的初始化、就绪检测及结果获取流程。

Full Options

完整参数选项

bash

$SKILL_DIR/scripts/launch-subagent.sh "Title" "Prompt" \
  --tool codex|gemini \     # REQUIRED for non-Claude agents
  --path /project/dir \     # Working directory (auto-inherits parent path if omitted)
  --wait \                  # Block until response is ready
  --timeout 180 \           # Seconds to wait (default: 300)
  --mcp exa                 # Attach MCP servers (can repeat)

bash

$SKILL_DIR/scripts/launch-subagent.sh "Title" "Prompt" \
  --tool codex|gemini \     # 非Claude Agent必填
  --path /project/dir \     # 工作目录（若省略则自动继承父会话路径）
  --wait \                  # 阻塞等待直到响应就绪
  --timeout 180 \           # 等待超时时间（秒，默认300）
  --mcp exa                 # 挂载MCP服务（可重复添加）

Supported Tools

支持的工具

Tool	Flag	Notes
Claude	`--tool claude`	Default, no flag needed
Codex	`--tool codex`	Requires `codex` CLI installed
Gemini	`--tool gemini`	Requires `gemini` CLI installed

工具	参数标识	说明
Claude	`--tool claude`	默认选项，无需指定参数
Codex	`--tool codex`	需提前安装 `codex` CLI
Gemini	`--tool gemini`	需提前安装 `gemini` CLI

How It Works

工作流程

Script auto-detects current session and profile
Creates a child session with the specified tool in the parent's project directory
Waits for the tool to initialize (handles Codex approval prompts automatically)
Sends the question/prompt
With
```
--wait
```
: polls until the agent responds, then returns the full output
Without
```
--wait
```
: returns immediately, check output later with
```
agent-deck session output "Title"
```

脚本自动检测当前会话及配置文件
在父会话的项目目录中创建指定工具的子会话
等待工具初始化完成（自动处理Codex的授权提示）
发送问题/提示内容
若添加
```
--wait
```
参数：轮询直到Agent返回响应，然后返回完整输出
若未添加
```
--wait
```
参数：立即返回，之后可通过
```
agent-deck session output "Title"
```
查看结果

Examples

示例

bash

undefined

bash

undefined

Code review from Codex

让Codex进行代码评审

$SKILL_DIR/scripts/launch-subagent.sh "Codex Review" "Read cmd/main.go and suggest improvements" --tool codex --wait --timeout 180

$SKILL_DIR/scripts/launch-subagent.sh "Codex代码评审" "读取cmd/main.go并提出改进建议" --tool codex --wait --timeout 180

Architecture feedback from Gemini

让Gemini提供架构反馈

$SKILL_DIR/scripts/launch-subagent.sh "Gemini Arch" "Review the project structure and suggest better patterns" --tool gemini --wait --timeout 180

$SKILL_DIR/scripts/launch-subagent.sh "Gemini架构评估" "评审项目结构并提出更优模式建议" --tool gemini --wait --timeout 180

Both in parallel (consult both, compare answers)

同时咨询两者（并行执行，对比结果）

$SKILL_DIR/scripts/launch-subagent.sh "Ask Codex" "Best way to handle errors in Go?" --tool codex --wait --timeout 120 & $SKILL_DIR/scripts/launch-subagent.sh "Ask Gemini" "Best way to handle errors in Go?" --tool gemini --wait --timeout 120 & wait

undefined

$SKILL_DIR/scripts/launch-subagent.sh "咨询Codex" "Go语言中处理错误的最佳方式是什么？" --tool codex --wait --timeout 120 & $SKILL_DIR/scripts/launch-subagent.sh "咨询Gemini" "Go语言中处理错误的最佳方式是什么？" --tool gemini --wait --timeout 120 & wait

undefined

Cleanup

清理会话

After getting the response, remove the consultation session:

bash

agent-deck remove "Consult Codex"

获取响应后，可删除咨询会话：

bash

agent-deck remove "Consult Codex"

Or remove multiple at once:

或批量删除：

agent-deck remove "Codex Review" && agent-deck remove "Gemini Arch"

undefined

agent-deck remove "Codex代码评审" && agent-deck remove "Gemini架构评估"

undefined

TUI Keyboard Shortcuts

TUI键盘快捷键

Navigation

导航操作

Key	Action
`j/k` or `↑/↓`	Move up/down
`h/l` or `←/→`	Collapse/expand groups
`Enter`	Attach to session

按键	操作
`j/k` 或 `↑/↓`	上下移动
`h/l` 或 `←/→`	折叠/展开分组
`Enter`	连接到会话

Session Actions

会话操作

Key	Action
`n`	New session
`r/R`	Restart (reloads MCPs)
`M`	MCP Manager
`f/F`	Fork Claude session
`d`	Delete
`m`	Move to group

按键	操作
`n`	新建会话
`r/R`	重启会话（重新加载MCP）
`M`	打开MCP管理器
`f/F`	复刻Claude会话
`d`	删除会话
`m`	将会话移动到指定分组

Search & Filter

搜索与过滤

Key	Action
`/`	Local search
`G`	Global search (all Claude conversations)
`!@#$`	Filter by status (running/waiting/idle/error)

按键	操作
`/`	本地搜索
`G`	全局搜索（所有Claude对话）
`!@#$`	按状态过滤（运行中/等待中/空闲/异常）

Global

全局操作

Key	Action
`?`	Help overlay
`Ctrl+Q`	Detach (keep tmux running)
`q`	Quit

按键	操作
`?`	打开帮助弹窗
`Ctrl+Q`	断开连接（保持tmux后台运行）
`q`	退出TUI界面

MCP Management

MCP管理

Default: Do NOT attach MCPs unless user explicitly requests.

bash

undefined

默认规则： 除非用户明确要求，否则请勿挂载MCP。

bash

undefined

List available

列出可用的MCP

agent-deck mcp list

Attach and restart

挂载MCP并重启会话

agent-deck mcp attach <session> <mcp-name> agent-deck session restart <session>

Or attach on create

或在创建会话时直接挂载

agent-deck add -t "Task" -c claude --mcp exa /path


**Scopes:**
- **LOCAL** (default) - `.mcp.json` in project, affects only that session
- **GLOBAL** (`--global`) - Claude config, affects all projects

agent-deck add -t "Task" -c claude --mcp exa /path


**作用范围：**
- **LOCAL**（默认） - 项目目录下的`.mcp.json`，仅影响当前会话
- **GLOBAL**（添加`--global`参数） - Claude全局配置，影响所有项目

Worktree Workflows

Git工作树工作流

Create Session in Git Worktree

在Git工作树中创建会话

When working on a feature that needs isolation from main branch:

bash

undefined

当开发需要与主分支隔离的功能时：

bash

undefined

Create session with new worktree and branch

创建带新工作树和分支的会话

agent-deck add /path/to/repo -t "Feature Work" -c claude --worktree feature/my-feature --new-branch

agent-deck add /path/to/repo -t "功能开发" -c claude --worktree feature/my-feature --new-branch

Create session in existing branch's worktree

在已有分支的工作树中创建会话

agent-deck add . --worktree develop -c claude

undefined

agent-deck add . --worktree develop -c claude

undefined

List and Manage Worktrees

列出并管理工作树

bash

undefined

bash

undefined

List all worktrees and their associated sessions

列出所有工作树及其关联的会话

agent-deck worktree list

Show detailed info for a session's worktree

查看会话关联工作树的详细信息

agent-deck worktree info "My Session"

Find orphaned worktrees/sessions (dry-run)

查找孤立的工作树/会话（试运行）

agent-deck worktree cleanup

Actually clean up orphans

实际清理孤立资源

agent-deck worktree cleanup --force

undefined

agent-deck worktree cleanup --force

undefined

When to Use Worktrees

工作树适用场景

Use Case	Benefit
Parallel agent work	Multiple agents on same repo, different branches
Feature isolation	Keep main branch clean while agent experiments
Code review	Agent reviews PR in worktree while main work continues
Hotfix work	Quick branch off main without disrupting feature work

场景	优势
多Agent并行工作	同一仓库不同分支上运行多个Agent
功能开发隔离	Agent在隔离环境中实验，保持主分支干净
代码评审	Agent在工作树中评审PR，不影响主线工作
紧急修复	快速从主分支切出分支，不中断功能开发

Configuration

配置说明

File:

~/.agent-deck/config.toml

toml

[claude]
config_dir = "~/.claude-work"    # Custom Claude profile
dangerous_mode = true            # --dangerously-skip-permissions

[logs]
max_size_mb = 10                 # Max before truncation
max_lines = 10000                # Lines to keep

[mcps.exa]
command = "npx"
args = ["-y", "exa-mcp-server"]
env = { EXA_API_KEY = "key" }
description = "Web search"

See config-reference.md for all options.

配置文件：

~/.agent-deck/config.toml

toml

[claude]
config_dir = "~/.claude-work"    # 自定义Claude配置文件目录
dangerous_mode = true            # 启用--dangerously-skip-permissions模式

[logs]
max_size_mb = 10                 # 日志文件最大容量（MB）
max_lines = 10000                # 保留的最大日志行数

[mcps.exa]
command = "npx"
args = ["-y", "exa-mcp-server"]
env = { EXA_API_KEY = "key" }
description = "网页搜索"

完整配置选项请参考config-reference.md。

Troubleshooting

问题排查

Issue	Solution
Session shows error	`agent-deck session start <name>`
MCPs not loading	`agent-deck session restart <name>`
Flag not working	Put flags BEFORE arguments: `-m "msg" name` not `name -m "msg"`

问题	解决方案
会话显示异常	执行 `agent-deck session start <name>`
MCP无法加载	执行 `agent-deck session restart <name>`
参数不生效	参数需放在参数值之前：如 `-m "msg" name` ，而非 `name -m "msg"`

Get Help

获取帮助

Discord: discord.gg/e4xSs6NBN8 for quick questions and community support
GitHub Issues: For bug reports and feature requests

Discord社区： discord.gg/e4xSs6NBN8，用于快速提问及社区支持
GitHub Issues： 用于提交Bug报告及功能需求

Report a Bug

Bug报告

If something isn't working, create a GitHub issue with context:

bash

undefined

若遇到问题，请携带上下文信息在GitHub创建Issue：

bash

undefined

Gather debug info

收集调试信息

agent-deck version agent-deck status --json cat ~/.agent-deck/config.toml | grep -v "KEY|TOKEN|SECRET" # Sanitized config

agent-deck version agent-deck status --json cat ~/.agent-deck/config.toml | grep -v "KEY|TOKEN|SECRET" # 脱敏后的配置文件

Create issue at:

提交Issue地址：

https://github.com/asheshgoplani/agent-deck/issues/new


**Include:**
1. What you tried (command/action)
2. What happened vs expected
3. Output of commands above
4. Relevant log: `tail -100 ~/.agent-deck/logs/agentdeck_<session>_*.log`

See [troubleshooting.md](references/troubleshooting.md) for detailed diagnostics.


**需包含内容：**
1. 尝试执行的操作（命令/动作）
2. 实际结果与预期结果
3. 上述命令的输出内容
4. 相关日志：`tail -100 ~/.agent-deck/logs/agentdeck_<session>_*.log`

详细诊断步骤请参考[troubleshooting.md](references/troubleshooting.md)。

Session Sharing

会话共享

Share Claude sessions between developers for collaboration or handoff.

Use when: User says "share session", "export session", "send to colleague", "import session"

bash

undefined

在开发者之间共享Claude会话，用于协作或任务交接。

适用场景： 用户提及“share session”、“export session”、“send to colleague”、“import session”时

bash

undefined

Export current session to file (session-share is a sibling skill)

将当前会话导出到文件（session-share为同级Skill）

$SKILL_DIR/../session-share/scripts/export.sh

Output: ~/session-shares/session-<date>-<title>.json

输出文件路径：~/session-shares/session-<date>-<title>.json

Import received session

导入收到的会话

$SKILL_DIR/../session-share/scripts/import.sh ~/Downloads/session-file.json


**See:** [session-share skill](../session-share/SKILL.md) for full documentation.

$SKILL_DIR/../session-share/scripts/import.sh ~/Downloads/session-file.json


**详细文档：** 请参考[session-share skill](../session-share/SKILL.md)。

Critical Rules

核心规则

Flags before arguments:

session start -m "Hello" name

(not

name -m "Hello"

)

Restart after MCP attach: Always run
```
session restart
```
after
```
mcp attach
```
Never poll from other agents - can interfere with target session

参数在前，参数值在后： 如
```
session start -m "Hello" name
```
，而非
```
name -m "Hello"
```
挂载MCP后需重启会话： 执行
```
mcp attach
```
后必须运行
```
session restart
```
请勿从其他Agent轮询： 会干扰目标会话的正常运行

References

参考文档

cli-reference.md - Complete CLI command reference
config-reference.md - All config.toml options
tui-reference.md - TUI features and shortcuts
troubleshooting.md - Common issues and bug reporting
session-share skill - Export/import sessions for collaboration

cli-reference.md - 完整CLI命令参考
config-reference.md - 所有config.toml配置选项
tui-reference.md - TUI功能及快捷键说明
troubleshooting.md - 常见问题及Bug报告指南
session-share skill - 会话导出/导入协作文档

agent-deck

Original

Translation

Agent Deck

Agent Deck

Script Path Resolution (IMPORTANT)

脚本路径解析（重要）

Set SKILL_DIR to the base directory shown when this skill was loaded

将SKILL_DIR设置为加载本Skill时显示的基础目录

Then run scripts as:

然后按如下方式运行脚本：

Quick Start

快速开始

Launch TUI

启动TUI界面

Create and start a session

创建并启动会话

Send message and get output

发送消息并获取输出

Essential Commands

核心命令

Sub-Agent Launch

子Agent启动

Retrieval Modes

结果获取模式

Recommended MCPs

推荐使用的MCP

Consult Another Agent (Codex, Gemini)

咨询其他Agent（Codex、Gemini）

Quick Reference

快速参考

Consult Codex (MUST include --tool codex)

咨询Codex（必须添加--tool codex参数）

Consult Gemini (MUST include --tool gemini)

咨询Gemini（必须添加--tool gemini参数）

Full Options

完整参数选项

Supported Tools

支持的工具

How It Works

工作流程

Examples

示例

Code review from Codex

让Codex进行代码评审

Architecture feedback from Gemini

让Gemini提供架构反馈

Both in parallel (consult both, compare answers)

同时咨询两者（并行执行，对比结果）

Cleanup

清理会话

Or remove multiple at once:

或批量删除：

TUI Keyboard Shortcuts

TUI键盘快捷键

Navigation

导航操作

Session Actions

会话操作

Search & Filter

搜索与过滤

Global

全局操作

MCP Management

MCP管理

List available

列出可用的MCP

Attach and restart

挂载MCP并重启会话

Or attach on create

或在创建会话时直接挂载

Worktree Workflows

Git工作树工作流

Create Session in Git Worktree

在Git工作树中创建会话

Create session with new worktree and branch

创建带新工作树和分支的会话

Create session in existing branch's worktree

在已有分支的工作树中创建会话

List and Manage Worktrees