agtx

一个在终端看板上管理其他编码智能体的AI助手 - 添加任务，按下一键。编排智能体会接手、规划，并将其委派给多个并行运行的编码智能体。等你回来时，更改已准备好合并。

让不同的AI编码智能体在同一个任务上自主协作，实现自动会话切换和上下文感知—— 例如：Gemini → 研究 | Claude → 实现 | Codex → 审查

---

为什么选择agtx？

AI编码工具通常只提供一个智能体、一项任务和一个终端。而agtx则为你提供一个多编码智能体并行工作的看板——每个智能体都在自己的Git工作树中，各自独立地运行在tmux窗口里，通过由编排智能体管理的规范驱动型工作流自主完成任务。

有了编排智能体，你甚至无需亲自管理看板。一个AI智能体会接管任务、分配工作，并确保通过规划、实施、审查及解决冲突来完成任务——让你可以专注于更重要的事情：研究、定义任务以及合并代码变更。

[!TIP] 请查看贡献指南部分，或浏览good first issues，参与其中，成为我们的贡献者⭐️

特性

• 编排智能体：一个专门的AI智能体，通过MCP自主管理你的看板——委派给编码智能体、推进各个阶段、检查合并冲突（实验性功能）
• 多智能体任务生命周期：为每个工作流阶段配置不同的智能体——例如，用Gemini进行研究、用Claude实现、用Codex进行审查——并实现智能体的自动切换
• 并行执行：每个任务都有自己的Git工作树和tmux窗口——你可以同时运行任意数量的智能体
• 规范驱动插件：可接入GSD、Spec-kit、OpenSpec、BMAD、Superpowers——或者只需一个TOML文件即可自定义
• 多项目仪表盘：通过一个统一的TUI管理所有项目的智能体会话
• 兼容工具：Claude Code | Codex | Gemini CLI | OpenCode | Cursor Agent | Copilot

[!NOTE] 如果你只需要一个普通的编码智能体会话管理器，具备完全的人工干预控制，并且不涉及自动的规范驱动技能执行和任务推进编排呢？

那就选择**void插件**，享受完全由人工控制的看板式编码智能体界面吧。

快速开始

# 安装
curl -fsSL https://raw.githubusercontent.com/fynnfluegge/agtx/main/install.sh | bash

# 在任何git仓库中运行
cd your-project && agtx

# 仪表盘模式——管理所有项目
agtx -g

# 编排模式——让AI帮你管理看板
agtx --experimental

[!NOTE] 请将.agtx/添加到项目的.gitignore文件中，以避免提交工作树和本地任务数据。

# 从源码安装
cargo build --release
cp target/release/agtx ~/.local/bin/

要求

• tmux — 智能体会话运行在一个专用的tmux服务器中
• gh（可选） — GitHub命令行工具，用于PR操作

使用方法

键盘快捷键

任务创建向导

按o键创建新任务。向导会引导你完成以下步骤：

1. 标题 — 输入简短的任务名称
2. 插件 — 选择一个工作流插件（如果只有一个选项，则自动跳过）
3. 提示 — 编写详细的任务描述，并插入内联引用

智能体的配置是在项目级别通过config.toml文件进行的（而非针对每个任务）。

任务描述编辑器

在编写任务描述时，你可以内联引用文件、技能和其他任务：

智能体会话功能

• 当任务从“审查”状态转为“运行”状态时，会话会自动恢复
• 整个任务生命周期中都会保留完整的对话上下文
• 可在任务弹出窗口中查看智能体的实时输出
• 自动解决合并冲突：当审查任务处于空闲状态时，agtx会检查其与默认分支之间的合并冲突。若检测到冲突，智能体将被自动指示去解决这些冲突。

配置

配置文件位置：~/.config/agtx/config.toml

工作树基础分支

agtx为每个任务创建一个新的Git工作树。默认情况下，它会按照以下顺序自动检测基础分支：main、master，最后是当前分支。你可以覆盖此设置，强制指定特定的基础分支（例如dev或develop）。

全局工作树的默认设置可以在以下位置进行配置：

# ~/.config/agtx/config.toml
[worktree]
base_branch = "dev"

项目配置

每个项目的设置可以放在项目根目录下的 .agtx/config.toml 文件中：

# 创建新任务工作树时使用的基分支（可选）
base_branch = "dev"

# 从项目根目录复制到每个新工作树的文件列表（用逗号分隔）
# 路径是相对路径，并保留目录结构
copy_files = ".env, .env.local, web/.env.local"

# 工作树创建并完成文件复制后，在工作树内部运行的 Shell 命令
init_script = "scripts/init_worktree.sh"

# 在工作树被移除之前，在工作树内部运行的 Shell 命令
cleanup_script = "scripts/cleanup_worktree.sh"

base_branch 控制新任务工作树是从哪个分支创建的。如果未指定或为空，agtx 会自动检测 main、master 分支，或者回退到当前分支。

这些选项会在从待办事项列表进入研究/规划/执行阶段的过程中运行，即在工作树创建之后、代理会话开始之前。

当一个任务工作树被移除时，cleanup_script 会首先运行（当前工作目录设置为工作树的根目录）。如果该脚本退出状态码非零，则工作树的移除会被中止，并记录错误信息（强制清理流程会在记录错误后继续执行）。脚本会接收到以下环境变量：

• AGTX_PROJECT_PATH
• AGTX_WORKTREE_PATH
• AGTX_TASK_ID
• AGTX_TASK_SLUG
• AGTX_TASK_BRANCH（如果可用）

按阶段的代理配置

默认情况下，所有阶段都使用 default_agent。你可以在全局或项目级别为特定阶段覆盖代理：

# ~/.config/agtx/config.toml
default_agent = "claude"

[agents]
research = "gemini"
planning = "claude"
running = "claude"
review = "codex"

# .agtx/config.toml（项目级覆盖 — 优先于全局配置）
[agents]
running = "codex"

插件

将任何基于规范的框架接入任务生命周期。定义命令、提示和工件——agtx 会处理阶段间的流转、工件轮询、工作树同步、代理切换以及自主执行。

按 P 键可以切换插件。默认附带 7 个内置插件：

代理兼容性

命令以标准格式编写一次，然后根据不同的代理自动转换：

✅ 技能、命令和提示完全支持 · 🟡 仅支持提示，无交互式技能支持 · ❌ 不支持

name = "my-plugin"
description = "我的自定义工作流"

[commands]
research = "/my-plugin:research {task}"
planning = "/my-plugin:plan"
running = "/my-plugin:execute"
review = "/my-plugin:review"

[prompts]
planning = "任务：{task}"

name = "my-plugin"
description = "我的自定义工作流"

# 工作树创建后、代理启动前在工作树内运行的 Shell 命令。
# {agent} 会被替换为代理名称（claude、codex、gemini 等）。
init_script = "npm install --prefix .my-plugin --{agent}"

# 限制支持的代理类型（空或省略表示支持所有代理）。
supported_agents = ["claude", "codex", "gemini", "opencode"]

# 需要从项目根目录复制到每个工作树的额外目录。
# 代理配置目录（.claude、.gemini、.codex、.github/agents、.config/opencode）总是会自动复制。
copy_dirs = [".my-plugin"]

# 从项目根目录复制到每个工作树的单独文件。
# 与 .agtx/config.toml 中的项目级 copy_files 合并。
copy_files = ["PROJECT.md", "REQUIREMENTS.md"]

# 如果为真，则启用通过 `p` 键进行“评审 → 规划”阶段切换。
# 每次循环都会递增阶段计数器（{phase} 占位符）。
# 适用于多里程碑的工作流（例如：规划 → 执行 → 评审 → 下一里程碑）。
cyclic = false

# 表示阶段已完成的工件文件。
# 当检测到这些文件时，任务会显示勾号而不是加载动画。
# 支持单层目录通配符（例如：“specs/*/plan.md”）。
# 使用 {phase} 可实现周期感知路径（替换为当前周期编号）。
# 对于未指定的阶段，则不会显示完成标志。
[artifacts]
research = ".my-plugin/research.md"
planning = ".my-plugin/{phase}/plan.md"
running = ".my-plugin/{phase}/summary.md"
review = ".my-plugin/{phase}/review.md"

# 每个阶段通过 tmux 发送给代理的斜杠命令。
# 以标准格式书写（Claude/Gemini 风格）：/namespace:command
# 自动根据代理类型转换：
#   Claude/Gemini：/my-plugin:plan（保持不变）
#   OpenCode：/my-plugin-plan（冒号变为短横线）
#   Codex：$my-plugin-plan（斜杠变为美元符号，冒号变为短横线）
# 对于未指定的阶段，则回退到代理原生的 agtx 技能调用
# （例如，Claude 使用 /agtx:plan，Codex 使用 $agtx-plan）。
# 设置为空字符串表示跳过该阶段的命令发送。
# 使用 {phase} 可实现周期感知命令（替换为当前周期编号）。
# 使用 {task} 可以将任务描述内联进去。
[commands]
preresearch = "/my-plugin:research {task}"  # 仅在尚未存在研究工件时使用
research = "/my-plugin:discuss {phase}"
planning = "/my-plugin:plan {phase}"
running = "/my-plugin:execute {phase}"
review = "/my-plugin:review {phase}"

# 作为任务内容发送的提示模板。
# {task} = 任务标题 + 描述，{task_id} = 唯一的任务 ID，{phase} = 周期编号。
# 对于未指定的阶段，则不发送提示（由技能或命令自行处理指令）。
[prompts]
research = "任务：{task"

# 在向 tmux 窗格发送提示之前需要等待的文本模式。
# 当某个命令会触发必须先出现的交互式提示时非常有用。
# 每 500 毫秒轮询一次，超时时间为 5 分钟。
[prompt_triggers]
research = "你想构建什么？"

# 在一个阶段完成后，从工作树复制回项目根目录的文件/目录。
# 当检测到阶段工件时自动触发（从加载图标变为勾号）。
# 适用于在不同工作树之间共享研究相关工件（规格、计划等）。
[copy_back]
research = ["PROJECT.md", "REQUIREMENTS.md", ".my-plugin"]

# 自动关闭在提示触发前出现的交互式提示。
# 每条规则在所有检测模式都出现且窗格状态稳定时生效。
# 响应是换行分隔的按键序列（例如，“2\nEnter”会发送“2”然后按 Enter 键）。
[[auto_dismiss]]
detect = ["映射代码库", "跳过映射", "输入选择"]
response = "2\nEnter"

.agtx/plugins/my-plugin/
├── plugin.toml
└── skills/
    ├── agtx-plan/SKILL.md
    ├── agtx-execute/SKILL.md
    └── agtx-review/SKILL.md

工作原理

架构

┌─────────────────────────────────────────────────────────┐
│                      agtx TUI                           │
├─────────────────────────────────────────────────────────┤
│  待办列表  │  规划  │  执行  │  评审  │  完成   │
│  ┌─────┐  │  ┌─────┐   │  ┌─────┐  │  ┌─────┐ │         │
│  │任务1│  │  │任务2│   │  │任务3│  │  │任务4│ │         │
│  └─────┘  │  └─────┘   │  └─────┘  │  └─────┘ │         │
└─────────────────────────────────────────────────────────┘
                    │           │
                    ▼           ▼
┌─────────────────────────────────────────────────────────┐
│                 tmux 服务器 “agtx”                      │
│  ┌────────────────────────────────────────────────────┐ │
│  │ 会话: “my-project”                              │ │
│  │  ┌────────┐  ┌────────┐  ┌────────┐                │ │
│  │  │窗口: │  │窗口: │  │窗口: │                │ │
│  │  │task2   │  │task3   │  │task4   │                │ │
│  │  │(Claude)│  │(Claude)│  │(Claude)│                │ │
│  │  └────────┘  └────────┘  └────────┘                │ │
│  └────────────────────────────────────────────────────┘ │
│  ┌────────────────────────────────────────────────────┐ │
│  │ 会话: “other-project”                           │ │
│  │  ┌───────────────────┐                             │ │
│  │  │ 窗口:           │                             │ │
│  │  │ some_other_task   │                             │ │
│  │  └───────────────────┘                             │ │
│  └────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
                    │           │
                    ▼           ▼
            ┌───────────────────────────┐
            │   Git 工作树           │
            │  .agtx/worktrees/task2/   │
            │  .agtx/worktrees/task3/   │
            │  .agtx/worktrees/task4/   │
            └───────────────────────────┘

Tmux 结构

• 服务器：所有会话都在名为 agtx 的专用 tmux 服务器上运行。
• 会话：每个项目都有自己的 tmux 会话（以项目命名）。
• 窗口：每个任务在项目的会话中都有自己的窗口。

# 列出所有会话
tmux -L agtx list-sessions

# 列出所有会话中的窗口
tmux -L agtx list-windows -a

# 连接到 agtx 服务器
tmux -L agtx attach

数据存储

• 数据库：~/Library/Application Support/agtx/（macOS）或 ~/.local/share/agtx/（Linux）。
• 配置文件：~/.config/agtx/config.toml。
• 工作树：每个项目中的 .agtx/worktrees/。
• Tmux：专用服务器 agtx 及其按项目划分的会话。

协调代理（实验性）

按下 O 键后即可离开。回来时，更改已准备好合并。

协调代理是一个 AI 代理，能够 驱动其他 AI 代理完成任务。你只需将任务分类到规划或执行阶段——协调代理会接管剩余流程，推动每个任务依次经过各个阶段，直到进入评审阶段，供你合并。

agtx --experimental   # 然后按下 O 键

它的工作方式：

• 监控规划和执行阶段的任务。
• 在各阶段完成后自动推进任务（规划 → 执行 → 评审）。
• 尊重插件的阶段规则——在每次转换前检查 allowed_actions。
• 检测卡住的任务（超过 1 分钟未产生阶段工件）并读取代理窗格内容以诊断原因。
• 对卡住的代理进行提醒，自动回答 CLI 提示，或在需要人工干预时向你汇报具体原因。

你负责分类，它负责执行。 将任务从待办列表移至规划或执行阶段——剩下的就由协调代理来完成。最终是否合并，由你决定。

MCP 集成

编排器通过 模型上下文协议 (MCP) 与 agtx 进行通信。agtx 自带一个内置的 MCP 服务器 (agtx serve)，它通过标准输入输出以 JSON-RPC 的形式将看板展示为一组工具。

┌─────────────-┐     MCP (stdio)     ┌──────────────┐     SQLite     ┌─────┐
│ 编排器       │ ←─────────────────→ │  MCP 服务器  │ ←────────────→ │ DB  │
│ (Claude Code)│                     │ (agtx serve) │                └──┬──┘
└──────┬───────┘                     └──────────────┘                   │
       │  空闲时推送通知                                  │
┌──────┴───────┐                                                        │
│   TUI (agtx) │ ←───────────────────────────────────────────────────--─┘
└──────────────┘

编排器可用的 MCP 工具：

工作流程：

1. 当你按下 O 键时，TUI 会通过 claude mcp add-json --scope local 将 MCP 服务器注册到编排器代理。
2. 编排器会在空闲时接收到推送到其 tmux 窗格的阶段完成通知。
3. 它会调用 get_task 检查 allowed_actions，然后调用 move_task 来推进任务。
4. TUI 处理状态转换请求，执行所有副作用（切换代理、部署技能、发送提示），并更新数据库。
5. 如果某个任务在没有产生阶段成果的情况下空闲超过 1 分钟，编排器就会收到通知——它会使用 read_pane_content 读取窗格内容，然后要么通过 send_to_task 提醒代理，要么调用带有 escalate_to_user 参数的 move_task 来将其标记为你需要关注的任务。
6. 被升级的任务会在看板上显示一个 ⚠ 标记；打开任务弹出窗口即可查看原因并取消标记。
7. 当编排器停止时，MCP 注册会被清理。

贡献

我们欢迎各种贡献！无论是修复 bug、开发新插件、集成新代理，还是改进文档。

完整的指南请参阅 CONTRIBUTING.md。以下是简要说明：

# 克隆并创建分支
git clone https://github.com/<you>/agtx && cd agtx

# 构建并测试
cargo build && cargo test --features test-mocks

适合初学者的贡献

不知道从哪里开始？这里有一些建议：

• 编写插件 — 只需要一个 plugin.toml 文件即可。完整的参考请见 创建插件。
• 添加新代理 — 集成你喜欢的 AI 编程 CLI。关于代理的结构，请参阅 架构文档。
• 改进文档 — 发现了不清楚的地方吗？帮助他人，把它改得更清晰吧。
• 报告 bug — 在 GitHub 问题页面 上提交一个问题。提供复现步骤会非常有帮助。
• 浏览开放问题 — 查看带有 good first issue 标签的问题，这些都是适合初学者的任务。

开发

完整的架构文档和开发模式请参阅 CLAUDE.md。

# 构建
cargo build

# 运行测试（包含基于模拟的测试）
cargo test --features test-mocks

# 构建发布版本
cargo build --release

agtx 快速上手指南

agtx 是一个运行在终端的看板工具，旨在协调多个 AI 编程代理（Agent）并行工作。它通过一个“编排器（Orchestrator）”自动分配任务、规划流程并委托给不同的 AI（如 Gemini 负责调研、Claude 负责实现、Codex 负责审查），让多个 AI 在独立的 Git Worktree 和 tmux 窗口中自主协作。

环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统: Linux 或 macOS (Windows 需通过 WSL2)
• Git: 必须安装，用于管理多任务分支。
• tmux: 核心依赖。agtx 依赖 tmux 服务器来隔离和运行每个 AI 代理的会话。
• AI 客户端: 至少安装一种支持的 AI CLI 工具，例如：
  • Claude Code
  • Gemini CLI
  • OpenAI Codex
  • Cursor Agent
  • GitHub Copilot CLI 等
• gh (可选): GitHub CLI，用于拉取请求（PR）相关操作。

安装步骤

方式一：一键脚本安装（推荐）

使用官方提供的安装脚本快速部署：

curl -fsSL https://raw.githubusercontent.com/fynnfluegge/agtx/main/install.sh | bash

方式二：源码编译安装

如果您已安装 Rust 工具链，可以通过源码构建：

cargo build --release
cp target/release/agtx ~/.local/bin/

提示: 建议在项目的 .gitignore 文件中添加 .agtx/，以避免提交本地任务数据和临时 worktree 文件。

基本使用

1. 启动 agtx

进入任意 Git 项目目录并运行：

cd your-project && agtx

2. 核心模式

agtx 提供两种主要运行模式：

• 看板管理模式 (默认): 手动管理任务流转，完全由人类控制。

  agtx
  

• 全局仪表盘模式: 在一个界面管理所有项目的代理会话。

  agtx -g
  

• 自动编排模式 (实验性): 启用 AI 编排器，让 AI 自动接管看板，进行任务规划、分配和冲突解决。

  agtx --experimental
  

3. 创建与执行任务

启动后，您将看到基于终端的看板界面（通常包含 Backlog, Research, Running, Review 等列）。

1. 新建任务: 按下 o 键。
   • 输入任务标题。
   • 选择工作流插件（如 agtx, gsd, spec-kit 等，若只有一个则自动跳过）。
   • 编写详细任务描述（支持使用 # 引用文件，/ 引用技能，! 引用其他任务）。
2. 推进任务:
   • 使用 j/k 或 ↑/↓ 选择任务。
   • 使用 m 将任务移动到下一个阶段（例如从 Backlog 移到 Research）。
   • 一旦任务进入 Running 阶段，agtx 会自动创建一个新的 Git Worktree 和 tmux 窗口，并启动配置的 AI 代理开始工作。
3. 查看进度:
   • 按下 ↩ (Enter) 键打开任务，实时查看 AI 在 tmux 中的输出。
   • 按下 d 查看当前任务的 Git 差异。

4. 常用快捷键速查

5. 配置多代理协作

您可以通过配置文件让不同阶段的任務使用不同的 AI。

全局配置 (~/.config/agtx/config.toml):

# 默认代理
default_agent = "claude"

# 为特定阶段指定代理
[agents]
research = "gemini"   # 调研阶段使用 Gemini
planning = "claude"   # 规划阶段使用 Claude
running = "claude"    # 执行阶段使用 Claude
review = "codex"      # 审查阶段使用 Codex

项目级配置 (.agtx/config.toml，优先级高于全局配置):

# 覆盖当前项目的执行代理
[agents]
running = "codex"

配置完成后，当任务在不同阶段流转时，agtx 会自动切换到对应的 AI 代理进行处理。