crosscode-cli

crosscode

多人协作的 Agent 编码。
Agent 时代的实时协同编码。你编辑一个文件，他们的工作副本会在几秒内更新。他们编辑，你的也会更新。无需任何人按下按钮，也无需任何人盯着屏幕。

由 abdullah sultan 构建

_{Node 24 和一个 Git 工作副本。无需部署任何内容。}

将安装提示词粘贴到你已打开的编码 Agent 中，剩下的交给它即可。想自己输入的话：

npm install -g crosscode-cli

兼容你已在使用的 Agent

claude code  ·  codex cli  ·  opencode  ·  cursor

gemini cli   vs code   amp   cline   zed   windsurf   + 任意 MCP 客户端

重要

crosscode-cli 可从 npm 安装，其底层同步引擎（影子引用、三方合并、热文件延迟处理和离线追赶同步）已构建并经过测试。编辑前钩子会注册要运行的命令，守护进程会监测你当前所在分支上的提交或拉取操作。

同步需针对每个工作副本单独启用，并仅涵盖你共享分支上的已跟踪文件。这些文件会通过托管服务中继，而非端到端加密；详情请参阅 docs/privacy.md。 PLAN.md 会追踪已完成的事项。

工作原理

你们都在普通的 Git 工作副本中工作。每个工作副本都会运行一个小型后台守护进程；文件编辑稳定后，它会检测到更改，将该文件发送给同一分支上的其他人，并以相同方式将对方的更改应用到你的工作树中。提交、分支和推送仍由纯 Git 处理。crosscode 只会操作尚未提交的工作树文件，并且绝不会碰你或你的 Agent 在最近几秒内操作过的文件。

只有在确实需要作出决定时才会打断你：你们同时修改了同一文件中的相同行。这时会将合并的三个版本交给你自己的编码 Agent，由 Agent 修复。crosscode 从不评判更改、对风险分类或审查代码。它会在恰当的时机传递正确的信息，再由你的 Agent 完成工作。

没有 Web 应用、没有仪表板，也没有 UI。五条 CLI 命令、四个 MCP 工具和一个技能，安装在两个位置，确保你运行的任意 Agent 都能读取。

功能

### 默认静默 编辑顺利应用后，会直接写入你的工作树，不会弹出提示、显示差异或发送通知。这大约涵盖了 95% 的实际使用场景。	冲突交给你的 Agent 同一行上的冲突会以 ours / theirs / ancestor 的形式发送给你自己的编码 Agent，由它自动合并，无需你发出请求。 文档 →
底层纯用 Git 一个引用 refs/crosscode/shadow 保存最后一次达成一致的状态。HEAD 永远不会移动，且 git log 中不会显示任何内容。 文档 →	一条命令撤销 crosscode 写入的所有内容都可以通过 git checkout refs/crosscode/shadow -- <path> 撤销。 文档 →
原生支持 MCP 标准的 stdio MCP 服务，无需安装编辑器扩展。Claude Code 和 Codex 还会获得一个编辑前钩子。 文档 → · mcp.so →	密钥绝不外传 在捕获前即会排除，即使 Git 跟踪了这些文件：.env* 和 .envrc/.npmrc/.netrc/ .pgpass/.htpasswd/.pypirc/.dockercfg/.git-credentials；.aws/、.ssh/、 .kube/、.gnupg/；id_rsa 等文件；*.pem/*.key/*.p8/*.p12/*.pfx/*.jks/ *.keystore/*.keytab/*.kdbx/*.ovpn/*.gpg/*.asc；路径段中包含 credentials 或 secrets 的任何文件、*service-account*.json、kubeconfig；*.tfvars 和 *.tfstate。这些模式按路径段和扩展名匹配，因此普通源文件仍会同步，完整列表见 SECRET_PATH_PATTERNS。未跟踪的文件绝不会发送。 文档 →
网络中断后仍可运行 守护进程会在离线时继续捕获，并从游标处追赶进度。历史记录保留约 7 天；超过此期限后，副本会从完整内容重新同步。 文档 →	两行完成入门设置 运行 crosscode invite 会打印一个链接。加入页面会检查受邀者是否确实有仓库访问权限， 然后向他们提供 git clone 和 crosscode join 命令。 文档 →

快速开始

将设置任务交给你已经打开的 Agent。把 安装提示词粘贴到 Claude Code、Codex CLI、OpenCode、 Cursor 或任何支持 MCP 的 Agent 中：它会安装 CLI，在检出目录中运行 crosscode start， 并配置自己的 MCP。Codex CLI 的配置使用 TOML 格式，且 start 不会写入该配置，因此 Codex 用户需要手动添加三行配置。参见 MCP 客户端设置。

或者自行运行相同操作：

npm install -g crosscode-cli
cd your-repo
crosscode start

发布的软件包是 crosscode-cli， 其中包含两个二进制文件：crosscode（CLI）和 crosscode-mcp（MCP 服务及 编辑前钩子）。

crosscode start 会完成整个设置流程，并且可以安全地重复运行：它会通过 GitHub 为你登录，将此检出目录关联到一个项目，启动后台守护进程，并安装 MCP 服务、crosscode 技能、写入 AGENTS.md 的对应内容（供读取该文件而非技能的 Agent 使用），以及为你的编码 Agent 安装编辑前钩子。之后请重启 Agent，以便它加载新的 MCP 服务。

登录时会显示一个 URL 和一段简短的确认码，然后等待你操作。你打开 URL，通过 GitHub 登录并输入确认码即可；你的机器上不会有回调服务监听，也无需将任何内容粘贴回终端。在远程 Shell 中，--no-browser 会打印 URL，而不是打开它。

邀请队友加入：

crosscode invite          # prints https://www.getcrosscode.dev/join/7f3a9c2e

他们打开链接，通过 GitHub 登录，页面会提供两行命令供他们粘贴：

git clone [email protected]:acme/app.git && cd app
crosscode join CC-7F3A-9C2E

入门设置就这么简单。之后，双方的检出目录便会保持同步。

另外只有两个命令，仅此而已：

crosscode status     # branch, connected, paused, who else is on this branch
crosscode stop       # stop syncing this checkout

MCP 服务配置

crosscode start 会为你写入此配置。手动添加时，请将其放在检出目录根目录下的 .mcp.json（claude code）、.cursor/mcp.json（cursor）或 .gemini/settings.json（gemini cli）中：

{
  "mcpServers": {
    "crosscode": {
      "command": "crosscode-mcp",
      "args": []
    }
  }
}

该服务通过 stdio 使用 MCP，并根据工作目录识别检出目录，因此启动时请将 cwd 设置为检出目录根目录。codex cli 的配置采用 toml 格式，而 opencode 使用自己的格式；两者都收录在 MCP 客户端和钩子中。

工具

只有四个，不会有第五个。

工具	功能
status	此检出目录的同步状态：分支、连接状态、暂停状态，以及其他协作者正在处理的内容。只读。
conflicts	列出尚未解决的同步冲突，每个冲突都附带 ours/theirs/ancestor 文本，用于进行三方合并。
resolve	使用合并后的文件内容解决一个冲突，将内容写入磁盘并重新发布给团队。
pause	暂停或恢复此检出目录的同步，以便进行变基、二分查找或批量重写。

每个工具的每个响应都会附带所有待处理冲突，无论是否有人请求这些信息：包括每个冲突的摘要、涉及的文件及冲突出现时间；只需调用一次 conflicts 即可获取合并文本。完整目录及输入和输出架构见 MCP 客户端和钩子。

哪些内容会同步，哪些永远不会同步

只有你要同步的文件会离开当前工作区：你在共享分支上编辑的已跟踪文件，但明确禁止同步的文件除外。未跟踪文件会留在原处；你的提交、分支、索引、暂存区和远程仓库都不会受到影响，因此 crosscode 不会向远程仓库推送任何内容。停止运行或移除 crosscode 后，你的仓库仍是普通的 git 仓库，与之前完全一致。

这些文件会通过托管协调服务转发，而非端到端加密，因此拥有生产环境访问权限的人可以读取它们。docs/privacy.md 列出了服务存储的具体内容及其保留时长，docs/security.md 则介绍了威胁模型。

应用规则

一个 git 引用就能完成大部分工作。refs/crosscode/shadow 指向一个提交，其树记录了双方上次达成一致的状态。合并基准、“自上次同步以来我是否编辑过此文件”、撤销操作和内容存储，都由这个引用提供支持；内容存储使用的是 git 自己的对象库。

同步单元是一个文件：{ path, op, baseHash, contentHash, content-or-patch }。没有批次、生命周期，也没有接受或拒绝操作。对于路径 P 的传入更改，其中 L 是你磁盘上的内容，S 是影子版本：

1. L == S 且发送方基于 S 进行构建：直接写入，不提示。
2. 否则，基于发送方的基础版本进行三方合并。合并干净则直接写入，不提示；发生冲突则通知你的 Agent。
3. 只有在对应基础版本的 blob 确实缺失时，才从游标追赶同步并重试。

永远不会合并二进制文件，因此并发编辑二进制文件总会产生冲突。发生冲突的路径会被隔离，不会发布或应用，直到冲突得到解决。

确保同步不会造成干扰的规则：

• 你或你的 Agent 在最近约 10 秒内接触过的文件，绝不写入。
• 变基、合并或二分查找期间绝不同步。请先暂停，然后重新同步。
• 仅同步同一分支。使用不同分支就表示你不想同步。
• 所有操作都可以通过一条命令撤销。

更多信息请参阅架构和协议。

定价

所有内容永久免费。CLI 使用 MIT 许可证，托管服务也不收取任何费用：没有付费计划、等级、席位、使用限制、到期试用，也不会收集付款信息。请参阅 docs/terms.md。

Agent 看到的内容

四个 MCP 工具：status、conflicts、resolve 和 pause，以及一项说明如何使用这些工具、主要是何时不要动它们的技能。Claude Code 从 .claude/skills/crosscode/ 读取该技能；Codex CLI、Cursor、OpenCode 和 Gemini CLI 则从 start 写入 AGENTS.md 的 crosscode 区块中读取相同内容。

每个工具的每次响应都会附带所有待处理冲突，无论是否有人要求该工具提供这些信息。这是有意为之。Agent 只有在被调用时才会查看任何内容，因此在它空闲时出现的冲突原本会一直无人察觉。这样一来，它下次做任何事时都会碰上该冲突。随附的是摘要，因此无关调用不会把整个文件拖进 Agent 的上下文；在 Agent 真正进行合并时，只需调用一次 conflicts 就能获取 ours/theirs/ancestor 文本。Claude Code 和 Codex 还会获得一个在编辑文件前运行的钩子，让这个时机进一步提前：Agent 覆写文件之前就会知道该文件存在冲突，而不是事后才知道。该钩子是 MCP 的额外功能，并非必需；其他所有客户端都只依靠随附的冲突信息。

本项目的目标是：双方的 Agent 都不会在真正出现冲突之前提及 crosscode，而接收方的 Agent 会在无人要求的情况下自行解决冲突。有关告知 Agent 的内容，请参阅 skills/crosscode/SKILL.md。该文件是唯一副本：start 会将其原样安装为技能，并去掉 frontmatter 后将其作为 AGENTS.md 区块；如果三者内容不一致，测试就会失败。

crosscode 不是什么

没有对传入工作进行接受或拒绝的步骤，没有任务、认领或交接，没有隐藏的快照层，没有验证配置、风险分类、AI 审核员、席位、Web 应用或 TUI。我们曾经把这些都做过一遍，也因此学会了适可而止。

开发

pnpm install
pnpm build          # typecheck + bundle
pnpm test           # vitest

目录结构：packages/protocol（传输协议契约）、packages/sync（应用规则、影子引用和三方合并）、packages/git（其运行所依赖的 Git 底层操作）、packages/core（拒绝列表和哈希处理）、apps/daemon（按检出目录同步）、apps/service（托管式协同服务）、apps/cli（五个命令）、apps/mcp-server（四个工具和编辑前钩子）、skills/crosscode（Agent 技能）、apps/docs-site（落地页和本文档）。

想要贡献？请参阅 CONTRIBUTING.md。PLAN.md 是本仓库唯一的计划文档，而 spike/ 则存放了构建系统之外、用于验证合并核心的临时概念验证。

文档：架构 · 协议 · MCP 客户端和钩子 · 接入契约 · 安装提示词 · 安全 · 隐私 · 可观测性 · 条款 · 支持

社区与支持

• 问题： 缺少某项功能，或者遇到了错误？ 提交问题。
• 安全： 请按照 SECURITY.md 的说明私下报告漏洞，切勿在公开问题中报告。
• 隐私： docs/privacy.md 列出了服务能够看到的所有内容。
• 表示支持： 为此仓库点星，关注项目进展。

许可证

crosscode 根据 MIT 许可证 免费开源。

商标

MIT 许可证适用于代码，但不适用于“crosscode”这个名称或 assets/ 中的徽标。你可以分叉、发布，也可以撰文介绍。只是不要把修改后的版本说成是 crosscode 本身。TRADEMARK.md 中有详细说明，未涵盖的事项可联系 [email protected]。