1. 项目概述如果你和我一样每天要同时开着五六个AI编程助手窗口——Claude Code在重构前端Gemini CLI在写后端APIOpenCode在调试脚本还有几个实验性的会话在后台挂着——那你肯定经历过这种混乱。终端标签页多到看不清标题想切回半小时前那个关键的对话得在十几个窗口里翻找某个会话卡在等待输入你完全没注意到直到半小时后才发现它一直在那儿干等。更别提管理不同项目的MCP服务器、技能配置还有那些临时起意的分支会话了。这种碎片化的管理方式严重拖慢了AI辅助编程的流畅度。Agent Deck就是为了解决这个痛点而生的。你可以把它理解为你所有AI代理的“任务控制中心”。它是一个基于终端的TUI文本用户界面应用用Go语言编写深度集成tmux让你在一个统一的视图中管理所有Claude Code、Gemini CLI、OpenCode、Codex等终端AI工具的会话。核心价值就一句话一个终端掌控所有AI代理状态一目了然。无论你是独立开发者还是团队里的技术负责人只要你在日常工作中重度依赖多个AI编程助手Agent Deck都能显著提升你的工作流效率和掌控感。它的设计哲学很明确不替代任何AI工具本身而是成为它们之上的“管理层”。你原来怎么用Claude Code现在还怎么用只是现在你能在一个地方看到所有会话的实时状态运行中、等待输入、空闲、错误用快捷键瞬间切换按项目分组管理还能进行会话分叉、MCP服务器动态挂载、Git工作树隔离等高级操作。最近还加入了成本追踪仪表板、Docker沙箱运行、以及“指挥家”Conductor这种能自动监控并响应其他会话的智能体功能已经相当丰富。2. 核心架构与设计思路拆解2.1 为什么基于Tmux和TUIAgent Deck选择Tmux作为底层会话管理的基础这是一个非常务实且高效的选择。Tmux本身就是一个成熟的终端复用器它提供了稳定的会话session、窗口window和窗格pane管理能力并且可以在后台持久化运行。Agent Deck没有重复造轮子而是将每个AI代理会话例如一个Claude Code进程运行在一个独立的Tmux窗格中。这样做有几个关键优势第一状态持久化与恢复。即使你关闭了Agent Deck的TUI界面甚至重启了终端那些Tmux会话依然在后台运行。你重新打开Agent Deck所有会话的状态都能完美恢复。这比你自己维护一堆终端进程要可靠得多。第二统一的输入/输出控制。Tmux提供了标准的管道来向窗格发送命令和捕获输出。Agent Deck利用这一点来实现状态检测——通过定期向每个会话窗格发送特定的探测命令比如检查是否有等待输入的提示符来判断会话是“运行中”、“等待中”还是“空闲”。这种基于Tmux的探测方式比轮询进程列表或解析日志文件要精准和高效。第三无缝的终端体验。因为每个AI代理实际上就是运行在一个原生的终端窗格里所以它们的所有功能——包括语法高亮、交互式命令、甚至是一些依赖特定终端特性的功能——都能得到完全支持。用户切换到一个会话时感觉就像直接打开了那个终端没有任何中间层的隔阂感。而选择用Bubble Tea一个Go语言的TUI框架来构建上层管理界面则是为了极致的键盘操作效率和沉浸感。对于开发者来说在终端里工作是最自然的状态。一个精心设计的TUI可以通过j/k、f、/等快捷键完成所有操作手完全不用离开键盘比在GUI窗口间点击鼠标要快得多。Bubble Tea的组件化模型也让开发复杂的交互式界面如MCP管理器、成本仪表板成为可能。2.2 数据流与状态管理Agent Deck的核心是一个典型的事件驱动架构。我们可以把它想象成一个控制塔TUI和多个停机坪Tmux会话的关系。状态检测循环这是Agent Deck的“心跳”。它以一个可配置的间隔比如每2秒遍历所有被管理的Tmux会话。对于每个会话它通过Tmux命令捕获窗格的最后几行输出然后通过一系列正则表达式或关键字匹配来判断状态如果输出中包含“●”或类似的运行指示符或者检测到模型正在“思考”的动画则标记为运行中 (Running)。如果输出中包含“”、“Enter a prompt:”或“等待输入”等明确的提示符则标记为等待中 (Waiting)。如果一段时间内没有检测到活动且没有等待提示则标记为空闲 (Idle)。如果Tmux窗格无法连接或进程已退出则标记为错误 (Error)。这个状态信息会被实时更新到内存中的会话列表并反映在TUI的界面上用不同颜色和符号表示。同时状态变化也会触发事件比如“等待中”的会话会触发通知显示在Tmux状态栏或通过指挥家Conductor发送提醒。配置与持久化所有用户配置~/.agent-deck/config.toml、会话元数据、成本数据等都使用TOML和SQLite进行管理。SQLite数据库通常位于~/.agent-deck/profile/state.db记录了每个会话的创建时间、所属分组、工作目录、关联的Git分支、Tmux会话ID、最后一次已知状态等。这种设计保证了Agent Deck本身是无状态的——即使主进程重启它也能从数据库和Tmux中重建出完整的视图。MCP与技能池这是Agent Deck一个非常巧妙的设计。MCPModel Context Protocol服务器和Claude技能通常需要全局或项目级配置。Agent Deck没有让用户手动编辑复杂的配置文件而是引入了“池”Pool的概念。你将MCP服务器定义在全局配置中将技能文件放在~/.agent-deck/skills/pool/目录下。在TUI中通过MCP管理器按m和技能管理器按s你可以动态地为当前选中的会话“挂载”或“卸载”这些资源。Agent Deck会在后台自动生成正确的claude.toml或settings.json文件并重启Claude Code会话以应用更改。这实现了配置的“一次定义随处按需使用”既灵活又干净。3. 核心功能深度解析与实操要点3.1 会话分叉无损探索不同思路会话分叉Fork是我认为Agent Deck最提升效率的功能之一。当你在一个复杂的Claude对话中想尝试另一种实现方案但又不想丢失当前的对话历史和上下文时分叉功能就派上用场了。底层原理Agent Deck的分叉不是简单的复制粘贴。当你按f分叉一个会话时它会做以下几件事克隆对话历史它会读取原会话Claude Code的完整对话转录文件transcript。这个文件通常位于~/.claude/sessions/目录下包含了所有轮次的消息。创建新会话实体在Agent Deck的数据库和Tmux中创建一个全新的会话记录。这个新会话拥有独立的ID、窗格和工作目录如果是Git工作树则会创建新的工作树。继承环境与配置新会话会继承原会话的MCP服务器配置、技能挂载状态、环境变量等。这意味着你分叉后两个会话拥有完全相同的工具能力。启动新进程在新的Tmux窗格中启动一个新的Claude Code进程并将克隆的对话历史作为初始上下文加载进去。这样你就得到了两个并行的对话线。你可以在分叉A中继续优化原有方案同时在分叉B中尝试一个激进的重构。两者互不干扰。实操心得命名与分组默认分叉的会话名会加上“-fork”后缀但很容易混淆。我强烈建议在分叉时使用大写F它会弹出一个对话框让你自定义会话名和分组。例如将主会话命名为“refactor-auth”分叉会话命名为“refactor-auth-alternative”并放入同一个“auth”分组。这样在TUI中一目了然。对于探索性任务我甚至会创建“experiment-1”、“experiment-2”这样的分叉快速验证不同想法的可行性。3.2 Git工作树真正的并行开发沙盒对于版本控制下的项目让多个AI代理同时工作而不产生冲突是个挑战。Agent Deck的Git工作树Worktree功能完美解决了这个问题。它是如何工作的Git工作树是Git的一个原生功能允许你为同一个仓库签出多个并行的、独立的工作目录每个目录关联不同的分支。Agent Deck在此基础上做了自动化封装当你执行agent-deck add . -c claude --worktree feature/new-feature --new-branch时Agent Deck会在仓库中默认在仓库同级目录可配置为子目录创建一个新的工作树目录名通常为repo-name-branch-name。在该工作树中创建一个新的分支如果使用--new-branch或检出已有分支。在这个全新的、独立的工作目录中启动Claude Code会话。关键优势完全隔离每个工作树有自己的node_modules、构建产物、甚至.env文件通过worktree-setup.sh脚本复制。AI代理在其中一个工作树里安装依赖或修改文件完全不会影响其他会话。原子性操作agent-deck worktree finish “会话名”这个命令是神来之笔。它会自动将工作树中的分支合并回主分支或你指定的目标分支然后删除该工作树并清理Agent Deck中的会话记录。一键完成“开发-测试-合并-清理”的闭环。支持裸仓库布局对于高级的Git工作流如将.git目录放在.bare/中的布局Agent Deck也能智能识别确保工作树创建在正确的位置。避坑指南工作树设置脚本Git不会将忽略的文件如.env,.mcp.json复制到新工作树。你必须创建一个项目根目录/.agent-deck/worktree-setup.sh脚本。这个脚本会在每个新工作树创建后自动执行。一个典型的脚本如下#!/bin/sh # AGENT_DECK_REPO_ROOT 是主仓库路径 # AGENT_DECK_WORKTREE_PATH 是新工作树路径 for f in .env .env.local .mcp.json config/local.json; do if [ -f $AGENT_DECK_REPO_ROOT/$f ]; then cp $AGENT_DECK_REPO_ROOT/$f $AGENT_DECK_WORKTREE_PATH/$f echo Copied $f fi done # 你也可以在这里运行 npm install 或 poetry install但注意性能务必注意这个脚本必须放在项目根目录下的.agent-deck/文件夹里而不是某个工作树里。对于裸仓库布局根目录是包含.bare/文件夹的那个目录。3.3 MCP管理器与Socket池化资源管理的艺术MCP服务器为AI代理提供了扩展能力如文件搜索、网络请求但每个Claude Code会话启动一个MCP服务器进程内存消耗是巨大的。Agent Deck的MCP Socket池化Pooling功能将内存占用降低了85-90%。技术原理在没有池化的情况下10个Claude会话会启动10个相同的MCP服务器进程。启用池化后在config.toml中设置pool_all trueAgent Deck会为每个MCP服务器配置启动一个独立的守护进程。这个守护进程监听一个Unix Domain Socket。当任何Claude会话需要连接该MCP服务器时它不再直接启动进程而是连接这个共享的Socket。Agent Deck还会在守护进程崩溃时约3秒内自动重启它并让所有客户端会话重连。操作流程在~/.agent-deck/config.toml中定义你的MCP服务器。[[mcp_servers]] name brave-search command npx args [-y, modelcontextprotocol/server-brave-search] env { BRAVE_API_KEY {BRAVE_API_KEY} }在TUI中选中一个会话按m打开MCP管理器。使用空格键Space来为当前会话“开关”某个MCP服务器。使用Tab键可以在“仅当前会话(LOCAL)”和“全局所有会话(GLOBAL)”两种作用域间切换。Agent Deck会自动处理配置文件的生成和会话重启。Socket隔离v1.7.50这是一个重要的稳定性功能。通过在配置中添加[tmux] socket_name agent-deck你可以让Agent Deck运行在一个独立的Tmux服务器上。这意味着它的所有会话和你的日常终端Tmux会话完全隔离。你的个人Tmux配置、快捷键、状态栏插件都不会被Agent Deck干扰反之亦然。这彻底解决了早期版本中因Tmux配置冲突导致的问题。3.4 指挥家从手动管理到半自动运维指挥家Conductor是Agent Deck向“自治”迈出的关键一步。它本质上是一个特殊的、长期运行的AI代理会话被赋予了监控和响应其他“子”会话的能力。架构剖析当你运行agent-deck conductor setup ops时会发生以下事情创建身份目录在~/.agent-deck/conductor/ops/下创建专属的CLAUDE.md身份指令文件、meta.json配置和state.json运行时状态。启动守护进程一个名为conductor-ops的持久化Claude Code会话在后台启动。它的系统指令被精心设计使其能够理解Agent Deck的会话状态、接收事件并采取行动。可选连接消息桥如果你配置了Telegram或Slack一个桥接守护进程bridge.py会启动将外部消息路由给对应的指挥家。指挥家能做什么状态监控指挥家定期通过心跳或事件获取所有会话的状态列表。自动响应当它检测到一个子会话从“运行中”变为“等待中”或“错误”时可以根据预定义的策略或通过学习尝试自动回复。例如一个常见的“等待中”状态是Claude在等待用户批准执行一个命令。指挥家如果判断这个命令是安全的比如npm test可能会自动发送“y”进行批准。事件路由通过Webhook、GitHub、ntfy等适配器接入的外部事件可以被路由到指定的指挥家。例如一个GitHub PR创建的Webhook可以触发指挥家去自动审查代码。远程控制通过Telegram或Slack你可以向指挥家发送如ops: 检查前端会话状态这样的指令实现移动端管理。重要安全提示权限与危险模式默认情况下Claude Code在执行可能具有破坏性的命令如文件删除、系统命令前会请求用户批准。指挥家如果也被这个机制卡住就失去了自动化的意义。为了允许指挥家自动批准你需要在配置中明确开启“危险模式”[claude] allow_dangerous_mode true请务必理解其风险这赋予了指挥家很大的自主权。你应该只为高度可信的、在受控环境中运行的指挥家开启此选项并确保其系统指令CLAUDE.md包含了严格的安全约束。一个最佳实践是为不同的指挥家设置不同的Claude配置目录config_dir将危险模式仅限制在特定的指挥家配置中。4. 高级工作流与集成实践4.1 成本追踪仪表板让AI开销一目了然随着使用的AI模型越来越多 token消耗和成本变得难以追踪。Agent Deck内置的成本仪表板是一个强大的辅助决策工具。数据收集机制Claude Code通过解析Claude Code生成的对话转录文件transcript直接提取每轮对话的输入/输出token数。这是最准确的方式。其他工具Gemini, Codex等通过解析命令行输出来估算token和成本。这种方式是实验性的精度取决于工具的输出格式。仪表板使用TUI视图在Agent Deck主界面按$键会弹出一个仪表板。你可以查看今日、本周、本月的总花费按模型、按会话、按分组进行分解。这对于快速了解消费大头非常有用。Web视图Agent Deck还运行一个本地HTTP服务器通常在http://localhost:port/costs提供更丰富的图表和钻取功能。它使用Chart.js渲染支持实时更新SSE。预算告警你可以在配置中设置每日、每周、每月的预算上限。当消耗达到80%时会发出警告达到100%时Agent Deck可以自动停止所有新会话此功能待充分测试。# ~/.agent-deck/config.toml 中的成本配置示例 [costs] retention_days 180 # 数据保留180天 [costs.budgets] daily_limit 20.00 # 每日预算20美元 weekly_limit 100.00 monthly_limit 300.00 [costs.pricing.overrides] # 如果你使用私有或自定义模型可以覆盖定价 my-private-model { input_per_mtok 0.5, output_per_mtok 1.5 }实操建议定期使用agent-deck costs sync命令来同步历史转录文件中的数据。在开始一个大型重构或代码生成任务前先按$看一眼本周剩余预算可以有效避免“账单惊吓”。4.2 Docker沙箱安全地运行不可信代码有时你需要让AI代理运行一些你不完全信任的脚本或命令例如安装未知来源的依赖、执行复杂的系统修改。Docker沙箱功能为此提供了隔离层。工作原理在创建会话时勾选“Run in Docker sandbox”Agent Deck会基于一个轻量级镜像如debian:stable-slim启动一个Docker容器。将你的项目目录以读写模式-v挂载到容器内的一个路径如/workspace。这意味着AI在容器内对代码的修改会直接反映在宿主机上你无需手动复制文件。将必要的认证信息如~/.config/claude/通过只读卷或环境变量注入容器使Claude Code在容器内可以正常认证。在容器内启动Claude Code进程。所有AI执行的命令都被限制在这个容器环境中。关键配置[docker] default_enabled false # 我建议默认关闭仅在需要时开启避免性能开销 mount_ssh true # 将SSH密钥挂载进容器方便git操作 auto_cleanup true # 会话结束时自动删除容器。设为false可用于调试。使用场景测试安装脚本让AI写一个复杂的bootstrap.sh在沙箱中运行它观察效果而不会污染你的主机环境。运行第三方代码如果你让AI基于一个陌生的开源库生成示例在沙箱中运行更安全。调试环境问题如果某个命令在主机上失败可以在纯净的容器环境中复现排除环境干扰。经验之谈性能与便利的权衡Docker沙箱会带来明显的启动延迟和额外的内存开销。对于绝大多数日常编码任务我不推荐默认开启。我的工作流是95%的时间在原生会话中工作获得最佳性能。只有当AI建议运行一个我不确定的、可能修改系统状态或安装大量依赖的命令时我才会用agent-deck try 任务描述命令启动一个一次性沙箱会话。这个命令会创建一个临时的沙箱会话任务完成后自动清理完美平衡了安全与效率。4.3 监视器将外部事件转化为AI行动监视器Watcher功能将Agent Deck从一个被动的管理工具变成了一个能主动响应外部事件的自动化平台。它允许你将GitHub的PR、Slack消息、甚至自定义的Webhook直接“喂”给指定的指挥家会话触发自动化的AI工作流。适配器类型webhook:通用HTTP监听器。任何能发送HTTP POST请求的服务如CI/CD pipeline、监控告警都可以触发它。github:专门处理GitHub的Webhook事件issues,pull_request,push。它强制要求HMAC-SHA256签名验证安全性有保障。ntfy:连接 ntfy.sh 服务。你可以从手机或浏览器向一个私有主题发送推送监视器收到后路由给指挥家。这是实现“手机遥控AI”最简单的方式。slack:通过一个Cloudflare Worker桥接将Slack频道的消息转发到ntfy主题再由ntfy监视器接收。实现了Slack到指挥家的间接集成。设置流程以GitHub为例创建监视器agent-deck watcher create github --name pr-bot --secret $MY_GITHUB_WEBHOOK_SECRET配置路由规则编辑~/.agent-deck/watcher/pr-bot/clients.json指定哪些事件类型如pull_request.opened发送给哪个指挥家或分组。启动监视器agent-deck watcher start pr-bot在GitHub仓库设置Webhook将Payload URL指向http://你的服务器:端口/webhook并设置相同的Secret。测试agent-deck watcher test pr-bot发送一个模拟事件。现在每当有新的PR创建指挥家就会收到一个包含PR详情的结构化事件并可以自动执行代码审查、运行测试、甚至生成评论。路由规则设计模式在clients.json中你可以设计精细的路由逻辑。例如你可以让pull_request.opened事件路由给名为“code-reviewer”的指挥家而issues.labeled事件路由给“triage-bot”。你还可以基于事件内容如PR标题包含“[URGENT]”进行条件路由。这让你能构建一个由多个专精AI组成的响应团队。5. 配置、故障排查与性能调优5.1 多配置文件与分组策略对于需要切换不同工作环境如公司项目 vs 个人项目的用户Agent Deck的配置系统非常灵活。配置文件结构主配置文件是~/.agent-deck/config.toml。但你可以通过-p参数指定不同的“配置文件”profile例如agent-deck -p work。这会加载~/.agent-deck/work/config.toml如果存在否则回退到全局配置。每个配置文件有自己独立的SQLite状态数据库和会话列表。分组管理在TUI中你可以按g键将选中的会话移动到一个分组。分组不仅仅是视觉上的归类它还可以承载配置按组分设Claude配置目录如果你用一个Claude账号处理个人项目用另一个处理工作项目可以为“work”分组指定不同的CLAUDE_CONFIG_DIR。这样该分组下的所有会话都会使用对应账号的认证和设置。环境变量文件通过env_file配置可以为特定分组注入环境变量例如不同的API密钥、代理设置等。# ~/.agent-deck/config.toml 中的分组配置示例 [groups.work] claude.config_dir ~/.claude-work claude.env_file ~/company/.env [groups.experimental] claude.env_file /tmp/experimental.env配置查找优先级从高到低环境变量CLAUDE_CONFIG_DIR指挥家专属配置[conductors.name.claude]分组配置[groups.name.claude]配置文件级配置[profiles.profile.claude]全局配置[claude]默认路径~/.claude这种层级结构让你可以精细地控制每个会话的运行环境。5.2 常见问题与排查清单即使设计得再完善在实际使用中也可能遇到问题。以下是我积累的一些常见问题及其解决方法。问题1会话状态检测不准确一直显示“空闲”或“错误”可能原因ATmux窗格被意外关闭或进程崩溃。排查在终端中运行tmux list-panes -a查看所有窗格。找到对应会话的窗格ID检查其是否存在、进程是否存活。解决在Agent Deck TUI中选中该会话按R(重启) 或先按x(停止) 再按r(启动)。可能原因BAgent Deck用于状态探测的正则表达式与你的AI工具输出不匹配。排查手动切换到那个Tmux窗格在Agent Deck中按Enter看看实际的输出是什么。Claude Code的“等待输入”提示符是否是标准的解决这可能需要调整Agent Deck的探测逻辑。你可以尝试在GitHub Issues中搜索或提交问题。临时方案是忽略状态显示直接进入会话操作。问题2MCP服务器连接失败或未生效可能原因AMCP服务器进程启动失败。排查检查~/.agent-deck/logs/下的日志文件。查看是否有MCP服务器启动报错如依赖未安装、端口冲突、API密钥缺失。解决确保MCP服务器的命令路径和参数正确所需环境变量已在配置中定义。可以尝试在终端手动运行该命令看是否能成功启动。可能原因BSocket池化进程僵死。排查检查是否有孤儿MCP守护进程ps aux | grep mcp-server。解决重启Agent Deckpkill -f agent-deck然后重新启动它会清理并重建池化进程。问题3Git工作树创建失败可能原因A本地有未提交的更改。解决Git不允许在有未提交更改的分支上创建新工作树。请先提交或贮藏stash你的更改。可能原因B目标分支已存在同名工作树。解决使用agent-deck worktree list查看现有工作树并清理不再需要的agent-deck worktree cleanup。可能原因Cworktree-setup.sh脚本执行失败。排查脚本是否有执行权限 (chmod x .agent-deck/worktree-setup.sh)脚本中是否有命令失败脚本开头应加set -e查看Agent Deck的日志。解决简化脚本确保每条命令都成功。注意脚本有60秒超时。问题4指挥家没有自动响应可能原因A指挥家会话本身处于“错误”或“停止”状态。排查在TUI中检查conductor-*会话的状态。按Enter进入其窗格查看是否有报错。解决重启指挥家agent-deck conductor restart name。可能原因B通知事件未被路由。排查检查配置中[notifications] transition_events是否设为true。检查会话是否设置了--no-transition-notify。解决确保通知功能已开启。对于关键会话不要使用--no-transition-notify标志。可能原因C指挥家需要“危险模式”权限。排查进入指挥家会话看它是否在等待用户批准某个操作。解决如3.4节所述在配置中为指挥家启用allow_dangerous_mode并重启指挥家会话。问题5性能问题TUI卡顿、响应慢可能原因A管理的会话数量过多例如超过20个。解决Agent Deck的状态轮询是线性的。考虑将不活跃的会话停止按x或使用分组功能折叠起来。对于长期不用的实验性会话果断删除。可能原因B磁盘I/O过高成本追踪频繁写库或日志量巨大。解决考虑将SQLite数据库放在SSD上。调整日志级别如果支持或定期清理旧日志。可能原因CTmux会话过多tmux命令本身变慢。解决启用Socket隔离 ([tmux].socket_name)将Agent Deck的Tmux负载与你的工作环境分离。5.3 自定义工具集成Agent Deck不仅支持主流AI工具还允许你集成任何自定义的、基于终端的工具。配置示例假设你有一个内部工具叫my-ai-tool它启动后会在终端输出READY提示符并在等待输入时输出INPUT NEEDED:。在config.toml中定义这个工具[[tools]] name my-ai-tool command my-ai-tool args [--mode, interactive] # 关键定义状态检测的正则表达式 status_patterns [ { state running, pattern \\bTHINKING\\b }, { state waiting, pattern INPUT NEEDED: }, { state idle, pattern READY }, ] # 可选定义如何向它发送命令默认是回车后输入 send_keys Enter现在你可以像使用Claude Code一样使用它agent-deck add . -c my-ai-tool。状态检测原理status_patterns列表按顺序匹配Tmux窗格的最后几行输出。第一个匹配到的模式决定状态。确保你的模式能唯一标识状态避免误判。通过这种方式你可以将团队内部开发的、或小众的AI命令行工具无缝接入Agent Deck的统一管理框架享受同样的会话管理、状态监控和分叉能力。这极大地扩展了Agent Deck的生态边界。