AgentTakt

AgentTakt 是一个 MCP（Model Context Protocol）服务和 TUI 工具。当 AI Agent（例如 Claude Code 这样的“执行器”）通过 MCP 发送任务执行计划时，AgentTakt 会在终端中将其呈现为节点图。你可以使用鼠标和键盘进行审查——移动、添加和删除节点，绘制依赖边，编辑参数——然后批准，编辑后的计划 JSON 就会返回给执行器执行。

Claude Code (Executor)
   │ stdio (MCP)                        your other terminal
   ▼                                           │
[agenttakt serve] ── Unix domain socket ──▶ [agenttakt (TUI)]
 MCP server                               review / edit / approve

功能

• 原生终端体验——无需 Web UI；所有操作都在终端中进行
• 可视化节点编辑器——圆角节点、依赖边和按类型着色，由 Textual 提供支持
• 以鼠标操作为主的编辑方式——拖动节点以移动，通过端口绘制边（橡皮筋效果），点击以选择并删除
• 安全的审批流程——入口处会进行循环检测（保证 DAG）和其他验证，并返回错误，以便 Agent 自行修正

要求

• Python 3.10+（推荐：uv）
• 支持鼠标事件报告的终端模拟器（iTerm2、WezTerm、kitty、Ghostty 等）

安装

如果你有 uv，则无需安装。 uvx agenttakt 会按需获取并运行 AgentTakt，下面的 .mcp.json 示例也会以相同方式启动 MCP 服务。

如果你没有 uv，请安装一次 AgentTakt：

brew install ryoohshima/tap/agenttakt    # Homebrew
pipx install agenttakt                   # pipx

即使使用 uv，安装也便于日常使用——你需要手动启动 TUI，因此直接运行 agenttakt 比每次输入 uvx agenttakt 更方便：

uv tool install agenttakt

Agent 插件

此仓库是一个 Agent Plugins 1.0.0 软件包。在兼容的客户端中，将仓库根目录作为插件目录加载：

AgentTakt/
├── plugin.json     # Portable plugin manifest
├── mcp.json        # MCP server configuration
└── LICENSE

该插件要求 PATH 中包含 uvx，并会从 PyPI 运行已发布的 agenttakt 软件包。uv 缓存存储在由客户端管理的 PLUGIN_DATA 目录中。使用这些工具前，请先单独运行 uvx agenttakt 启动 TUI。 对于 request_approval，请在客户端中配置足够长的工具超时时间（例如 30 分钟）；可移植的 MCP 格式没有 timeout 字段。

开发用的 .mcp.json 是单独的客户端原生配置，用于运行本地检出版本。server.json 提供 MCP Registry 所需的元数据。

快速开始

AgentTakt 由两个进程组成：MCP 服务由 Claude Code 为你启动，TUI 则需要你在单独的终端中自行启动。TUI 用于显示计划，因此请在要求执行器批准之前启动它。

┌─ Terminal A: you ───────────────────┐   ┌─ Terminal B: Claude Code ───────────┐
│ $ uvx agenttakt                     │   │ $ claude                            │
│                                     │   │                                     │
│   ╭─ grep ───╮                      │   │ > Plan the refactor, then ask       │
│   │ pattern  │───╮                  │   │   me to approve it                  │
│   ╰──────────╯   │                  │   │                                     │
│             ╭────▼─────╮            │   │   calls request_approval(plan)      │
│             │   edit   │            │   │   waiting for approval...           │
│             ╰──────────╯            │   │   (blocked until you decide)        │
│                                     │   │                                     │
│   [a] Approve   [r] Reject          │   │                                     │
└─────────────────────────────────────┘   └─────────────────────────────────────┘
             ▲                                                    │
             ╰──────────────── Unix domain socket ────────────────╯

在与 Claude Code 相同的会话中运行 TUI 不起作用。stdio MCP 服务的标准输入和输出专用于协议通信，因此同一进程无法同时驱动全屏终端界面。因此，这两部分会作为独立进程运行，并通过 Unix 域套接字进行通信。

1. 启动 TUI（在独立的终端中）

uvx agenttakt           # if installed: agenttakt (short alias: agt)

空闲界面会显示出来，等待 Executor 提供计划。请保持此终端打开。如果 Executor 调用 request_approval 时没有正在运行的 TUI，该调用会失败并显示：

AgentTakt 编辑器未运行。请让用户在单独的终端中运行“agenttakt”，然后再次调用 request_approval。

启动时，TUI 会在后台检查 PyPI，并在有新版本可用时显示通知。设置 AGENTTAKT_NO_UPDATE_CHECK=1 可禁用检查。

2. 向 Executor 注册 MCP 服务（Claude Code）

将以下内容添加到项目的 .mcp.json 中：

{
  "mcpServers": {
    "agenttakt": {
      "command": "uvx",
      "args": ["agenttakt", "serve"],
      "timeout": 1800000
    }
  }
}

重要

必须显式设置 timeout（毫秒）。 request_approval 工具会阻塞，直到人工完成审核。MCP 进度通知不会延长客户端超时，因此默认超时会在审批完成前中断请求。上面的示例将超时设为 30 分钟（1800000）。这不适用于 show_plan，因为 TUI 收到计划后，该工具会立即返回。

3. 向 Executor 请求审批

当 Executor 调用 MCP 工具 request_approval(plan, summary) 时，计划会以节点图的形式显示在 TUI 中。人工编辑并批准（或拒绝）后，结果会以如下形式返回：

{ "status": "approved", "plan": { "...edited plan..." }, "reason": null }

有关计划 JSON 格式以及每个节点应填写的内容，请参阅 docs/schema.md。

仅显示计划（show_plan）

show_plan(plan, summary) 会在 TUI 中显示计划，但不会等待审批——编辑器收到计划后，该工具会立即返回 {"status": "displayed"}。无论处于何种模式（不只限于计划模式），如果你只想查看 Agent 的规划，都可以使用此工具。计划会以 [view-only] 标题打开；关闭计划不会向 Executor 返回任何内容。

宿主处于计划模式时，Agent 会自然地调用 request_approval，但在计划模式之外，它们不会主动提供计划。要鼓励这种行为，可在项目的 CLAUDE.md（或等效的 Agent 指令文件）中添加类似以下指令：

## AgentTakt

Whenever you formulate a multi-step plan — in any mode, not just plan mode —
submit it with the AgentTakt `show_plan` tool so the human can see it as a
node graph. Use `request_approval` instead when you need the human's approval
before executing.

注意：[view-only] 计划会一直占用编辑器，直到被关闭；之后的 request_approval 会排在它后面等待处理。

调试模式（不使用 MCP 进行试用）

uvx agenttakt open examples/sample_plan.json --out edited.json

从文件加载计划，打开编辑器，并将审批结果写入 --out。

按键绑定

按键	操作
a	批准计划（确认对话框）
r	拒绝计划（需说明原因）
n	添加节点
d / Delete	删除所选节点/边
u / U	撤销 / 重做
方向键	将所选节点移动一个单元格（微调）
Escape	清除选择
p	切换参数面板
?	帮助（操作说明以及如何填写 type / data）
q	退出

鼠标：拖动节点可移动它；从节点的输出端口（●，右侧边缘）拖出，并在另一节点上松开，可创建一条边。

默认情况下，边会绘制为盲文风格的贝塞尔曲线。如果它们在你的环境中显示效果不佳，可使用 --edges orthogonal 切换为圆角正交线。

文档

• 计划 JSON 架构 — 数据模型、节点字段、type / data 的填写方式以及验证规则
• 更新日志 — 各版本的发行说明

许可证

MIT