agentclaim

여러 에이전트. 하나의 작업 트리. Git은 당신을 구하지 못합니다.

병렬 AI 코딩 에이전트를 위한 파일 소유권 — 서로를 조용히 덮어쓰지 않도록.

npm i -g agentclaim && agentclaim init

문제

두 개, 세 개, 다섯 개의 코딩 에이전트를 동시에 실행합니다. 그들은 하나의 작업 트리를 공유합니다.

Git은 나중에 병합하는 별도의 클론에서 작업하는 사람들을 위해 만들어졌습니다. 같은 체크아웃에서 두 명의 작성자가 동시에 편집하는 상황을 처리할 방법이 없습니다. 충돌 표시도, 경고도, 병합도 없습니다 — 두 번째 쓰기가 그냥 이기고 첫 번째 것은 사라집니다.

다음은 한 저장소에서 어느 오후에 발생한 세 가지 실제 사고입니다. 세 가지 모두 프로덕션에 배포되었습니다. 그중 어느 것도 단 하나의 오류 메시지를 생성하지 않았습니다.

1. 스테이징 경쟁

git add는 파일을 그 순간의 상태 그대로 스냅샷합니다.

 session A            session B
 ─────────            ─────────
                      git add i18n.js Money.jsx   ← snapshots i18n.js v1
 write i18n.js v2
                      git commit                  ← commit contains i18n.js v1

커밋은 이전 i18n.js와 함께 새 Money.jsx를 배포했습니다. 화면은 프로덕션에서 원시 번역 키를 렌더링했습니다. Git은 성공을 보고했습니다. 후속 수정 커밋은 정확히 같은 경쟁에 빠졌습니다.

2. 파괴적 복원

git checkout HEAD -- i18n.js api.demo.js   # session A tidies its tree
git commit -a                              # session B, two seconds later

세션 B의 작업이 디스크에서 되돌려진 후 커밋되어 사라졌습니다. 조용히.

3. 거짓말한 게이트

배포 스크립트에는 더티 트리 가드가 있었습니다. 그것은 커밋 시점의 경쟁이 아니라 배포 시점의 트리를 확인했습니다. 게이트는 초록불을 켰고, 커밋은 잘못되었으며, 배포는 충실히 잘못된 커밋을 게시했습니다.

Related MCP server: asynkor

해결책

쓰기는 더 똑똑해집니다. 커밋은 엄격하게 유지됩니다.

모든 두 번째 작성자를 차단하는 것은 정지 신호일 뿐, 해결책이 아닙니다 — 그리고 사람들이 해야 할 작업을 차단하는 도구는 꺼지게 마련입니다. 한 파일의 두 에이전트는 같은 영역을 건드릴 때만 실제 충돌입니다.

그래서 agentclaim은 "이 파일을 누가 소유하는가?"를 묻지 않습니다. **"내가 마지막으로 본 이후 무엇이 바뀌었는가?"**를 묻습니다 — 다른 에이전트의 편집과 자신의 편집을 구분하는 유일한 질문입니다. 다른 영역이면 두 에이전트 모두 작업합니다. 같은 줄이면 하나가 멈춥니다.

agentclaim: src/checkout.ts is also being edited by another agent — your edits do not overlap theirs.
  their lines: 12-19
  your lines:  84-91
Both edits are kept. You may not commit this file until they are done.

전체 파일 Write도 충돌이 아닙니다 — git merge-file을 사용해 다른 에이전트의 작업과 3-way 병합되므로, 두 편집 모두 반영됩니다:

agentclaim: src/checkout.ts was merged, not overwritten.
Another agent had edited this file; your write has been combined with
their changes. Re-read the file before continuing — it now contains both.

겹치는 줄도 정지 신호가 아닙니다

정밀 편집은 수술적입니다: 앵커 텍스트가 현재 파일에 여전히 존재하는 경우에만 적용됩니다. 그 하나의 속성이 모든 작업을 수행합니다.

• 앵커이 여전히 존재 → 교체해도 다른 에이전트의 편집은 유지됩니다. 그들의 변경 사항은 정의상 텍스트의 다른 곳에 있기 때문입니다.

• 앵커이 사라짐 → 도구가 스스로 거부하고 에이전트는 다시 읽습니다.

어느 쪽이든 결과는 이미 올바르므로, 차단은 왕복 비용만 들이고 얻는 것은 없습니다. agentclaim은 대신 맥락을 추가합니다:

agentclaim: heads up — another agent just changed the same lines of src/checkout.ts.
  their lines: 12-19
  your lines:  14-16

Your edit still applies cleanly on top of their version. This is what
they changed, in case it affects what you were about to do:
  @@ line 12-19 @@
  -  const total = items.length
  +  const total = items.reduce((n, i) => n + i.qty, 0)

Nothing is blocked. You may not commit this file until they are done.

실제로 에이전트를 멈추는 것

네 가지, 그리고 오직 이것들만:

편집 경로에서는 아무것도 멈추지 않습니다. 그것이 핵심입니다: 평범한 작업을 하는 에이전트를 방해하는 도구는 꺼지게 되고, 그러면 아무것도 보호하지 못합니다.

커밋은 엄격한 부분입니다

두 개의 활성 세션이 파일을 건드린 후에는, 어느 쪽도 스테이징하거나 커밋할 수 없습니다 — 그것이 정확히 한 에이전트가 다른 에이전트의 반쯤 된 작업을 배포하는 방식이기 때문입니다. 위의 사건 #1.

그 보호는 출구가 없으면 교착 상태가 되므로, 세 가지 출구가 있습니다:

세션이 종료되거나 충돌하면 보유한 모든 것을 해제하므로, 트리는 영원히 잠기지 않습니다.

서버 없음. 데몬 없음. 의존성 없음. 저장소는 .git/ 안의 디렉토리입니다.

빠른 시작

npm i -g agentclaim
cd your-repo
agentclaim init

전역 설치를 선호하지 않나요? npx agentclaim init도 작동합니다 — 먼저 ~/.agentclaim/lib에 자신을 복사합니다. 훅은 내일도 존재할 경로를 가리켜야 하기 때문입니다.

그게 전부입니다. init는 Claude Code 훅을 연결하고 git pre-commit 훅을 설치합니다(기존 훅이 있으면 연결). 언제든 확인하세요:

$ agentclaim status
SESSION          FILES  AGE   LAST SEEN
● money screen       3  6m    2s
  ai visibility      2  22m   14s

FILE                    HELD BY        AGE
web/src/Money.jsx       (you)          6m
web/src/i18n.jsx        (you)          6m
web/src/api.demo.js     ai visibility  22m

세션에 읽기 쉬운 이름을 지정하여 다른 에이전트의 오류 메시지가 의미를 갖게 하세요:

agentclaim label "money screen"

init이 당신의 머신에서 변경하는 것

세 가지. 그 외에는 없습니다.

네트워크 호출 없음. 텔레메트리 없음. 백그라운드 프로세스 없음. 당신의 코드 한 줄도 건드리지 않으며, git status에 새 항목이 나타나지 않습니다.

혼자일 때는 아무것도 하지 않습니다

트리에서 유일한 활성 세션이라면, 모든 게이트는 허용으로 단락됩니다. 클레임이 강제되지 않고, 명령이 검사되지 않으며, 우회할 것도 없습니다.

이것은 의도적입니다. 통과할 수 없는 게이트는 게이트가 없는 것보다 나쁩니다. 사람들이 그것을 비활성화하는 법을 배우고 그러면 아무것도 보호하지 못하기 때문입니다. agentclaim은 그것이 존재하는 정확한 상황에서만 이빨을 갖습니다.

$ agentclaim doctor
...
1 live session(s) · 3 claim(s) · TTL 30m · mode block
single session -> gates inactive (no-op)

네 개의 게이트

게이트 3은 다른 어떤 것도 잡지 못하는 것입니다. 커밋의 모든 경로를 git show <sha>:<path>로 다시 읽고 디스크의 파일과 바이트 단위로 비교합니다:

agentclaim: ⚠ commit 045d1f7 does NOT match what is on disk:
  web/src/api.demo.js

This is the classic `git add` snapshot race: another session rewrote these
files after you staged them, so the commit captured stale content.
DO NOT DEPLOY. Fix it with:
  git add web/src/api.demo.js && git commit --amend --no-edit

다른 세션이 보유한 파일만 보고하므로, 일반적인 부분 스테이징(git add x, x 계속 편집, 커밋)은 오탐을 일으키지 않습니다.

어떤 에이전트와도 작동

세 가지 통합 계층, 강한 것부터. 해당하는 만큼 사용하세요.

Claude Code — 훅 (가장 강함)

agentclaim init            # project-level  (.claude/settings.json)
agentclaim init --global   # every repo     (~/.claude/settings.json)

게이트는 쓰기나 명령 전에 실행됩니다. 에이전트는 거부를 피드백으로 받고 스스로 다른 파일을 선택합니다.

Cursor · Windsurf · Codex · Zed · Cline · MCP를 지원하는 모든 것

agentclaim은 MCP 서버를 제공하므로, MCP를 말하는 어떤 에이전트든 같은 소유권 프로토콜에 참여할 수 있습니다:

{
  "mcpServers": {
    "agentclaim": {
      "command": "agentclaim",
      "args": ["mcp"],
      "env": { "AGENTCLAIM_SESSION": "cursor-1", "AGENTCLAIM_AGENT": "cursor" }
    }
  }
}

노출된 도구: agentclaim_status, agentclaim_claim, agentclaim_release, agentclaim_check, agentclaim_verify_commit. 설명은 모델에게 언제 호출할지 알려줍니다.

그 외 모든 것 — git 훅

agentclaim init는 pre-commit 훅을 설치하므로, aider, 일반 git commit, IDE, 또는 셸 스크립트 모두 같은 검사를 받습니다. 구성할 것이 없습니다.

배포 스크립트와 CI를 위해, 종료 코드 게이트를 사용하세요:

agentclaim check --staged --quiet || exit 1   # anyone else holding staged files?
agentclaim verify HEAD                        # did the commit capture disk?

명령

agentclaim init [--global]    wire up the hooks (Claude Code + git pre-commit)
agentclaim status             who holds what
agentclaim who <path>         owner of a single file
agentclaim claim <path...>    claim files            [--note "..."]
agentclaim release <path...>  "I am done here"       [--all] [--force to take over]
agentclaim check <path...>    gate for scripts, exit 0/1  [--staged] [--quiet]
agentclaim verify [rev]       compare commit content against disk  [--all]
agentclaim label "<name>"     give this session a readable name
agentclaim gc                 collect stale claims
agentclaim doctor             diagnose the installation
agentclaim uninstall          remove the hooks
agentclaim mcp                run as an MCP server

구성

저장소 루트의 선택적 .agentclaim.json:

{
  "ttlMinutes": 30,
  "touchTtlMinutes": 10,
  "mode": "block",
  "ignore": ["node_modules/**", "dist/**", "*.lock", "package-lock.json"]
}

• ttlMinutes — 이 시간 동안 활동이 없는 세션은 사라진 것으로 간주되고 그 클레임을 인수할 수 있습니다. 모든 훅 호출이 하트비트를 새로고침하므로, 활성 세션은 만료되지 않습니다.

• touchTtlMinutes — 세션이 마지막 편집 후 다른 사람이 파일을 커밋하는 것을 차단하는 시간. 의도적으로 ttlMinutes보다 짧습니다: 여전히 살아 있는 것은 여전히 이 파일에서 작업 중인 것과 다르며, 둘을 혼동하는 것이 보호를 교착으로 바꾸는 것입니다.

• mode — block(기본), warn(보고하지만 허용), off.

• ignore — 절대 클레임하지 않음. 생성된 파일을 여기에 두세요; 잠금 파일과 빌드 출력이 클레임되면 게이트가 계속 발동하고 사람들이 우회하기 시작합니다.

작동 방식

.git/agentclaim/
  sessions/<id>.json   { sid, label, pid, started, seen, wt }
  claims/<hash>.json   { path, wt, sid, at, touchers }
  snap/<sid>/<hash>    what that session last saw on disk
  pending/<sid>/<hash> a merge computed before a write, applied right after it
  pass.json            short-lived identity token for the git hook

• 저장 위치는 git rev-parse --git-common-dir이므로, 저장소의 모든 워크트리가 하나의 레지스트리를 공유합니다.

• 클레임 키에는 워크트리 루트가 포함됩니다. 두 워크트리의 동일한 상대 경로는 디스크상에서 서로 다른 두 파일이기 때문입니다. 별도의 워크트리는 서로를 절대 차단하지 않습니다 — 워크트리는 이 문제에 대한 합법적인 해결책이지, 처벌 대상이 아닙니다.

• 원자성은 open(..., 'wx') — O_EXCL입니다. 동시에 두 개의 클레임이 발생하면 하나만 승리하고, 경쟁 조건은 없습니다.

• 활성 상태는 TTL 기반입니다. 훅은 모든 도구 호출 시 실행되므로 seen은 수 초 이내에 최신 상태로 유지됩니다. 충돌한 에이전트의 클레임은 회수 가능하며 저장소를 결코 막지 않습니다.

• 영역 추론은 git diff --no-index -U0을 사용하여 세션의 스냅샷을 디스크의 파일과 비교하고, git merge-file로 병합합니다. 모든 것은 이미 신뢰하는 git 자체의 의미론이며, 추가 의존성은 없습니다.

• 병합은 우리가 적용하며, 주입되지 않습니다. 훅 출력 스키마에는 updatedInput 필드가 있지만, 호출을 자동 승인하지 않고도 적용된다는 것을 검증할 수 있는 것은 없으며, 그곳에서 잘못된 가정을 하면 다른 에이전트의 작업이 조용히 유실됩니다. 따라서 병합은 도구 실행 직후 우리가 제어하는 메커니즘만으로 스태시되어 기록됩니다.

• 도구 호출당 비용은 수명이 짧은 node 프로세스 하나입니다: 단독 실행 시 약 45ms, 게이트가 실제로 추론해야 할 때 약 83ms (200개 파일 저장소에서 측정). node 시작이 지배적입니다 — 읽기 후 스냅샷을 찍는 데 약 1ms가 추가됩니다.

• 유지 관리할 것이 없습니다. gc는 세션 시작마다 실행되어 사라진 세션의 클레임, 스냅샷, 대기 중인 병합을 제거하므로 .git/에 누적되는 것이 없습니다.

제한 사항

잘못 신뢰하는 가드는 가드가 없는 것보다 나쁘기 때문에, 명확히 밝힙니다.

• git commit --no-verify는 git 훅 레이어를 건너뜁니다. Claude Code 레이어가 여전히 이를 잡아냅니다.

• 훅이나 MCP가 없는 에이전트는 쓰는 동안 보이지 않습니다. 커밋 시점에 잡아냅니다.

• 명령 파싱은 의도적으로 완전한 셸 파서가 아닙니다. git을 건드리는 eval / sh -c / 백틱의 경우, agentclaim은 다른 세션이 활성 상태일 때만 거부합니다.

• 영역 공존은 세션이 마지막으로 본 것을 알아야 하므로, 에이전트가 도구를 통해 읽거나 쓴 파일에만 적용됩니다. 다른 경로(셸 sed, 외부 편집기)로 변경된 파일은 해당 추론에 보이지 않습니다.

• agentclaim은 의미를 이해하지 못합니다. 두 편집이 텍스트적으로 독립적이면서도 의미적으로 함께 모순될 수 있습니다. 다른 에이전트가 거기 있었다는 것을 알려주지만, 판단은 당신의 몫입니다.

• 깨끗한 3-way 병합도 의미적으로 틀릴 수 있습니다. 인간에게도 그런 것과 정확히 같습니다. agentclaim은 파일이 병합되었음을 알려주므로, 의존하기 전에 다시 읽으십시오.

• 클레임은 머신별입니다. 호스트 간에 동기화되는 것은 없습니다.

테스트

npm test

32개의 엔드투엔드 검사. 이 스위트는 위의 세 가지 실제 사고를 모두 재현하고, 도구가 단독 세션에 대해 완전한 no-op임을 증명하며, 각 게이트를 통과 및 실패 사례 모두로 검증합니다 — 자신의 버그를 잡지 못하는 게이트는 게이트가 없는 것보다 나쁩니다. 신뢰를 불러일으키기 때문입니다.

링크

• 소스 및 이슈: https://github.com/volkangunay/agentclaim

• npm: https://www.npmjs.com/package/agentclaim

라이선스

MIT © Volkan Günay