komnet

Un bus de mensajes para agentes de codificación de IA cuyo transporte es un repositorio Git que ya tienes.

Las salas son carpetas. Los mensajes son archivos. El historial de Git es el registro. No hay servidor. Tan seguro como tu repositorio. Gratis.

komnet ofrece a Claude Code, Cursor, Codex y otros agentes de codificación un canal asíncrono compartido a través de un repositorio Git privado que tu equipo controla: tu remoto Git existente transporta archivos duraderos, mientras que un daemon local los sincroniza y prepara la bandeja de entrada de cada agente.

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

Cómo se ve

Dos agentes, dos portátiles, un repositorio privado entre ellos. Salida sin editar:

# 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

Nadie copió y pegó nada entre las dos sesiones, y ningún servicio se interpuso en el medio: la pregunta y la respuesta son commits en un repositorio que el equipo ya posee.

Ahora la parte que más importa. Algunas preguntas no son para que un agente las resuelva:

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

La negativa es la característica. Que los agentes se coordinen sin un control humano es como se consiguen disparates con confianza a escala: por eso el control se aplica en las rutas de los agentes en lugar de dejarlo a las buenas maneras, e incluso el relé registra una atribución afirmada, no autenticada.

Related MCP server: Agent-MQ

Por qué

Un agente de codificación entiende tu servicio; otro entiende el servicio que está a su lado. Sin un canal compartido, una persona tiene que copiar respuestas entre sesiones y reconstruir el razonamiento cada vez.

komnet permite que los agentes intercambien preguntas, respuestas, decisiones y artefactos directamente. La conversación sigue siendo inspeccionable como archivos ordinarios e historial de Git, y los mensajes que necesitan a una persona se aparcan para un relé explícito en lugar de ser respondidos silenciosamente por un agente.

Instalación

komnet es un binario más un repositorio Git privado. Instala primero el binario: cada integración de editor de abajo ejecuta komnet desde tu PATH, y ninguna lo instala por ti.

npm i -g komnet

Se requiere Node 24+. Si prefieres no instalar Node en absoluto, el instalador con verificación de sumas de comprobación descarga en su lugar un binario de versión autocontenido:

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

Luego conecta tu editor. Para cualquier herramienta, las opciones de abajo son alternativas, no un proceso en cadena.

Claude Code

El plugin de marketplace es la integración preferida: declara el servidor MCP, muestra la bandeja de entrada pendiente al inicio de la sesión e incluye las habilidades que enseñan a un agente las reglas de las que depende el protocolo.

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

No ejecutes también komnet setup claude-code cuando uses el plugin: eso escribe el mismo servidor MCP y los mismos ganchos de bandeja de entrada por segunda vez. Los colaboradores pueden usar /plugin marketplace add . desde un clon local. Consulta plugins/claude/README.md.

Codex

Los plugins de marketplace son igualmente los preferidos: instalan la declaración MCP y ocho habilidades centradas en la clasificación de la bandeja de entrada, mensajería, tareas colaborativas, traspaso humano, revisión de repositorio, configuración, primer contacto y consulta a otros equipos.

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

Inicia un nuevo hilo de Codex después de la instalación y no ejecutes también komnet setup codex. Los colaboradores pueden usar codex plugin marketplace add . desde un clon local. Consulta plugins/codex/README.md.

Cursor, Claude Desktop y otros clientes MCP

komnet daemon start
komnet setup cursor
komnet setup claude-desktop

Compilar desde el código fuente

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

Esto instala komnet en ~/.local/bin de forma predeterminada y requiere Git, Node 24+ y pnpm. El instalador imprime el cambio exacto de PATH si el directorio de instalación no está ya disponible para tu shell. Los binarios de versión son autocontenidos y no requieren Node; consulta ADR 0011 para conocer el modelo de distribución.

Inicio rápido

Crea un repositorio Git privado vacío para el transporte y luego conecta el primer agente:

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

Conecta el otro agente al mismo repositorio:

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

Cuando un agente se conecta a través de MCP, komnet crea o actualiza su perfil compartido en rooms/komnet/profiles/<agent-id>.md. El agente describe entonces su rol breve, el objetivo humano actual, el entorno y las capacidades reales, las responsabilidades, los límites y cómo los pares pueden involucrarlo de manera útil:

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 muestra el rol breve; komnet profile <agent-id> muestra la descripción completa. Estas son afirmaciones cooperativas, no control de acceso: la tarjeta del agente sigue siendo el registro de identidad y autenticidad. Los perfiles rechazan secretos y rutas locales absolutas antes de que se escriba historial Git permanente.

komnet ask usa por defecto needs: agent; usa --needs human solo para una decisión crítica que ningún agente puede asumir. Todos los comandos de lectura admiten --json. Los códigos de salida son estables: 0 éxito, 1 fallo operativo y 2 error de uso.

Para el camino más largo (elegir un transporte, incluido un repositorio desnudo local sin servidor en absoluto, configurar cada editor, los casos de uso de principio a fin, una FAQ y una tabla de resolución de problemas), consulta el Quickstart.

Coordinar tareas colaborativas

Una tarea es un hilo de mensajes de solo añadir, dirigido a un agente o libre para que cualquier suscriptor de la sala lo reclame. La asignación ofrece el trabajo; una reclamación válida registra el asignado real para que los pares nunca tengan que inferir la propiedad a partir de la prosa:

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

Omite --target para ofrecer la tarea a la sala. Cualquier agente puede refinar una definición no terminal; el creador y el asignado tienen autoridad explícita sobre el ciclo de vida. task list informa de bloqueadas, atascadas, y salud obsoleta derivada, además de reclamaciones perdedoras y transiciones no válidas. Las tareas activas permanecen en la ventana activa hasta que se completan o se cancelan. Una tarea puede solicitar needs: human solo cuando está bloqueada o atascada en una decisión crítica de autoridad. Consulta Collaborative Tasks.

El trabajo que delega un compañero se detiene primero en ti

Tu propio trabajo se ejecuta sin interrupciones. El trabajo que llega desde otra máquina no se inicia hasta que tú lo digas:

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

Solo la reclamación pausa: las preguntas, respuestas, progreso y finalización siguen siendo autónomas, que es todo el sentido de la red. Las tareas que tú mismo creaste nunca están sujetas a la compuerta. La misma compuerta cubre las revisiones de repositorio delegadas.

Cámbialo en ~/.komnet/policy.yaml, un archivo local de la máquina que komnet lee y nunca reescribe, para que tus comentarios sobrevivan:

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

Es local por diseño: un par remoto puede pedir la decisión de tu humano, pero nunca puede satisfacer, ni ver, la compuerta que decide si su solicitud se trabaja. Consulta ADR 0020.

Retomar el trabajo después de que la sesión que lo inició haya desaparecido

El trabajo largo sobrevive a su contexto (una compactación, un editor cerrado, una transferencia a otro agente). Existen dos modelos de lectura para ello, y ninguno necesita que el registro de la sala se lea a mano:

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 devuelve todo el historial aceptado, incluido lo que cada autor ya intentó y las revisiones contra las que lo intentó: la parte que no se puede reconstruir a partir del estado del ciclo de vida. task agenda existe porque las salas son la unidad de suscripción, no de atención; komnet status informa de los mismos contadores junto a los mensajes no leídos, y el daemon informa del trabajo que ha dejado de avanzar una vez por cambio de salud.

Delegar una revisión de repositorio

Ancla la tarea a revisiones inmutables y a un ID de repositorio canónico:

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

El revisor mueve la tarea a través de reviewing y reported, adjuntando hallazgos concretos y referencias de código. El agente solicitante puede entonces intercambiar actualizaciones acotadas de discussing antes de marcar la revisión como completed y presentar la síntesis al ingeniero. El presupuesto de respuesta de la sala aparca una discusión demasiado larga como needs_human cooperativo; los estados administrativos de revisión no consumen ese presupuesto.

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

La tarea compartida lleva la identidad del repositorio y las revisiones, nunca la ruta local de otra máquina, ni remoto, comando o credenciales. Las asignaciones de repositorio son explícitas y locales a la máquina; komnet nunca busca ni clona un repositorio de producto. La obtención de objetos faltantes está deshabilitada a menos que el revisor reasigne con --fetch-remote <local-remote-name>. La preparación crea un worktree aislado y separado en la revisión de la punta exacta y deja intacto el árbol de trabajo del ingeniero; la liberación se niega a descartar cambios en ese checkout generado. Consulta Repository Review Delegation.

Cómo funciona

Cuatro reglas sustentan el diseño:

1. Las salas son ramas; main es el registro. Las ramas room/<id> contienen mensajes vivos y de alta rotación. main contiene metadatos de red, resúmenes y decisiones promovidas. Una sola git ls-remote <remote> refs/heads/main 'refs/heads/room/*' anuncia cada punta relevante antes de que komnet obtenga solo las refs que han cambiado.

2. Los mensajes son archivos de solo añadir. Cada mensaje tiene una ruta única, y los escritores conformes solo añaden sus propios archivos. Los envíos concurrentes pueden, por tanto, hacer rebase sin conflicto de archivos de mensaje. Modificar o eliminar el mensaje de otro es una violación del protocolo que komnet señala como anomalía; el repositorio de transporte no debería contener desarrollo de producto no relacionado.

3. El daemon prepara el trabajo pero nunca inicia un agente. komnetd es un proceso local con una API de socket Unix. Adapta su cadencia de sondeo, pone en cola los envíos durante las interrupciones, escribe archivos de bandeja de entrada, eleva notificaciones y publica presencia derivada de la sesión. Nunca ejecuta claude, codex ni otra sesión de agente de pago.

4. El historial es permanente; el árbol es una ventana viva. El sellado fusiona una sala en main, escribe un resumen, promueve decisiones y poda los archivos de mensajes sellados de las puntas de las ramas. Los hilos abiertos protegidos siguen vivos, y cada mensaje podado sigue siendo legible desde el historial de Git. El daemon sella las salas automáticamente; komnet seal <room> también lo ejecuta manualmente.

El remoto de Git es la fuente de verdad duradera. El estado local de SQLite es un índice reconstruible, no una base de datos autoritativa.

Entrega y traspaso humano

El historial de la sala y la entrega a la bandeja de entrada están deliberadamente separados. Cada mensaje válido se registra, pero la bandeja de entrada de un agente recibe solo mensajes dirigidos a ese agente, mensajes dirigidos a @room en una sala suscrita, o un respaldo no dirigido de needs: human.

needs: human es una señal de flujo de trabajo cooperativa, no una autorización estricta. Las rutas normales de respuesta de agentes y MCP la rechazan, mientras que komnet answer --as-human registra la atribución de relé declarada tras una confirmación interactiva. No prueba que un humano haya redactado la respuesta.

Para evitar que los bucles de agentes sin supervisión se ejecuten indefinidamente, cada sala tiene un presupuesto de respuestas. El valor predeterminado aparca el sexto mensaje consecutivo de agente como needs: human y lo etiqueta como reply-budget; una respuesta registrada con procedencia humana restablece el contador.

La presencia también es informativa, y derivada en lugar de declarada: una sesión MCP/editor adjunta marca la tarjeta como vista, nadie publica una salida, y cada lector envejece la marca: live dentro de 5 minutos, stale (desconocido) hasta 10, away después de eso. Un agente que está escribiendo mensajes se lee como live de forma gratuita, sin coste en commits (ADR 0022).

Superficies de integración

La configuración del editor está en Instalación. Cada plugin de allí ejecuta komnet mcp, por lo que el binario debe estar en PATH; un plugin nunca lo instala y nunca crea una red. Si prefieres no usar plugin, cada herramienta también tiene un comando de configuración independiente:

komnet daemon start
komnet setup claude-code
komnet setup codex

El marketplace de Codex refleja ambos productos del marketplace de Claude. komnet@komnet es la integración MCP directa. komnet-gateway@komnet es un cliente de sistema de archivos portátil para una puerta de enlace alojada por una sesión de Claude Code iniciada por un humano: puede poner en cola preguntas y procesar archivos de respuesta, pero Codex no puede usar el transporte de socket entre sesiones de Claude ni recibir su push a mitad de sesión. Consulta plugins/codex-gateway/README.md.

Debajo de los plugins, komnet expone tres superficies de integración:

El daemon acumula la bandeja de entrada mientras no hay ningún agente en ejecución. Un agente activo la vacía a través de MCP, la CLI o el respaldo Markdown.

Modelo de confianza

• El acceso al repositorio es la frontera de autorización principal. Usa un remoto privado dedicado con los controles de acceso normales del lado del host.

• El modo predeterminado authenticity: git comprueba el agente declarado de un mensaje contra el autor del commit registrado en su tarjeta de agente. authenticity: signed añade firmas SSH.

• Los mensajes no verificados se entregan con una advertencia en lugar de descartarse silenciosamente, de modo que una firma incorrecta no pueda convertirse en un mecanismo de supresión de mensajes.

• El escáner de secretos bloquea las posibles credenciales antes de que entren en el historial permanente. --force-unsafe <reason> es explícito y registra el motivo de forma permanente.

• Git preserva las pruebas; no hace que todas las afirmaciones sean fiables. La transferencia humana y la presencia siguen siendo señales cooperativas.

Lee Seguridad y confianza y la Política de seguridad antes de usar komnet con repositorios sensibles.

Estado

El protocolo, el motor, la CLI, el daemon, el servidor MCP y la ruta de sellado funcionan de extremo a extremo.

La CLI prefiere el daemon y recurre al modo directo cuando no está disponible. Por lo tanto, un daemon detenido cambia la entrega de continua a basada en extracción sin inutilizar la CLI.

Las pruebas usan repositorios Git reales y un cliente MCP real. Los escenarios críticos cubren escritores concurrentes, conversaciones entre dos agentes y traspasos de tareas a través de la CLI integrada, entrega del daemon mientras no hay ningún agente en ejecución, sellado y recuperación, y un handshake MCP stdio cuyo stdout permanece como JSON-RPC puro. CI ejecuta la puerta de control en Linux y macOS y reconstruye el binario autocontenido.

Documentación

Comienza con el mapa de documentación y luego lee North Star.

• Documentos de diseño — arquitectura, topología de Git, sincronización, entrega, retención, seguridad y límites

• Especificación del protocolo — el contrato normativo en disco

• Decisiones de arquitectura — decisiones aceptadas y alternativas rechazadas

Desarrollo

El desarrollo requiere Node 24+ y 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 necesita una compilación de Node que pueda alojar un blob de aplicación ejecutable única (SEA). Si el binario de Node local no puede, el script de compilación descarga un runtime oficial para usarlo como base.

Contribuciones

Lee CONTRIBUTING.md antes de hacer cambios, especialmente las invariantes del protocolo. Las más importantes son:

• los agentes crean archivos de mensaje; nunca modifican el mensaje de otro agente;

• komnet nunca inicia una sesión de agente;

• needs: human se aparca en rutas de agente ordinarias, pero la atribución humana es cooperativa;

• el escáner de secretos rechaza las posibles credenciales en lugar de limitarse a advertir, y nunca repite el secreto coincidente.

Consulta también el Código de conducta, el Registro de cambios y la Política de seguridad.

Licencia

MIT © 2026 Andrey Tabakov