quilt

Quilt

Quilt 是一款命令行工具，可跟踪共享 Git 工作副本中每一行由哪个 Agent 编写，让多个 AI 编码 Agent 可以同时在一个代码库中工作，并且每个 Agent 只提交自己的更改。

它会在工具边界捕获每次编辑，逐行记录内容的编写者，并在提交时还原每个 Agent 自己的更改。Git 始终是事实来源。Quilt 从不调用大模型或启动 Agent，其状态保存在 .quilt/ 辅助目录中，删除该目录不会影响代码库。

npm install -g @quilt-dev/cli
quilt setup     # capture hooks wired; claim enforcement via Claude hooks or MCP

问题所在

你希望 Agent 在同一个工作副本中工作：共用一个 node_modules、一次构建、一个开发服务器和一个持续可用的环境，而不是为每个 Agent 建立一个工作树，各自安装并产生偏差。但在共享工作副本中，即使 Agent 完全在处理不同的事情，普通 Git 也会带来麻烦：第一个 git commit -am 会把其他人尚未提交的文件一并打包，代码生成和锁文件的变动会被算到最后提交者名下，而两个 Agent 偶尔也会改到同一行，导致一方的修改被另一方悄然覆盖。这些情况与 Agent 是否在处理同一项任务无关，只是共享工作副本的默认行为。

Quilt 让共享工作副本变得安全。每个 Agent 只提交自己的行，不多不少：彼此独立的工作从头到尾保持独立，进入提交历史也无需额外操作。当两个 Agent 确实需要相同的代码时，这会变成一次协同交接，而不是悄然丢失更改。即使增加 Agent 数量，这种方式也依然有效。

./examples/fleet.sh 会在一个工作副本中运行七个 Agent。以下是两种结果：

WITHOUT quilt   1 commit for 7 agents — six got "nothing to commit", their
                work swept into the first agent's blob. a7 silently
                overwrote a1's change to getUser. a1's work is gone.

WITH quilt      6 clean commits, one per agent, each exactly its own lines.
                a7's write into a1's claimed function was denied before any
                bytes changed, with a1's stated intent in the denial.

两个 Agent 需要同一个文件时

分别处理不同文件是最简单的情况，真正的考验是发生争用时。认领被拒并不意味着无路可走，拒绝信息会包含持有者声明的意图，以及其租约到期的时间：

$ QUILT_ACTOR=builder-flows quilt claim deals.js flows.js --intent "wire flows to deals"
  ✗ denied  deals.js (held by builder-friction)
      builder-friction is: friction pass: rename + archive flags
      their claim lapses 2026-07-04T22:12:05Z unless renewed
  ✓ claimed flows.js

因此，受阻的 Agent 可以在等待期间处理已获准的文件，在持有者提交并自动释放认领后重新认领，再将自己的更改叠加到已提交的更改之上。最终会有两个干净的提交，文件中保留双方的更改，不会丢失任何内容。./examples/contention.sh 会在实际机制上运行完整流程。

功能

• 共享工作副本。 将人类、Agent 和机器人视为在同一个工作树中编辑的参与者，无需为每个 Agent 创建工作树。
• 逐行归属。 commit --mine 只提交你的行，即使这些行与其他参与者的行位于同一个代码块中也一样。
• 符号级认领。 认领 utils.js#formatPrice，而不是整个文件，这样编辑不同函数的 Agent 就不会发生争用。通过 tree-sitter 支持十种语言；其余语言则支持整文件认领。
• 防止冲突。 如果写入其他 Agent 已认领的代码，Quilt 会在任何字节发生变化之前拒绝操作，并告知持有者声明的意图。
• 感知依赖变更。 认领依赖于其他参与者正在修改的函数的符号时，Quilt 会在认领时发出警告。
• 检测并保留。 如果某个参与者覆盖了另一位参与者尚未提交的行，Quilt 会保存受影响者的版本，确保内容不会悄然丢失。

Quilt 生成的每个提交都是普通的 Git 提交。它信任 Git，绝不会改写 Git；所有状态都保存在本地的 .quilt/ 目录下。无需账户，也无需守护进程。

快速开始

quilt setup      # wire Quilt into the repo (capture hooks + optional MCP tools)
quilt doctor     # confirm it's wired and capture is flowing

就是这样。Agent 会自动命名：每个 Claude Code 会话或 MCP 连接都会获得自己的 ID，因此并行工作的 Agent 无需任何设置就能彼此区分。

4 个终端，一个代码仓库

从 Git 仓库到 4 个 Agent 同时工作，完整流程如下：

cd your-repo
quilt setup          # once, ~5 seconds
claude               # terminal 1
claude               # terminal 2
claude               # terminal 3
claude               # terminal 4

如果要从一个包含多个代码仓库的目录启动会话，请改为在该目录运行 quilt setup：它会配置工作区根目录及其中的每个代码仓库，并将每次编辑记录到文件所属的代码仓库中。

无需其他操作。不需要 QUILT_ACTOR，也不需要为每个终端做任何准备，更无需审批：捕获钩子会自动将每次编辑归属到相应会话。运行 quilt fleet 可实时查看；会话的工作准备就绪后，让它运行 quilt commit --mine -m "..." 即可。每次提交只包含该会话修改的行，即使两个会话修改了同一个文件也一样。（Claude Code 还会提示你为项目启用可选的 quilt MCP 服务；批准后会添加声明／预防工具，但无论是否启用，钩子都会保护你。）

查看 Agent 队列

运行 quilt ui，即可在浏览器中实时查看相同的信息：谁写了什么（按参与者统计每个文件的行数）、活动声明、谁被谁阻塞，以及需要人工处理的事项。仅限本地（127.0.0.1），只读，只需一条命令。

更喜欢用终端？quilt fleet --watch 会以文本形式显示相同信息。

需要跨会话保持稳定的标识时，请设置一个明确的 ID：

QUILT_ACTOR=auth-agent claude    # this agent's edits are attributed to auth-agent

然后，每个 Agent 只提交自己的行：

quilt status                     # who owns what
quilt preview --mine             # exact patch that would be committed
quilt commit --mine -m "fix auth redirect"
quilt provenance HEAD            # actor, session, files, hunks, tree

Quilt 会将来源信息写入 Git 提交本身，因此常规推送和全新克隆后仍会保留。提示词关联信息只保存在本地的 quilt ui 中，不会发布到 Git 历史记录。

在共享 Shell 中，请明确指定提交者（quilt --as auth-agent commit --mine ...）。如果脏工作树显示了其他参与者，Quilt 就会拒绝使用检出范围的会话身份。如果部署提供商要求使用可识别的 Git 邮箱，请设置一次邮箱，同时保持参与者名称各不相同：

quilt config author.email [email protected]

quilt fleet 会显示完整信息：每个参与者、其声明以及所有需要人工处理的事项。完整命令列表请参见 docs/reference.md。

为什么不用 worktree？

为每个 Agent 建立一个 worktree 是常见做法，对于完全独立的任务也确实有效。但每个 worktree 都意味着又要搭建一套环境（另一次安装、另一份构建缓存、另一个开发服务器），而隔离只是把冲突推迟到了合并时。这些成本会随 Agent 数量增加；使用共享检出目录的意义，正是只需搭建一次环境。

	减少运行的 Agent 数量	每个 Agent 一个 worktree	Quilt
并行性	较低，有上限	高	高
每个 Agent 的设置	无	完整安装／构建／环境 × N	无（一个检出目录）
查看彼此正在进行的工作	不适用	否	是
冲突	手动避免	合并时出现	阻止，或实时显现
每个 Agent 干净的提交	不适用	合并后	是

worktree 负责隔离，不负责协调。当多个 Agent 同时处理相同代码时，通常希望他们彼此可见，并在工作过程中相互配合。这正是 Quilt 的作用。两者并不冲突：使用 worktree 处理独立的长期任务，使用 Quilt 让多个 Agent 同时处理同一份代码。

与 Agent 配合使用

quilt setup 会配置捕获钩子和共享 MCP 服务。在 Claude Code 中，钩子允许 Agent 正常使用内置的 Edit 和 Write 工具，同时 Quilt 会记录每项更改的作者，并阻止写入其他 Agent 持有的代码；Agent 无需遵循任何协议，也无需进行任何设置：每个会话都会自动命名，或使用各自的 QUILT_ACTOR 作为稳定 ID。对于其他运行时，也可以通过 MCP 工具实现相同的捕获和阻止功能，每个连接也会以相同方式自动命名。

请参阅 docs/orchestrators.md，了解 Codex、Cursor、Aider，以及每个 Agent 使用独立进程和多个 Agent 在同一进程中运行这两种设置的区别。

文档

• docs/orchestrators.md：运行 Agent 集群。
• docs/reference.md：完整的命令列表、归属机制，以及 .quilt/ 状态目录布局。
• bench/：Quilt 测试所用的场景阶梯，以及在相同指标下启用和不启用 Quilt 的测试结果。

遥测

每天发送一次匿名心跳：quilt 版本、操作系统、Node 主版本号、随机本地 ID。除非你在 quilt setup 时选择加入，否则不会发送其他信息；绝不会发送代码、路径、仓库或 Agent 名称。使用 quilt telemetry off、QUILT_TELEMETRY=0 或 DO_NOT_TRACK=1 可关闭所有遥测。详情请参阅：docs/reference.md。

贡献

欢迎贡献。请参阅 CONTRIBUTING.md。

许可证

MIT