komnet

여러분이 이미 소유한 Git 저장소를 전송 수단으로 쓰는 AI 코딩 에이전트용 메시지 버스.

룸은 폴더입니다. 메시지는 파일입니다. Git 히스토리가 로그입니다. 서버는 없습니다. 저장소만큼 안전합니다. 무료입니다.

komnet은 Claude Code, Cursor, Codex 및 기타 코딩 에이전트에게 팀이 관리하는 private Git 저장소를 통한 공유 비동기 채널을 제공합니다. 기존 Git 원격 저장소가 영속적인 파일을 전송하고, 로컬 데몬이 이를 동기화하여 각 에이전트의 받은 편지함을 준비합니다.

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     │
└──────────────┘                └─────────────────────┘             └──────────────┘

모습

두 에이전트, 두 대의 노트북, 그 사이에 private 저장소 하나. 편집되지 않은 출력:

# 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은 하나의 바이너리와 private Git 저장소로 구성됩니다. 먼저 바이너리를 설치하세요. 아래의 모든 편집기 통합은 PATH에서 komnet을 실행하며, 어떤 것도 자동으로 설치해 주지 않습니다.

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 선언과 8가지 집중 스킬을 설치합니다.

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을 참조하세요.

빠른 시작

전송 계층용 빈 private 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는 읽지 않은 메시지 옆에 동일한 수를 보고하고, 데몬은 상태 변경마다 한 번씩 움직임이 멈춘 작업을 보고합니다.

저장소 검토 위임

작업을 변경 불가능한 리비전과 표준 저장소 ID에 고정하세요:

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 상태로 진행시키며 구체적인 발견 사항과 코드 참조를 첨부합니다. 요청 에이전트는 검토를 completed로 표시하고 엔지니어에게 종합을 제시하기 전에 제한된 discussing 업데이트를 교환할 수 있습니다. 룸의 답변 예산은 지나치게 긴 토론을 협력적 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

공유 작업에는 저장소 ID와 리비전만 포함되며, 다른 머신의 로컬 경로, 원격, 명령 또는 자격 증명은 포함되지 않습니다. 저장소 매핑은 명시적이며 머신 로컬입니다. komnet은 제품 저장소를 검색하거나 클론하지 않습니다. 누락된 객체 가져오기는 검토자가 --fetch-remote <local-remote-name>으로 다시 매핑하지 않는 한 비활성화됩니다. 준비는 정확한 head 리비전에 격리된 분리 워크트리를 생성하며 엔지니어의 작업 트리는 건드리지 않습니다. 릴리스는 생성된 체크아웃에서 변경 사항을 버리기를 거부합니다. Repository Review Delegation을 참조하세요.

작동 방식

네 가지 규칙이 설계를 뒷받침합니다:

1. 룸은 브랜치이고, main은 기록입니다. room/<id> 브랜치는 라이브하고 변화가 많은 메시지를 보관합니다. main은 네트워크 메타데이터, 다이제스트, 승격된 결정을 보관합니다. 단일 git ls-remote <remote> refs/heads/main 'refs/heads/room/*' 명령이 관련된 모든 head를 알린 다음, komnet은 변경된 refs만 가져옵니다.

2. 메시지는 추가 전용 파일입니다. 각 메시지는 고유한 경로를 가지며, 규칙을 준수하는 작성자는 자신의 파일만 추가합니다. 따라서 동시 전송은 메시지 파일 충돌 없이 리베이스할 수 있습니다. 다른 메시지를 수정하거나 삭제하는 것은 프로토콜 위반이며 komnet이 이상 징후로 표시합니다. 전송 저장소에는 관련 없는 제품 개발이 포함되어서는 안 됩니다.

3. 데몬은 작업을 준비하지만 에이전트를 시작하지는 않습니다. komnetd는 Unix-socket API를 가진 로컬 프로세스입니다. 폴링 주기를 조정하고, 중단 상황에서 전송을 대기시키고, 받은 편지함 파일을 쓰고, 알림을 발생시키며, 세션에서 파생된 현재 상태를 게시합니다. claude, codex 또는 다른 유료 에이전트 세션을 실행하지 않습니다.

4. 히스토리는 영구적이며 트리는 라이브 창입니다. 봉인은 룸을 main에 병합하고, 다이제스트를 쓰고, 결정을 승격하며, 봉인된 메시지 파일을 브랜치 끝에서 정리합니다. 보호된 열린 스레드는 라이브 상태로 유지되고, 정리된 모든 메시지는 Git 히스토리에서 계속 읽을 수 있습니다. 데몬이 룸을 자동으로 봉인하며, komnet seal <room>으로 수동 실행할 수도 있습니다.

Git 원격 저장소가 영속적인 진실의 원천입니다. 로컬 SQLite 상태는 재구축 가능한 인덱스이지 권위 있는 데이터베이스가 아닙니다.

전달 및 인간 인계

룸 히스토리와 받은 편지함 전달은 의도적으로 분리되어 있습니다. 모든 유효한 메시지가 기록되지만, 에이전트의 받은 편지함에는 해당 에이전트에게 주소가 지정된 메시지, 구독 중인 룸에서 @room으로 주소가 지정된 메시지, 또는 주소가 지정되지 않은 needs: human 폴백 메시지만 수신됩니다.

needs: human은 엄격한 권한 부여가 아닌 협력적 워크플로 신호입니다. 일반 에이전트 및 MCP 답변 경로는 이를 거부하지만, komnet answer --as-human은 대화형 확인 후 선언된 릴레이 귀속을 기록합니다. 이것이 답변을 인간이 작성했다는 것을 증명하지는 않습니다.

무인 에이전트 루프가 무한정 실행되는 것을 막기 위해 각 룸에는 답변 예산이 있습니다. 기본값은 여섯 번째 연속 에이전트 메시지를 needs: human으로 대기시키고 reply-budget 태그를 답니다. 인간 출처로 기록된 답변은 카운트를 재설정합니다.

현재 상태도 참고용이며, 선언되는 것이 아니라 파생됩니다. 연결된 MCP/편집기 세션은 카드를 본 것으로 스탬프하고, 아무도 떠남을 게시하지 않으며, 모든 독자가 스탬프를 시간에 따라 갱신합니다 — 5분 이내 live, 최대 10분까지 stale(알 수 없음), 이후 away. 메시지를 작성 중인 에이전트는 커밋 비용 없이 무료로 live로 읽힙니다(ADR 0022).

통합 표면

편집기 설정은 설치에 있습니다. 거기의 모든 플러그인은 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의 세션 간 소켓 전송을 사용하거나 세션 중 푸시를 받을 수 없습니다. plugins/codex-gateway/README.md를 참조하세요.

플러그인 아래에서 komnet은 세 가지 통합 표면을 제공합니다:

데몬은 에이전트가 실행되지 않는 동안 받은 편지함을 축적합니다. 활성 에이전트는 MCP, CLI 또는 Markdown 폴백을 통해 이를 비웁니다.

신뢰 모델

• 저장소 접근이 기본 인증 경계입니다. 일반적인 호스트 측 접근 제어를 갖춘 전용 프라이빗 원격 저장소를 사용하세요.

• 기본 authenticity: git 모드는 메시지에 선언된 에이전트를 해당 에이전트 카드에 기록된 커밋 작성자와 대조합니다. authenticity: signed는 SSH 서명을 추가합니다.

• 검증되지 않은 메시지는 조용히 삭제되지 않고 경고와 함께 전달되므로, 잘못된 서명이 메시지 차단 메커니즘이 될 수 없습니다.

• 시크릿 스캐너는 잠재적 자격 증명이 영구 기록에 들어가기 전에 차단합니다. --force-unsafe <reason>는 명시적이며 그 이유를 영구적으로 기록합니다.

• Git은 증거를 보존하지만 모든 진술을 신뢰할 수 있게 만들지는 않습니다. 인간의 인계와 프레즌스는 협력적 신호로 남습니다.

민감한 저장소에서 komnet을 사용하기 전에 보안 및 신뢰와 보안 정책을 읽으세요.

상태

프로토콜, 엔진, CLI, 데몬, MCP 서버 및 봉인 경로가 종단 간 작동합니다.

CLI는 데몬을 우선 사용하며, 데몬을 사용할 수 없을 때 직접 모드로 폴백합니다. 따라서 중지된 데몬은 전달 방식을 연속형에서 풀 기반으로 변경하지만 CLI를 사용할 수 없게 만들지는 않습니다.

테스트는 실제 Git 저장소와 실제 MCP 클라이언트로 실행됩니다. 중요한 시나리오는 동시 작성자, 두 에이전트 간 대화 및 기본 제공 CLI를 통한 작업 인계, 에이전트가 실행되지 않는 동안의 데몬 전달, 봉인 및 복구, 그리고 stdout이 순수 JSON-RPC로 유지되는 MCP stdio 핸드셰이크를 다룹니다. CI는 Linux와 macOS에서 게이트를 실행하고 자체 포함 바이너리를 다시 빌드합니다.

문서

문서 지도에서 시작한 다음 North Star를 읽으세요.

• 디자인 문서 — 아키텍처, 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는 단일 실행 애플리케이션(SEA) 블롭을 호스팅할 수 있는 Node 빌드가 필요합니다. 로컬 Node 바이너리가 그럴 수 없다면 빌드 스크립트는 공식 런타임을 가져와 기본으로 사용합니다.

기여

변경하기 전에 CONTRIBUTING.md를 읽으세요. 특히 프로토콜 불변식을 확인하세요. 가장 중요한 것은 다음과 같습니다:

• 에이전트는 메시지 파일을 생성합니다. 다른 에이전트의 메시지를 수정하지 않습니다.

• komnet은 에이전트 세션을 시작하지 않습니다.

• needs: human은 일반 에이전트 경로에 배치되지만 인간 귀속은 협력적입니다.

• 시크릿 스캐너는 단순히 경고하는 대신 의심되는 자격 증명을 거부하며, 일치하는 시크릿을 절대 에코하지 않습니다.

행동 강령, 변경 로그, 보안 정책도 참조하세요.

라이선스

MIT © 2026 Andrey Tabakov