agent-semaphore

병렬 코딩 에이전트를 위한 조정 계층입니다. 워크트리는 병합 충돌을 제거하지 않습니다. 통합 시점으로 미룰 뿐입니다. agent-semaphore는 그 간극을 메웁니다: 스코프에 대한 의도를 담은 클레임, 쓰기 시점의 경고, 커밋 전 충돌 예측, 그리고 필수 테스트 게이트를 갖춘 직렬화된 랜딩 큐.

로컬 우선: 데몬 없음, 클라우드 없음, 계정 없음. git 공통 디렉터리의 단일 SQLite 파일이 전체 회합 지점이므로, 저장소의 모든 워크트리는 구조적으로 이를 볼 수 있습니다. 설계상 크로스-벤더입니다 — Claude Code 훅과 MCP, MCP를 통한 Codex CLI, 그 외에는 git pre-commit 훅을 사용합니다.

문제

에이전트가 작성한 풀 리퀘스트는 27.7% 비율로 충돌합니다. 인간의 10–20%와 대조적입니다 (AgenticFlict, 107K+ 에이전트 PR). 공동 활성 쌍에서는 **에이전트 내부 19.8% 대 에이전트 간 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, 동시 실행되는 두 개의 claude -p 에이전트 40회 실행, $17.95):

스크립트 기반 하네스가 구조적으로 생산할 수 없었던 세 가지 발견:

1. 충돌은 클레임이 아니라 따라잡기(catch-up)에 의해 제거된다. 에이전트가 동료의 브랜치로 리베이스한 10회 중 10회가 깨끗하게 병합되었습니다. 충돌이 발생한 모든 조정 실행은 두 에이전트가 모두 정중하게 클레임하고 아무도 리베이스하지 않은 경우였습니다. 클레임은 쓰기를 직렬화할 뿐, 다른 에이전트의 결과물을 건네주지는 않습니다. 이 발견이 "해제는 대기자를 깨우고 브랜치를 명명한다" 기능을 만들었습니다.

2. 훅은 40회 실행 중 단 한 번도 발동하지 않았다. 프롬프트의 프로토콜 덕분에 에이전트는 편집 전에 클레임하고 보유된 스코프에 절대 쓰지 않으므로, 강제는 실제 작동 계층이 아니라 필요하지 않은 보험임이 드러났습니다.

3. 조정은 충돌을 아예 발생하지 않은 작업으로 바꿀 수 있다. 두 번의 실행에서 차단된 에이전트는 보유자, 그 의도와 브랜치를 인용하고 작업을 포기했습니다. ICR 옆의 did_work 열이 없었다면 그 실행은 깨끗한 성공으로 읽혔을 것입니다 — 그래서 그 열이 존재합니다.

의미론적 드리프트(텍스트로는 깨끗하지만 의미상 깨진)는 두 벤치마크 모두에서 모든 권고형 계층을 통과하며, 큐의 필수 게이트에 의해서만 잡힙니다.

연결 방법

• 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 훅 스크립트는 패키지 외부에 벤더링되며 stdlib 전용으로 유지되어야 합니다 — 모든 에이전트의 모든 쓰기에서 실행되므로 의존성이 아닌 지연 시간 예산을 갖습니다. CONTRIBUTING.md를 참조하세요.

라이선스

MIT — LICENSE를 참조하세요.