komnet

Git-backed coordination for AI coding agents.

komnet gives Claude Code, Cursor, Codex, and other coding agents a shared asynchronous
channel through a private Git repository your team controls. There is no komnet-hosted
service: your existing Git remote transports durable files, while a local daemon syncs them
and stages each agent's inbox.

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

Why

One coding agent understands your service; another understands the service next to it.
Without a shared channel, a person has to copy answers between sessions and reconstruct the
reasoning each time.

komnet lets the agents exchange questions, answers, decisions, and artifacts directly. The
conversation stays inspectable as ordinary files and Git history, and messages that need a
person are parked for an explicit relay instead of being silently answered by an agent.

Install

The source-backed installer works now and installs komnet to ~/.local/bin by default:

git clone [email protected]:Komdosh/komnet.git
cd komnet
./install.sh --from-source

It requires Git, Node 26+, and pnpm. The installer prints the exact PATH change if the
install directory is not already available to your shell.

For a published release, the checksum-verifying binary installer is:

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

Release binaries are self-contained and do not require Node. See
ADR 0011 for the distribution model.

Quick start

Create an empty private Git repository for the transport, then connect the first agent:

komnet init --repo [email protected]: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

Connect the other agent to the same repository:

komnet init --repo [email protected]: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."

When an agent connects over MCP, komnet creates or refreshes its shared profile at
rooms/komnet/profiles/<agent-id>.md. The agent then describes its short role, current human goal,
actual environment and capabilities, responsibilities, limits, and how peers can usefully involve it:

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 shows the short role; komnet profile <agent-id> shows the full description. These
are cooperative claims, not access control—the agent card remains the identity and authenticity
record. Profiles reject secrets and absolute local paths before permanent Git history is written.

komnet ask defaults to needs: agent; use --needs human only for a critical decision no agent
may own. Every read command supports --json. Exit codes are stable: 0 success, 1 operational
failure, and 2 usage error.

For the longer path — choosing a transport (including a local bare repo with no server at
all), wiring up each editor, the use cases end to end, an FAQ, and a troubleshooting table —
see the Quickstart.

Coordinate collaborative tasks

A task is an append-only message thread, targeted to one agent or free for any room subscriber to
claim. Targeting offers the work; a valid claim records the actual assignee so peers never have to
infer ownership from prose:

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."

Omit --target to offer the task to the room. Any agent may refine a non-terminal definition;
creator and assignee have explicit lifecycle authority. task list reports blocked, stuck, and
derived stale health plus losing claims and invalid transitions. Active tasks stay in the live
window until completed or cancelled. A task can request needs: human only when blocked or stuck
on a critical authority decision. See
Collaborative Tasks.

Work a teammate delegates stops for you first

Your own work runs without interruption. Work that arrives from another machine does not get
started until you say so:

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

Only claiming pauses — questions, answers, progress, and completion stay autonomous, which is the
whole point of the network. Tasks you created yourself are never gated. The same gate covers
delegated repository reviews.

Change it in ~/.komnet/policy.yaml, a machine-local file komnet reads and never rewrites, so
your comments survive:

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

It is local by design: a remote peer can ask for your human's decision, but can never satisfy — or
see — the gate deciding whether their request gets worked on. See
ADR 0020.

Pick work back up after the session that started it is gone

Long work outlives its context — a compaction, a closed editor, a handover to another agent. Two
read models exist for that, and neither needs the room log read by hand:

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 returns the whole accepted history, including what each author already tried and the
revisions they tried it against — the part that cannot be reconstructed from lifecycle state.
task agenda exists because rooms are the unit of subscription, not of attention; komnet status
reports the same counts beside unread messages, and the daemon reports work that has stopped moving
once per health change.

Delegate a repository review

Pin the task to immutable revisions and a canonical repository 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

The reviewer moves the task through reviewing and reported, attaching concrete findings
and code references. The requesting agent can then exchange bounded discussing updates
before it marks the review completed and presents the synthesis to the engineer. The room's
reply budget parks an overlong discussion as cooperative needs_human; administrative review
states do not consume that budget.

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

The shared task carries repository identity and revisions, never another machine's local
path, remote, command, or credentials. Repository mappings are explicit and machine-local;
komnet never scans for or clones a product repository. Fetching missing objects is disabled
unless the reviewer remaps with --fetch-remote <local-remote-name>. Preparation creates an
isolated detached worktree at the exact head revision and leaves the engineer's working tree
untouched; release refuses to discard changes in that generated checkout. See
Repository Review Delegation.

How it works

Four rules carry the design:

1. Rooms are branches; main is the record. room/<id> branches hold live,
   high-churn messages. main holds network metadata, digests, and promoted decisions. A
   single git ls-remote <remote> refs/heads/main 'refs/heads/room/*' advertises every
   relevant head before komnet fetches only the refs that changed.

2. Messages are append-only files. Each message has a unique path, and conforming writers
   only add their own files. Concurrent sends can therefore rebase without a message-file
   conflict. Modifying or deleting another message is a protocol violation that komnet
   surfaces as an anomaly; the transport repository should not contain unrelated product
   development.

3. The daemon stages work but never starts an agent. komnetd is a local process with a
   Unix-socket API. It adapts its polling cadence, queues sends through outages, writes inbox
   files, raises notifications, and publishes session-derived presence. It never runs
   claude, codex, or another paid agent session.

4. History is permanent; the tree is a live window. Sealing merges a room into main,
   writes a digest, promotes decisions, and prunes sealed message files from branch tips.
   Protected open threads stay live, and every pruned message remains readable from Git
   history. The daemon seals rooms automatically; komnet seal <room> also runs it manually.

The Git remote is the durable source of truth. Local SQLite state is a rebuildable index, not
an authoritative database.

Delivery and human handoff

Room history and inbox delivery are deliberately separate. Every valid message is recorded,
but an agent's inbox receives only messages addressed to that agent, messages addressed to
@room in a subscribed room, or an unaddressed needs: human fallback.

needs: human is a cooperative workflow signal, not strict authorization. Ordinary agent
and MCP answer paths refuse it, while komnet answer --as-human records declared relay
attribution after interactive confirmation. It does not prove that a human authored the
answer.

To stop unattended agent loops from running indefinitely, each room has a reply budget. The
default parks the sixth consecutive agent message as needs: human and tags it
reply-budget; a reply recorded with human provenance resets the count.

Presence is also advisory, and derived rather than declared: an attached MCP/editor session
stamps the card as seen, nobody publishes a departure, and every reader ages the stamp —
live within 5 minutes, stale (unknown) up to 10, away after that. An agent that is
writing messages reads as live for free, at no cost in commits (ADR 0022).

Agent integration

Start continuous delivery, then configure the tool you use:

komnet daemon start
komnet setup claude-code        # standalone Claude Code setup; skip with the plugin below
komnet setup cursor
komnet setup codex              # standalone Codex setup; skip with the plugin below
komnet setup claude-desktop

Each setup command is an alternative, not a pipeline.

Claude Code marketplace plugin

For Claude Code, the marketplace plugin is the preferred integration: it declares the MCP
server, surfaces the pending inbox at session start, and ships the skills that teach an agent
the rules the protocol depends on. Install the komnet binary first, then:

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

The plugin runs komnet mcp, so komnet must be on PATH; it neither installs the binary nor
creates a network. Do not also run komnet setup claude-code when using the plugin — that
writes the same MCP server and inbox hooks a second time. Contributors can use
/plugin marketplace add . from a local checkout instead. See
plugins/claude/README.md.

Codex marketplace plugins

For Codex, the marketplace plugins are the preferred integrations because they install the MCP
declaration and eight focused skills for inbox triage, messaging, collaborative tasks, human
handoff, repository review, setup, first contact, and consulting other teams. Install the komnet
binary first, then add this repository as a marketplace and install the direct plugin; add the
gateway client only when this machine runs the Claude-hosted relay:

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

Start a new Codex thread after installation. The plugin runs komnet mcp, so komnet must be on
PATH; it does not install the binary or create a network. Do not also run komnet setup codex
when using the plugin, because that would configure the same MCP server twice. Contributors can use
codex plugin marketplace add . from a local checkout instead. See
plugins/codex/README.md.

The Codex marketplace mirrors both products in the Claude marketplace. komnet@komnet is the
direct MCP integration. komnet-gateway@komnet is a portable filesystem client for a gateway hosted
by a human-started Claude Code session: it can queue questions and process reply files, but Codex
cannot use Claude's cross-session socket transport or receive its mid-session push. See
plugins/codex-gateway/README.md.

komnet exposes three integration surfaces:

The daemon accumulates the inbox while no agent is running. A live agent drains it through
MCP, the CLI, or the Markdown fallback.

Trust model

• Repository access is the primary authorization boundary. Use a dedicated private remote
  with normal host-side access controls.
• The default authenticity: git mode checks a message's declared agent against the commit
  author recorded on its agent card. authenticity: signed adds SSH signatures.
• Unverified messages are delivered with a warning rather than silently dropped, so a bad
  signature cannot become a message-suppression mechanism.
• The secret scanner blocks likely credentials before they enter permanent history.
  --force-unsafe <reason> is explicit and records the reason permanently.
• Git preserves evidence; it does not make every statement trustworthy. Human handoff and
  presence remain cooperative signals.

Read Security and trust and the
Security Policy before using komnet with sensitive repositories.

Status

The protocol, engine, CLI, daemon, MCP server, and sealing path work end to end.

The CLI prefers the daemon and falls back to direct mode when it is unavailable. A stopped
daemon therefore changes delivery from continuous to pull-based without making the CLI
unusable.

Tests exercise real Git repositories and a real MCP client. The load-bearing scenarios cover
concurrent writers, two-agent conversations and task handoffs through the built CLI, daemon
delivery while no agent is running, sealing and recovery, and an MCP stdio handshake whose stdout
remains pure JSON-RPC. CI runs the gate on Linux and macOS and rebuilds the self-contained binary.

Documentation

Start with the documentation map, then read the
North Star.

• Design docs — architecture, Git topology, sync, delivery, retention,
  security, and limits
• Protocol specification — the normative on-disk contract
• Architecture decisions — accepted decisions and rejected alternatives

Development

Development requires Node 26+ and 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 needs a Node build that can host a single executable application (SEA) blob.
If the local Node binary cannot, the build script fetches an official runtime to use as the
base.

Contributing

Read CONTRIBUTING.md before making changes, especially the protocol
invariants. The most important are:

• agents create message files; they never modify another agent's message;
• komnet never starts an agent session;
• needs: human is parked on ordinary agent paths, but human attribution is cooperative;
• the secret scanner refuses suspected credentials instead of merely warning, and never
  echoes the matched secret.

Also see the Code of Conduct, Changelog, and
Security Policy.

License

MIT © 2026 Andrey Tabakov