agent-semaphore

Координационный слой для параллельных агентов, пишущих код. Worktree'ы не устраняют конфликты слияния — они откладывают их на этап интеграции. agent-semaphore закрывает этот пробел: намерения-заявки (claims) на области, предупреждение в момент записи, прогнозирование конфликтов до коммита и сериализованная очередь посадки с обязательным тестовым шлюзом.

Локально-ориентированный: без демона, без облака, без аккаунта. Единственный SQLite-файл в общей директории git — это вся точка рандеву, поэтому каждый worktree репозитория видит её по построению. Кроссплатформенный по замыслу — хуки Claude Code и MCP, Codex CLI через MCP, все остальные через git-хук pre-commit.

Проблема

Pull request'ы, написанные агентами, конфликтуют в 27,7% случаев — против 10–20% для человеческих (AgenticFlict, 107К+ PR'ов от агентов). В парах со-активных агентов разрыв составляет 19,8% внутриагентских против 41,7% межагентских: у агентов нет горизонтальной осведомлённости друг о друге, и каждый продукт, предоставляющий координацию, координирует только своих собственных агентов. Плохо разрешённый конфликт несёт до ~26x плотности ошибок по сравнению с обычным кодом (EMSE 2020) — дорогая часть не сам конфликт, а тихое плохое разрешение.

Изоляция решена и превращена в товар (worktree или контейнер на агента — все это предоставляют). Прогнозирование и интеграция — нет: никто не запускает git merge-tree между живыми worktree'ами, а автономные локальные очереди слияния практически не существуют.

Что он делает

Жёсткие гарантии существуют ровно в одном месте: путь посадки. Хуки и 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-сервер в .mcp.json. Зафиксированная разводка переносима между машинами ($HOME и голый asem), поэтому репозиторий, общий для нескольких машин, не несёт пути одного хоста.

• MCP (asem mcp, ключ сервера semaphore) — claim, release, check, status, extend, report_intent, radar, enqueue_land, land_status. Каждый ответ сливает ожидающие уведомления, поэтому агенты узнают о кражах, отскоках и перемещённых целях без опроса.

• Codex CLI — тот же MCP-сервер через ~/.codex/config.toml, плюс фрагмент протокола для AGENTS.md. Headless 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 тестов, шлюз задержки хука p95 в CI, оба бенчмарка воспроизводимы из репозитория.

Известные ограничения, изложенные прямо: продвижение из staging-ветки в 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.