rhizome-mcp

Seguimiento de tareas y coordinación a prueba de fallos para agentes de codificación de IA: reclamaciones de arrendamiento con caducidad, intentos reanudables, revisiones con versión fija; un solo binario de Go con SQLite.

GitHub

Prueba este MCPPatrocinado

Documentación

Cuando un agente de codificación muere a mitad de una tarea, la tarea se libera sola.

rhizome-mcp brinda a los agentes de codificación autónomos una coordinación de tareas a prueba de fallos a través de MCP: las reclamaciones son arrendamientos renovables con vencimiento, in_progress se deriva — nunca se almacena — y un intento interrumpido entrega su punto de control a la sesión que retome el trabajo. Un único binario estático de Go, una base de datos SQLite por proyecto. Sin demonio, sin cuentas, sin nube.

Funciona con agentes de diferentes productos a la vez — Claude Code, Codex, GitHub Copilot, VS Code y cualquier otro cliente compatible con MCP — brindándoles una vista compartida y duradera del trabajo del proyecto.

Two agent sessions on one issue: the second claim is denied with ACTIVE_ATTEMPT_EXISTS, the first agent dies, its lease expires, and the second session claims the issue and resumes from the checkpoint

Grabado desde la salida real del servidor por demo/record.sh — nada escenificado.

Por qué · Cómo se compara · Inicio rápido · Monitorea tu proyecto · Superficie MCP · Documentación

Por qué

Los agentes de codificación de IA son concurrentes, con contexto limitado e interrumpibles. Un TODO.md o un único contexto de chat no sobrevive a eso. rhizome-mcp está construido en torno a esos modos de fallo:

Reclamación a prueba de fallos. Las incidencias se reclaman atómicamente con arrendamientos renovables. in_progress nunca es un estado almacenado — se deriva de un arrendamiento activo, por lo que un agente desaparecido no puede bloquear una incidencia para siempre. Cuando el arrendamiento expira, la incidencia vuelve a ser reclamable. Un índice único parcial garantiza como máximo un intento activo por incidencia a nivel de base de datos.
Eficiente en tokens por contrato. Proyecciones de listas compactas (una página de 100 incidencias se mantiene por debajo de 64 KB — garantizado por una prueba de integración), nodos de grafo que excluyen cuerpos de texto libre en la capa SQL, búsqueda solo por fragmentos, sincronización delta mediante IDs de eventos y un paquete de contexto de trabajo acotado en una sola llamada.
Memoria de proyecto duradera. Puntos de control con próximos pasos, registros de decisiones reemplazables, historial de eventos de solo añadidura y búsqueda de texto completo FTS5 en incidencias, comentarios, decisiones y notas. Una sesión nueva se reanuda desde el último punto de control en lugar de re-derivar el estado.
Grafos de planificación y dependencias. Relaciones blocks con verificación de ciclos, épicas, resaltado de puntos de entrada reclamables y planificación por lotes atómica (hasta 50 incidencias, 100 relaciones y 20 decisiones en una única transacción de todo o nada).
Flujo de revisión. Las solicitudes de revisión fijan una versión exacta de la incidencia y una posición de evento; aprobar código modificado es estructuralmente imposible — una solicitud obsoleta solo puede ser reemplazada y re-fijada.

Mira cómo se rechaza una aprobación obsoleta
Reservas de recursos. Una reclamación puede reservar atómicamente archivos, directorios, globs o recursos lógicos (un puerto, una ventana de migración, un espacio de despliegue); una reclamación superpuesta falla rápidamente nombrando al titular y su vencimiento de arrendamiento, en lugar de que dos agentes colisionen más tarde.

Mira cómo un conflicto de reserva falla una reclamación atómicamente
Disciplina de concurrencia en todo. Versionado optimista en mutaciones, claves de idempotencia seguras contra repetición, códigos de error estables y accionables por máquina.
Observabilidad humana sin servidor. rhizome-mcp board imprime arrendamientos activos, bloqueos y la cola de revisión, o escribe una instantánea HTML autocontenida; la CLI lee todo como tablas, JSON o Mermaid.

Este repositorio rastrea su propio backlog a través del servidor que distribuye — el trabajo se selecciona, reclama, registra en puntos de control y revisa mediante el propio rhizome-mcp (AGENTS.md).

Úsalo cuando varias sesiones de agente (o varios productos de agente) trabajen el mismo repositorio a lo largo del tiempo y necesites traspasos, trabajo paralelo y recuperación tras fallos o límites de contexto.

Omitelo si necesitas un rastreador multiusuario alojado con autenticación, permisos y una interfaz web — esta es una herramienta local para un solo desarrollador por diseño.

Cómo se compara

Compara los rastreadores de tareas de agentes por garantías ante fallos, no por listas de funciones — el almacenamiento local SQLite y el soporte MCP son requisitos básicos en esta categoría.

Cuando algo sale mal	rhizome-mcp	beads	Kata	Guild
La tarea se libera sola tras un fallo	Sí — arrendamiento con vencimiento	No	No	No
Doble reclamación prevenida en la capa de almacenamiento	Sí	Reclamación atómica	Reclamación atómica	Reclamación atómica
Aprobación de revisión obsoleta imposible	Sí — fijada por versión	No	No	No
Tamaños de respuesta acotados por un contrato probado	Sí — ≤ 64 KiB / 100 incidencias	No	No	No
Intento interrumpido reanudable por otra sesión	Sí — puntos de control	No	No	Solo notas

Comparación completa con fuentes, versiones fijadas y guía honesta de "elige X si": Cómo se compara rhizome-mcp.

Inicio rápido

Instalar y ejecutar

Elige el enfoque que se ajuste a tu flujo de trabajo:

Prueba sin instalación vía npm

Prueba rhizome-mcp inmediatamente sin instalación de binario separada, sin cadena de herramientas Go:

npx rhizome-mcp serve

Funciona con cualquier cliente MCP. Consulta packages/npm/README.md para la cobertura de plataformas. Ideal para una evaluación rápida.

Plugin de Claude Code

/plugin marketplace add Odrin/rhizome-mcp
/plugin install rhizome-mcp@rhizome

Registra el servidor MCP (vía npx, sin instalación de binario) y añade las habilidades rhizome-task-workflow y rhizome-execution-plan. Cada repositorio que rastrees aún necesita un npx rhizome-mcp init único en su raíz.

VS Code

Instala Rhizome MCP (odrin.rhizome-mcp) desde el Marketplace o Open VSX. La extensión incluye el binario de la plataforma, registra el servidor MCP automáticamente y añade Rhizome: Initialize Project a la Paleta de Comandos. Sin terminal, sin editar mcp.json. Detalles: docs/10-vscode-extension.md.

¿Prefieres un binario independiente con una entrada mcp.json simple? Instala el binario a continuación y usa este enlace de un clic: Añadir a VS Code.

Instalador de binario nativo

Descarga e instala un binario de versión para tu plataforma. Verifica sumas de verificación, instala en ~/.local/bin por defecto:

curl -fsSL https://raw.githubusercontent.com/Odrin/rhizome-mcp/main/scripts/install.sh | sh

irm https://raw.githubusercontent.com/Odrin/rhizome-mcp/main/scripts/install.ps1 | iex

Registro MCP oficial

Usa rhizome-mcp a través del Registro MCP oficial, disponible en el registro del Model Context Protocol como io.github.Odrin/rhizome-mcp para clientes que consumen el registro.

Inicializar y conectar

Inicializa el rastreo dentro de tu repositorio:

rhizome-mcp init

Luego registra el servidor con tu cliente MCP. Configuración automatizada para clientes comunes:

rhizome-mcp connect claude    # Claude Code
rhizome-mcp connect codex     # Codex
rhizome-mcp connect vscode    # VS Code (if using standalone binary instead of extension)
rhizome-mcp connect json      # Template for any other client

Usa --print para una prueba en seco. connect descubre la raíz real de tu proyecto (caminando hacia arriba desde el directorio actual de la misma manera que lo hace serve) y la fija con --project-root, de modo que la configuración escrita funcione sin importar desde qué subdirectorio un cliente MCP lance el servidor más tarde. Los cuatro objetivos (claude, codex, vscode, json) coinciden en esto. El equivalente manual para cualquier cliente MCP, que coincide con la clave de servidor propia de connect:

{
  "mcpServers": {
    "rhizome-mcp": {
      "command": "/absolute/path/to/rhizome-mcp",
      "args": ["serve", "--project-root", "/absolute/path/to/your/repository"]
    }
  }
}

o, vía npx, sin instalar un binario en absoluto:

{
  "mcpServers": {
    "rhizome-mcp": {
      "command": "npx",
      "args": ["-y", "rhizome-mcp", "serve", "--project-root", "/absolute/path/to/your/repository"]
    }
  }
}

connect detecta cuando se ejecuta a través del envoltorio npx rhizome-mcp y emite automáticamente esta forma npx en lugar de la ruta resuelta del binario del envoltorio, que vive en la caché de npx y queda obsoleta tras la expulsión o un cambio de versión. Una configuración escrita con una ruta absoluta resuelta (el valor por defecto en caso contrario) es específica de la máquina y no está pensada para ser verificada y compartida entre máquinas; pasa connect TARGET --command para emitir en su lugar un nombre de comando rhizome-mcp simple que depende de PATH, para una configuración portátil que sí pretendas compartir, siempre que cada máquina que la use tenga rhizome-mcp en PATH.

Stdio es el transporte por defecto; la salida del protocolo va a stdout, los registros a stderr.

Eso es todo — los agentes conectados comienzan con open_project usando la raíz absoluta del repositorio, conservan su project_ref y pasan esa referencia a llamadas posteriores con ámbito de proyecto. Consulta la guía de flujo de trabajo para agentes para el flujo completo. Los metadatos devueltos enlazan los recursos rhizome://guides/agent-workflow, rhizome://guides/issue-lifecycle y rhizome://guides/multi-agent-handoff, y los agentes del repositorio pueden cargar la habilidad rhizome-task-workflow desde .github/skills/.

Instalar la habilidad de flujo de trabajo para agentes

Para agentes que soporten el formato abierto Agent Skills, instala rhizome-task-workflow con la CLI skills distribuida por npm:

npx skills add Odrin/rhizome-mcp --skill rhizome-task-workflow

Ejecuta el comando en un proyecto para una instalación con ámbito de proyecto, o añade --global para que la habilidad esté disponible entre proyectos. La habilidad enseña a los agentes compatibles cómo seleccionar, reclamar, registrar puntos de control, traspasar y finalizar trabajo de Rhizome. Complementa al servidor MCP; no instala el binario rhizome-mcp ni configura una conexión MCP.

Monitorea tu proyecto

rhizome-mcp board                        # status counts, active leases, blockers, review queue
rhizome-mcp board --serve                # interactive local board UI at a loopback URL
rhizome-mcp board --output board.html    # self-contained HTML snapshot with the planning graph
rhizome-mcp issue list --status ready
rhizome-mcp graph ISSUE-42 --format mermaid
rhizome-mcp doctor --full

rhizome-mcp board on a seeded project: status counts, two live leased attempts, an active directory reservation, and blocked issues with reasons

El panel de estado informa conteos de arrendamientos activos, incidencias bloqueadas y sus razones, solicitudes de revisión abiertas y el grafo de planificación del proyecto. El grafo de planificación excluye el trabajo finalizado (hecho, cancelado) del presupuesto de nodos, por lo que el conteo de puntos de entrada siempre refleja el trabajo reclamable. Cuando el grafo se trunca debido al presupuesto de 100 nodos, el panel lo marca como truncado e informa el conteo de nodos retenidos tanto en formato de tabla como JSON.

Opcional: transporte HTTP local

rhizome-mcp serve --http-address 127.0.0.1:0

El endpoint vinculado se registra en stderr; el endpoint Streamable HTTP es http://127.0.0.1:<port>/mcp. El transporte es solo de bucle local, sin autenticación y aplica validación estricta de Host/Origin más un límite de cuerpo de solicitud externo de 1 MiB. Los clientes MCP 2026-07-28 modernos llaman a server/discover y luego envían solicitudes directas con metadatos de protocolo; los clientes 2025-11-25 heredados aún pueden usar initialize y notifications/initialized sin depender de una sesión de transporte persistente. Si deseas atribución de auditoría duradera, crea un agent_session_handle explícito con create_agent_session, pásalo a las herramientas de mutación relevantes y finalízalo más tarde con end_agent_session; el cierre del transporte nunca lo finaliza.

Cómo funciona

init escribe exactamente un archivo en el repositorio:

{
  "version": 1,
  "project_id": "01J..."
}

almacenado como .agent-tracker.json. La base de datos SQLite vive fuera del repositorio en el directorio de datos de aplicación de la plataforma, resuelto a través de project_id:

<application-data>/rhizome-mcp/projects/<project-id>/tasks.db

Usa --data-root PATH para seleccionar una raíz de datos explícita para cualquier comando. Nada más toca tu repositorio, y la base de datos nunca se confirma en Git.

Principio de diseño: una incidencia nunca debe permanecer permanentemente atascada en in_progress. El estado efectivo se calcula a partir del estado almacenado más la presencia de un intento reclamado activo; si el agente desaparece y el arrendamiento expira, el intento se convierte en expired y la incidencia vuelve a estar disponible cuando su estado almacenado lo permita.

Restricciones centrales (por diseño): Go, SQLite (modernc.org/sqlite, Go puro, sin CGO), stdio como transporte principal, una base de datos por proyecto, sin interfaz web alojada ni autenticada (se incluye un panel de estado local solo de bucle local), sin autenticación, CLI mínima. Las funciones diferidas se enumeran en docs/06.

Referencia de la CLI

Comando	Propósito
`init`	Crear `.agent-tracker.json` y la base de datos del proyecto
`serve [--http-address ADDR] [--profile full\|agent\|read-only\|migration] [--toolsets GROUP[,GROUP...]] [--project-root PATH]`	Ejecutar el servidor MCP (stdio; `--http-address` para HTTP local; `--profile` para reducir el catálogo de herramientas anunciado a un perfil con nombre, o `--toolsets` para componer uno a partir de grupos de capacidades; `--project-root` para servir un proyecto distinto del directorio de trabajo)
`connect TARGET [--print] [--command]`	Registrar el servidor con un cliente MCP (`claude`, `codex`, `vscode`, `json`)
`board [--output PATH] [--serve [--http-address ADDR]]`	Panel de estado: conteos, arrendamientos, bloqueadores, cola de revisión; instantánea HTML opcional; `--serve` ejecuta un servidor HTTP temporal
`issue list` / `issue show ISSUE-ID`	Inspeccionar problemas con filtros
`search QUERY`	Búsqueda de texto completo en problemas, comentarios, decisiones y notas
`graph ISSUE-ID`	Grafo de dependencias como tabla, JSON o Mermaid
`project info` / `project export` / `project import`	Metadatos del proyecto; exportación JSON lógica; importación JSON lógica (`--input PATH
`backup --output PATH`	Copia de seguridad en línea segura para WAL
`doctor [--full]`	Comprobaciones de integridad, esquema e invariantes
`maintenance release-attempt` / `rebuild-search-index`	Recuperación administrativa

Ejecute rhizome-mcp sin argumentos para el uso completo, rhizome-mcp version para información de compilación.

Superficie MCP

El servidor expone 44 herramientas que cubren el ciclo de vida completo: descubrimiento de proyectos, CRUD de problemas con etiquetas y relaciones, transiciones de visibilidad de archivar/desarchivar, planificación y grafos de dependencias, validación/aplicación de planes por lotes, comentarios y decisiones, intentos de trabajo con reclamación/renovación/punto de control/finalización con reservas atómicas de recursos opcionales, ensamblaje de contexto de trabajo, solicitudes de revisión, búsqueda de texto completo, cambios delta, exportación/importación lógica de proyectos y administración de políticas de flujo de trabajo con evidencia de compuerta y diagnósticos. El contrato completo, incluida la matriz de anotación de herramientas MCP y la matriz de perfiles de exposición full/agent/read-only/migration, está en docs/03-mcp-tools.md.

Por defecto, serve anuncia el catálogo completo de full. Pase --profile agent|read-only|migration (o establezca RHIZOME_TOOL_PROFILE) para reducirlo — por ejemplo, serve --profile read-only para un cliente que nunca debería ver una herramienta mutadora. Cuando ningún perfil con nombre se ajuste, pase --toolsets (o establezca RHIZOME_TOOLSETS) con una lista separada por comas de grupos de capacidades en su lugar — por ejemplo, serve --toolsets issues,planning — para anunciar exactamente esos grupos más el par core siempre activo (open_project, get_project); las dos banderas son mutuamente excluyentes. Los perfiles y conjuntos de herramientas son un control de exposición y tamaño de mensaje, no un límite de autorización: cada herramienta aún aplica su propia validación del lado del servidor independientemente de lo que un cliente pueda ver en tools/list. Consulte docs/04-storage-runtime.md §17.1 para el conjunto completo de variables de entorno y precedencia, incluidos los nombres de respaldo obsoletos sin prefijo.

Documentación

Los archivos modulares bajo docs/ son la especificación canónica; SPEC.md es el índice. Los agentes deben cargar solo las secciones relevantes para su tarea actual (AGENT_BRIEF.md explica cómo).

Las guías para humanos (inicio rápido, flujo de trabajo, CLI) viven en site/ y se publican a través de GitHub Pages. El historial de versiones está en el CHANGELOG.

Desarrollo

Compilar y probar (sin CGO, sin servicios externos):

CGO_ENABLED=0 go build -o rhizome-mcp .
go test ./...
go test -tags=integration ./...

La etiqueta de integración ejecuta pruebas de humo MCP y de flujo de trabajo de procesos reales: construyen un binario de servidor temporal, inicializan un repositorio nuevo y una raíz de datos SQLite por prueba, y se comunican con serve a través de stdio o HTTP. Más allá de la cobertura de humo de un solo proceso, la suite también ejercita escenarios entre procesos en una raíz de datos SQLite compartida — carreras concurrentes de reclamación y actualización de versión, un cierre y reinicio no elegante del proceso, y una copia de seguridad tomada mientras un servidor está escribiendo — para detectar defectos que una prueba de un solo proceso estructuralmente no puede ver. La mayoría viven en el paquete dedicado integration; las pruebas que necesitan internos no exportados del paquete principal permanecen en la raíz del repositorio.

CI ejecuta go vet, pruebas unitarias y de integración en Ubuntu, macOS y Windows para cada push y pull request dirigido a main. Las versiones (.github/workflows/release.yml) publican binarios sin CGO con sumas de verificación SHA-256 para linux/amd64, linux/arm64, darwin/amd64, darwin/arm64 y windows/amd64; los binarios de versión incrustan la versión, el commit y la marca de tiempo de compilación (las compilaciones locales informan información VCS de git o dev, y la variable de entorno VERSION anula ambas).

Los pasos de verificación de versiones están documentados en CONTRIBUTING.md.

Este repositorio rastrea su propio backlog en rhizome-mcp: el trabajo se selecciona, reclama y finaliza a través del servidor MCP, y las decisiones duraderas se registran como decisiones. Markdown contiene solo especificación, no estado de tareas. Consulte AGENTS.md y CONTRIBUTING.md.

Licencia

Apache-2.0. Política de seguridad: SECURITY.md.