agent-semaphore

并行编码代理的协调层。 工作树并不能消除合并冲突——它们只是将冲突推迟到集成阶段。agent-semaphore 填补了这一空白：带有意图声明的范围声明、写入时的即时警告、提交前的冲突预测，以及带有强制测试门的序列化落地队列。

本地优先：无需守护进程、无需云服务、无需账户。Git 公共目录中的单个 SQLite 文件是整个会合点，因此仓库的每个工作树都能自然看到它。跨供应商设计——Claude Code 钩子和 MCP、Codex CLI 通过 MCP，其他所有人通过 git pre-commit 钩子。

问题

代理编写的拉取请求冲突率为 27.7%——而人类为 10–20%（AgenticFlict，107K+ 代理 PR）。在协同活动对上，分裂为 19.8% 代理内 vs 41.7% 代理间：代理之间没有横向感知，每个提供协调的产品只协调自己的代理。一个解决不当的冲突带来的错误密度高达普通代码的 ~26 倍（EMSE 2020）——昂贵的不是冲突本身，而是悄无声息的错误解决。

隔离问题已解决并商品化（每个代理一个工作树或容器——每个产品都提供）。预测和集成则没有：没有人在活跃的工作树之间运行 git merge-tree，独立的本地合并队列实际上不存在。

功能

硬保证只存在于一个地方：落地路径。钩子和 pre-commit 是协作式准入控制和遥测，而非安全边界——ASEM_HOOK_OFF=1 和 ASEM_OVERRIDE=1 是文档化的、被审计的逃生舱口。这一点事先说明，因为一个假装是沙箱的协调层比没有更糟糕。

快速开始

uv tool install git+https://github.com/alwh1te/agent-semaphore     # asem on PATH
# or, from a clone: uv tool install -e .

cd <your repo>
curl -O https://raw.githubusercontent.com/alwh1te/agent-semaphore/main/.agent-semaphore.toml.example
mv .agent-semaphore.toml.example .agent-semaphore.toml   # set the gate command, hot classes, target branch
asem init                                   # state in .git/agent-semaphore/
asem install --git-hooks                    # Claude Code hooks + .mcp.json + git pre-commit
asem doctor                                 # PASS checklist

asem claim src/api/ -i "refactor auth parsing" --ttl 30m   # exit 3 = held by someone else
asem check src/api/routes.py                               # who holds it, and what for
asem radar                                                 # conflicts between worktrees, before any commit
asem land feature-branch                                   # rebase -> gate -> CAS into the staging branch
asem notices                                               # messages addressed to you
asem status | asem queue status | asem doctor

退出码是契约的一部分：0 正常/空闲，3 被持有/冲突/退回，2 用法错误，1 内部错误——脚本可以区分“协调说不行”和“工具坏了”。

测量结果

这个领域没有人测量过声明是否真的减少了冲突，因此该仓库自带两个基准测试。

脚本化（docs/benchmark.md，60 次运行，确定性代理，合规性 = 1 由构造保证）：集成冲突 60% → 0%，人工干预 9 → 0。

实时代理（docs/bench-llm.md，40 次运行两个并发 claude -p 代理，$17.95）：

脚本化测试框架在结构上无法产生的三个发现：

1. 冲突是通过追赶消除的，而不是通过声明。 代理变基到其同伴分支的 10 次运行中，10 次都干净合并；每个冲突的协调运行都是两个代理都礼貌地声明但都没有变基的情况。声明序列化了写入——它不会把另一个代理的结果交给你。这个发现催生了“释放唤醒等待者并指明分支”的功能。

2. 钩子在 40 次运行中从未触发过一次。 由于提示中包含了协议，代理在编辑前声明，并且从不写入被持有的范围，因此执行被证明是不需要的保险——而不是工作层。

3. 协调可以将冲突转化为从未发生的工作。 在两次运行中，被阻塞的代理引用了持有者、其意图和其分支，并放弃了其任务。如果没有 did_work 列紧挨着 ICR，这些运行会被解读为干净的成功——这就是为什么该列存在。

语义漂移（文本上干净，语义上损坏）在两个基准测试的所有建议层中都存在，并且仅被队列的强制测试门捕获。

如何接入

• Claude Code — asem install 写入项目 .claude/settings.json（PreToolUse + PostToolUse），将 Bash(asem:*) 和 mcp__semaphore__* 添加到允许列表，并在 .mcp.json 中注册 MCP 服务器。提交的接线是主机可移植的（$HOME 和裸 asem），因此跨机器共享的仓库不会携带一台主机的路径。

• MCP（asem mcp，服务器键 semaphore）— claim、release、check、status、extend、report_intent、radar、enqueue_land、land_status。每个响应都会排空待处理的通知，因此代理无需轮询即可了解窃取、退回和移动的目标。

• Codex CLI — 通过 ~/.codex/config.toml 使用相同的 MCP 服务器，外加一个用于 AGENTS.md 的协议片段。无头 Codex 会静默取消 MCP 调用，除非工具已预先批准；docs/integration.md 中有可用的配置。

• 其他任何东西 — asem install --git-hooks 将 pre-commit 门放入共享钩子目录（它会链式加载之前存在的任何钩子）。

文档

• docs/00-research.md — 此设计所基于的研究档案：测量到的问题、工具格局、值得借鉴的经典先例、2024–26 年的论文，以及市场中三个已确认的空白。

• docs/adr/ADR-001-architecture.md — 架构，以及风险登记册和来自盲审的十次对抗性攻击（其中八次改变了设计）。

• docs/adr/ADR-002-stack-and-state.md — 技术栈、命名以及状态存储位置。

• docs/benchmark.md / docs/bench-llm.md — 两个基准测试：方法、结果以及明确的局限性。

• docs/integration.md — 安装以及各处的接线。

状态

v1 已实现并经过自用测试：该仓库通过它协调自己的代理。150 个测试，CI 中的 p95 钩子延迟门，两个基准测试均可从仓库重现。

已知限制，明确说明：从暂存分支提升到 main 仍然是手动的且无门控（asem promote 是下一个功能）；队列从不推送；没有符号级范围界定，没有超出测试门的语义冲突检测，没有 LLM 自动解决（已发布的正确率上限约为 55–60%，不足以无人值守运行）；多主机是 v2 设计，尽管模式已经包含 host 列。

开发

uv run pytest -q                          # 150 tests
uv run ruff check . && uv run ruff format --check .
uv run python bench/hook_latency.py 200   # hook latency gate (p95 < 100 ms)
uv run python bench/runner.py --seeds 3 && uv run python bench/report.py

PreToolUse 钩子脚本在包外销售，并且必须保持仅使用标准库——它在每个代理的每次写入时运行，因此它有延迟预算而不是依赖项。参见 CONTRIBUTING.md。

许可证

MIT — 参见 LICENSE。