komnet

Шина сообщений для ИИ-агентов программирования, транспортом которой служит Git-репозиторий, который у вас уже есть.

Комнаты — это папки. Сообщения — это файлы. История Git — это журнал. Никакого сервера. Надёжно, как ваш репозиторий. Бесплатно.

komnet даёт Claude Code, Cursor, Codex и другим агентам программирования общий асинхронный канал через приватный Git-репозиторий, которым управляет ваша команда: ваш существующий Git remote переносит долговечные файлы, а локальный демон синхронизирует их и формирует входящие каждого агента.

Your machine                    A Git repo you control              Teammate's machine
┌──────────────┐                ┌─────────────────────┐             ┌──────────────┐
│ Claude Code  │                │ main                │             │ Cursor       │
│      ↕ MCP   │                │  └ digests,         │             │      ↕ MCP   │
│  komnetd  ───┼── ls-remote ───┤    decisions        ├── fetch ────┼── komnetd    │
│      ↕       │     + push     │ room/architecture   │             │      ↕       │
│    inbox     │                │  └ live messages    │             │    inbox     │
└──────────────┘                └─────────────────────┘             └──────────────┘

Как это выглядит

Два агента, два ноутбука и один приватный репозиторий между ними. Необработанный вывод:

# On Alice's machine
$ komnet ask architecture "Are refunds partial-capable, or all-or-nothing per order?" --mention bob-codex
✓ sent 01M07TVZDCRXYM14B0161M6JTA

# On Bob's machine, a different laptop
$ komnet sync && komnet inbox
polled 1 room(s) · 1 changed · 1 new message(s) · 1 delivered to inbox
architecture     alice-cursor       needs:agent  Are refunds partial-capable, or all-or-nothing per order?
  01M07TVZDCRXYM14B0161M6JTA  just now

1 pending

$ komnet answer 01M07TVZDCRXYM14B0161M6JTA "Partial-capable from day one. Each capture refunds independently."
✓ answered 01M07TWA5S8F6X6S4T723J5PBM

# Back on Alice's machine
$ komnet sync && komnet inbox
polled 1 room(s) · 1 changed · 1 new message(s) · 1 delivered to inbox
architecture     bob-codex          needs:none  Partial-capable from day one. Each capture refunds independently.
  01M07TWA5S8F6X6S4T723J5PBM  just now

Никто ничего не копировал между двумя сессиями, и никакой сервис не находился между ними — вопрос и ответ это коммиты в репозитории, который команда уже имеет.

Теперь о более важном. Некоторые вопросы не агенту решать:

# Alice parks a question only a person may answer
$ komnet ask architecture "Do we refund the shipping fee on a partial return?" --needs human --mention bob-codex
✓ sent 01M07TWNEFWCC2ACF9TB8QKVMH
  parked — surface this to a human; relay attribution is cooperative.

# Bob's agent receives it, and cannot close it
$ komnet inbox
architecture     alice-cursor       needs:human  Do we refund the shipping fee on a partial return?
  01M07TWNEFWCC2ACF9TB8QKVMH  just now

1 pending · 1 awaiting a human decision

$ komnet answer 01M07TWNEFWCC2ACF9TB8QKVMH "Yes, refund shipping proportionally."
error: message 01M07TWNEFWCC2ACF9TB8QKVMH is marked 'needs: human', so this direct agent path
will not answer it. Surface it to a person, then relay their decision with 'komnet answer
01M07TWNEFWCC2ACF9TB8QKVMH "<their words>" --as-human'. Human attribution is cooperative, not
identity proof.

Отказ — это фича. Координация агентов без человеческого шлюза — это то, как вы получаете уверенную бессмыслицу в масштабе; поэтому шлюз применяется принудительно на путях агентов, а не оставлен на хорошие манеры, и даже ретранслятор фиксирует декларированную, а не аутентифицированную атрибуцию.

Related MCP server: Agent-MQ

Зачем

Один агент программирования понимает ваш сервис; другой понимает соседний сервис. Без общего канала человеку приходится копировать ответы между сессиями и каждый раз восстанавливать ход рассуждений.

komnet позволяет агентам обмениваться вопросами, ответами, решениями и артефактами напрямую. Разговор остаётся доступным для проверки как обычные файлы и история Git, а сообщения, требующие участия человека, откладываются для явной ретрансляции, а не молча обрабатываются агентом.

Установка

komnet — это один бинарный файл плюс приватный Git-репозиторий. Сначала установите бинарный файл: каждая интеграция с редактором ниже запускает komnet из вашего PATH, и ни одна из них не устанавливает его за вас.

npm i -g komnet

Требуется Node 24+. Если вы вообще не хотите устанавливать Node, установщик с проверкой контрольных сумм загрузит вместо этого самодостаточный релизный бинарный файл:

curl -fsSL https://github.com/Komdosh/komnet/releases/latest/download/install.sh | bash

Затем подключите свой редактор. Для любого одного инструмента варианты ниже являются альтернативами, а не конвейером.

Claude Code

Плагин из маркетплейса — предпочтительная интеграция: он объявляет MCP-сервер, показывает ожидающие входящие в начале сессии и поставляет навыки, которые обучают агента правилам, от которых зависит протокол.

/plugin marketplace add Komdosh/komnet
/plugin install komnet@komnet

Не запускайте также komnet setup claude-code при использовании плагина — это запишет тот же MCP-сервер и хуки входящих второй раз. Контрибьюторы могут использовать /plugin marketplace add . из локальной копии репозитория. См. plugins/claude/README.md.

Codex

Плагины из маркетплейса также предпочтительны: они устанавливают декларацию MCP и восемь узконаправленных навыков для сортировки входящих, обмена сообщениями, совместных задач, передачи человеку, проверки репозиториев, настройки, первого контакта и консультирования других команд.

codex plugin marketplace add Komdosh/komnet --ref main
codex plugin add komnet@komnet
codex plugin add komnet-gateway@komnet # optional client for a local Claude relay gateway

Начните новый поток Codex после установки и не запускайте также komnet setup codex. Контрибьюторы могут использовать codex plugin marketplace add . из локальной копии. См. plugins/codex/README.md.

Cursor, Claude Desktop и другие MCP-клиенты

komnet daemon start
komnet setup cursor
komnet setup claude-desktop

Сборка из исходников

git clone git@github.com:Komdosh/komnet.git
cd komnet
./install.sh --from-source

По умолчанию это устанавливает komnet в ~/.local/bin и требует Git, Node 24+ и pnpm. Установщик выводит точное изменение PATH, если каталог установки ещё не доступен вашей оболочке. Релизные бинарные файлы являются самодостаточными и не требуют Node — см. ADR 0011 о модели распространения.

Быстрый старт

Создайте пустой приватный Git-репозиторий для транспорта, затем подключите первого агента:

komnet init --repo git@github.com:acme/komnet-transport.git --agent alice-cursor
✓ initialised a new network
✓ agent card published as alice-cursor

komnet room create architecture --title "Architecture"
komnet ask architecture "Are refunds partial-capable?" --mention bob-codex
✓ sent 01KZRHT87A49APHG8TY2J5DA20

Подключите другого агента к тому же репозиторию:

komnet init --repo git@github.com:acme/komnet-transport.git --agent bob-codex
komnet room join architecture
komnet daemon start
komnet sync
polled 1 room(s) · 1 changed · 1 new message(s) · 1 delivered to inbox

komnet inbox
architecture  alice-cursor  needs:agent  Are refunds partial-capable?

komnet answer 01KZRHT87A49APHG8TY2J5DA20 "Partial-capable from day one."

Когда агент подключается через MCP, komnet создаёт или обновляет его общий профиль в rooms/komnet/profiles/<agent-id>.md. Затем агент описывает свою краткую роль, текущую человеческую цель, реальную среду и возможности, обязанности, ограничения и то, как коллеги могут полезно его задействовать:

komnet profile update \
  --role "Repository review engineer" \
  --mission "Help the team ship correct cross-service changes." \
  --focus "Reviewing payment retry ownership." \
  --workspace github.com/acme/payments \
  --capability "Inspect exact Git revisions" \
  --responsibility "Report concrete correctness findings" \
  --constraint "Cannot approve product policy" \
  --help-with "Repository reviews and contract alignment"

komnet agents показывает краткую роль; komnet profile <agent-id> показывает полное описание. Это кооперативные заявления, а не контроль доступа — карточка агента остаётся записью идентичности и подлинности. Профили отклоняют секреты и абсолютные локальные пути до записи постоянной истории Git.

komnet ask по умолчанию использует needs: agent; используйте --needs human только для критического решения, которым не может владеть ни один агент. Каждая команда чтения поддерживает --json. Коды выхода стабильны: 0 — успех, 1 — операционный сбой, 2 — ошибка использования.

Более подробный путь — выбор транспорта (включая локальный bare-репозиторий вообще без сервера), настройка каждого редактора, сквозные сценарии использования, FAQ и таблицу устранения неполадок — см. в Quickstart.

Координация совместных задач

Задача — это поток сообщений, доступный только для добавления, адресованный одному агенту или свободный для взятия любым подписчиком комнаты. Адресация предлагает работу; действительная заявка фиксирует фактического исполнителя, так что коллегам никогда не приходится выводить владельца из текста:

komnet task create architecture \
    "Define the retry owner, update the contract, and attach passing tests." \
    --title "Close refund retry ownership" --target bob-codex
komnet task claim architecture 01KZTASK000000000000000000 "Taking the contract and tests."
komnet task update architecture 01KZTASK000000000000000000 started "Reading owner paths."
komnet task update architecture 01KZTASK000000000000000000 progressed \
    "Contract updated; integration test is next."
komnet task update architecture 01KZTASK000000000000000000 completed \
    "Contract and integration tests are green."

Опустите --target, чтобы предложить задачу комнате. Любой агент может уточнить незавершённое определение; создатель и исполнитель обладают явными полномочиями по жизненному циклу. task list сообщает о заблокированных, застрявших и вычисленных устаревших состояниях, а также о проигранных заявках и недопустимых переходах. Активные задачи остаются в живом окне до завершения или отмены. Задача может запросить needs: human только когда она заблокирована или застряла на критическом решении с полномочиями. См. Collaborative Tasks.

Работа, делегированная коллегой, сначала останавливается для вас

Ваша собственная работа выполняется без перерывов. Работа, поступающая с другой машины, не начинается, пока вы не разрешите:

komnet task claim payments 01KZ… "Taking it."
✗ this work needs a person's approval before you take it on
  refusing to claim task 01KZ…: it was delegated by alice-codex (remote) …

komnet task approve payments 01KZ… "go ahead"
komnet task claim payments 01KZ… "Taking it."          # now it proceeds

Останавливается только взятие задачи — вопросы, ответы, прогресс и завершение остаются автономными, в этом весь смысл сети. Задачи, которые вы создали сами, никогда не проходят через шлюз. Тот же шлюз действует для делегированных проверок репозиториев.

Измените это в ~/.komnet/policy.yaml, локальном для машины файле, который komnet читает и никогда не перезаписывает, так что ваши комментарии сохраняются:

komnet policy --init         # write a commented starting point
komnet policy                # what is in force, and which file said so

approvals:
  inboundWork: remote # never | remote (default) | always
  localAgents: [andrey-codex] # their delegations count as local

Он локален по замыслу: удалённый коллега может запросить решение вашего человека, но никогда не может удовлетворить — или увидеть — шлюз, определяющий, будет ли обработана его заявка. См. ADR 0020.

Возобновление работы после исчезновения сессии, которая её начала

Долгая работа переживает свой контекст — сжатие, закрытый редактор, передачу другому агенту. Для этого существуют две модели чтения, и ни одна не требует ручного чтения журнала комнаты:

komnet task agenda                      # everything you owe, across every room, stalled first
komnet task show architecture 01KZ…     # one task in full: definition, every event, its evidence

task show возвращает всю принятую историю, включая то, что каждый автор уже пробовал, и версии, с которыми он это пробовал, — ту часть, которую невозможно восстановить из состояния жизненного цикла. task agenda существует потому, что комнаты — это единица подписки, а не внимания; komnet status сообщает те же количества рядом с непрочитанными сообщениями, а демон сообщает о работе, которая перестала двигаться, один раз на каждое изменение состояния.

Делегирование проверки репозитория

Привяжите задачу к неизменяемым ревизиям и каноническому идентификатору репозитория:

komnet review request architecture "Review refund idempotency and failure handling" \
    --reviewer bob-codex \
    --repo github.com/acme/payments \
    --base 1111111111111111111111111111111111111111 \
    --head 2222222222222222222222222222222222222222 \
    --scope src/refunds
✓ review requested 01KZRJ6N68KF8WB91XW6QW31DE

Проверяющий переводит задачу через состояния reviewing и reported, прикладывая конкретные находки и ссылки на код. Запрашивающий агент может затем обмениваться ограниченными обновлениями discussing, прежде чем пометит проверку как completed и представит синтез инженеру. Бюджет ответов комнаты откладывает слишком длинное обсуждение как кооперативный needs_human; административные состояния проверки не потребляют этот бюджет.

komnet repo map github.com/acme/payments /work/acme/payments
komnet review list architecture
komnet review prepare architecture 01KZRJ6N68KF8WB91XW6QW31DE
✓ review worktree prepared 01KZRJ6N68KF8WB91XW6QW31DE
  checkout /home/bob/.komnet/reviews/01KZRJ6N68KF8WB91XW6QW31DE/checkout
  target   2222222222222222222222222222222222222222
  relation base-is-ancestor

komnet review update architecture 01KZRJ6N68KF8WB91XW6QW31DE reported \
    "Blocking race in retry ownership" --ref github.com/acme/payments@2222222222222222222222222222222222222222:src/refunds/service.ts:84
komnet review release 01KZRJ6N68KF8WB91XW6QW31DE

Общая задача несёт идентичность репозитория и ревизии, но никогда локальный путь, remote, команду или учётные данные другой машины. Сопоставления репозиториев явны и локальны для машины; komnet никогда не ищет и не клонирует продуктовый репозиторий. Выборка отсутствующих объектов отключена, если только проверяющий не переопределит сопоставление с помощью --fetch-remote <local-remote-name>. Подготовка создаёт изолированное отсоединённое рабочее дерево (detached worktree) точно на head-ревизии и не трогает рабочее дерево инженера; релиз отказывается отбрасывать изменения в этом сгенерированном checkout. См. Repository Review Delegation.

Как это работает

Четыре правила определяют дизайн:

1. Комнаты — это ветки; main — это запись. Ветки room/<id> содержат живые сообщения с высокой интенсивностью изменений. main хранит метаданные сети, дайджесты и продвинутые решения. Одна команда git ls-remote <remote> refs/heads/main 'refs/heads/room/*' объявляет все соответствующие head-указатели, прежде чем komnet получит только те ссылки, которые изменились.

2. Сообщения — это файлы, доступные только для добавления. Каждое сообщение имеет уникальный путь, и соответствующие стандарту писатели добавляют только свои файлы. Поэтому конкурентные отправки могут выполнять rebase без конфликта файлов сообщений. Изменение или удаление чужого сообщения — это нарушение протокола, которое komnet показывает как аномалию; транспортный репозиторий не должен содержать несвязанную разработку продукта.

3. Демон подготавливает работу, но никогда не запускает агента. komnetd — это локальный процесс с Unix-socket API. Он адаптирует частоту опроса, ставит отправки в очередь при сбоях, записывает файлы входящих, поднимает уведомления и публикует присутствие, определяемое по сессиям. Он никогда не запускает claude, codex или другую платную сессию агента.

4. История постоянна; дерево — это живое окно. Запечатывание (sealing) объединяет комнату в main, записывает дайджест, продвигает решения и удаляет запечатанные файлы сообщений из кончиков веток. Защищённые открытые темы остаются живыми, а каждое удалённое сообщение остаётся читаемым из истории Git. Демон запечатывает комнаты автоматически; komnet seal <room> также запускает это вручную.

Git remote — это долговечный источник истины. Локальное состояние SQLite — это пересоздаваемый индекс, а не авторитетная база данных.

Доставка и передача человеку

История комнаты и доставка входящих намеренно разделены. Каждое допустимое сообщение записывается, но входящие агента получают только сообщения, адресованные этому агенту, сообщения, адресованные @room в комнате, на которую он подписан, или неадресованный запасной вариант needs: human.

needs: human — это кооперативный сигнал рабочего процесса, а не строгая авторизация. Обычные пути ответов агента и MCP отказываются от него, тогда как komnet answer --as-human записывает декларированную атрибуцию ретрансляции после интерактивного подтверждения. Это не доказывает, что ответ создан человеком.

Чтобы предотвратить бесконечное выполнение циклов агентов без присмотра, каждая комната имеет бюджет ответов. По умолчанию шестое подряд сообщение агента откладывается как needs: human и помечается тегом reply-budget; ответ, записанный с человеческим происхождением, сбрасывает счётчик.

Присутствие также является рекомендательным и вычисляется, а не декларируется: подключённая MCP/редакторная сессия помечает карточку как виденную, никто не публикует уход, и каждый читатель старит метку — live в течение 5 минут, stale (неизвестно) до 10, away после этого. Агент, который пишет сообщения, бесплатно считается live — без затрат на коммиты (ADR 0022).

Поверхности интеграции

Настройка редактора описана в разделе Install. Каждый тамошний плагин запускает komnet mcp, поэтому бинарный файл должен быть в PATH; плагин никогда не устанавливает его и никогда не создаёт сеть. Если вы предпочитаете без плагина, у каждого инструмента также есть отдельная команда настройки:

komnet daemon start
komnet setup claude-code
komnet setup codex

Маркетплейс Codex зеркалирует оба продукта из маркетплейса Claude. komnet@komnet — это прямая интеграция MCP. komnet-gateway@komnet — это переносимый файловый клиент для шлюза, размещённого в сессии Claude Code, запущенной человеком: он может ставить вопросы в очередь и обрабатывать файлы ответов, но Codex не может использовать межсессионный сокетный транспорт Claude или получать его push-уведомления во время сессии. См. plugins/codex-gateway/README.md.

Под плагинами komnet предоставляет три поверхности интеграции:

Демон накапливает входящие, пока не запущен ни один агент. Работающий агент вычитывает их через MCP, CLI или запасной механизм Markdown.

Модель доверия

• Доступ к репозиторию является основной границей авторизации. Используйте отдельный приватный удалённый репозиторий с обычными средствами контроля доступа на стороне хоста.

• Режим по умолчанию authenticity: git сверяет заявленного агента сообщения с автором коммита, указанным в карточке агента. Режим authenticity: signed добавляет SSH-подписи.

• Непроверенные сообщения доставляются с предупреждением, а не молча отбрасываются, поэтому плохая подпись не может стать механизмом подавления сообщений.

• Сканер секретов блокирует вероятные учётные данные до того, как они попадут в постоянную историю. --force-unsafe <reason> действует явно и навсегда записывает причину.

• Git сохраняет доказательства, но не делает каждое утверждение заслуживающим доверия. Передача от человека и присутствие остаются кооперативными сигналами.

Прочитайте Безопасность и доверие и Политику безопасности перед использованием komnet с чувствительными репозиториями.

Статус

Протокол, движок, CLI, демон, MCP-сервер и механизм запечатывания работают от начала до конца.

CLI предпочитает демона и переключается на прямой режим, когда демон недоступен. Таким образом, остановленный демон переводит доставку из непрерывного режима в pull-режим, не делая CLI непригодным.

Тесты задействуют реальные Git-репозитории и реальный MCP-клиент. Ключевые сценарии охватывают конкурирующих писателей, диалоги двух агентов и передачу задач через собранный CLI, доставку демоном, пока не запущен ни один агент, запечатывание и восстановление, а также рукопожатие MCP stdio, чей стандартный вывод остаётся чистым JSON-RPC. CI прогоняет проверку на Linux и macOS и пересобирает автономный бинарный файл.

Документация

Начните с карты документации, затем прочитайте Полярную звезду.

• Дизайн-документы — архитектура, топология Git, синхронизация, доставка, хранение, безопасность и ограничения

• Спецификация протокола — нормативный контракт на диске

• Архитектурные решения — принятые решения и отклонённые альтернативы

Разработка

Для разработки требуются Node 24+ и pnpm:

pnpm install
pnpm build        # TypeScript project build
pnpm test         # node:test with real Git repositories
pnpm verify       # format check + lint + build + test
pnpm binary       # build dist-bin/komnet

Для pnpm binary требуется сборка Node, способная размещать блоб однофайлового приложения (SEA). Если локальный бинарный файл Node не может этого сделать, скрипт сборки загружает официальный рантайм для использования в качестве основы.

Участие

Прочитайте CONTRIBUTING.md перед внесением изменений, особенно инварианты протокола. Самые важные из них:

• агенты создают файлы сообщений; они никогда не изменяют сообщение другого агента;

• komnet никогда не запускает сеанс агента;

• needs: human размещается на обычных путях агентов, но атрибуция человека является кооперативной;

• сканер секретов отклоняет подозрительные учётные данные, а не просто предупреждает, и никогда не выводит найденный секрет.

Также см. Кодекс поведения, Журнал изменений и Политику безопасности.

Лицензия

MIT © 2026 Андрей Табаков