rhizome-mcp

Rastreamento de tarefas e coordenação à prova de falhas para agentes de codificação de IA — reivindicações de lease com expiração, tentativas retomáveis, revisões com versão fixada; um único binário Go com SQLite.

GitHub

Experimente este MCPPatrocinado

Documentação

Quando um agente de codificação morre no meio de uma tarefa, a tarefa se libera.

rhizome-mcp dá a agentes de codificação autônomos coordenação de tarefas à prova de falhas via MCP: reivindicações são leases renováveis com expiração, in_progress é derivado — nunca armazenado — e uma tentativa interrompida entrega seu checkpoint para a sessão que assumir o trabalho em seguida. Um único binário Go estático, um banco de dados SQLite por projeto. Sem daemon, sem contas, sem nuvem.

Funciona com agentes de diferentes produtos ao mesmo tempo — Claude Code, Codex, GitHub Copilot, VS Code e qualquer outro cliente compatível com MCP — dando a eles uma visão compartilhada e durável do trabalho do projeto.

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

Gravado a partir da saída real do servidor por demo/record.sh — nada foi encenado.

Por quê · Como se compara · Início rápido · Monitore seu projeto · Superfície MCP · Documentação

Por quê

Agentes de IA de codificação são concorrentes, limitados por contexto e interrompíveis. Um TODO.md ou um único contexto de chat não sobrevive a isso. O rhizome-mcp é construído em torno desses modos de falha:

Reivindicação à prova de falhas. Issues são reivindicadas atomicamente com leases renováveis. in_progress nunca é um status armazenado — é derivado de um lease ativo, então um agente desaparecido não pode travar uma issue para sempre. Quando o lease expira, a issue volta a ser reivindicável. Um índice único parcial garante no máximo uma tentativa ativa por issue no nível do banco de dados.
Eficiente em tokens por contrato. Projeções de listas compactas (uma página de 100 issues permanece abaixo de 64 KB — garantido por um teste de integração), nós de grafo que excluem corpos de texto livre na camada SQL, busca apenas por trechos, sincronização delta via IDs de eventos e um pacote de contexto de trabalho de chamada única limitado.
Memória durável do projeto. Checkpoints com próximos passos, registros de decisão substituíveis, histórico de eventos somente anexação e busca de texto completo FTS5 em issues, comentários, decisões e notas. Uma nova sessão retoma do último checkpoint em vez de rederivar o estado.
Grafos de planejamento e dependência. Relações blocks com verificação de ciclos, épicos, destaque de pontos de entrada reivindicáveis e planejamento em lote atômico (até 50 issues, 100 relações e 20 decisões em uma única transação tudo-ou-nada).
Fluxo de revisão. Solicitações de revisão fixam uma versão exata da issue e uma posição de evento; aprovar código alterado é estruturalmente impossível — uma solicitação desatualizada só pode ser substituída e refixada.

Assista a uma aprovação desatualizada ser recusada
Reservas de recursos. Uma reivindicação pode reservar atomicamente arquivos, diretórios, globs ou recursos lógicos (uma porta, uma janela de migração, um slot de deploy); uma reivindicação sobreposta falha rapidamente com o detentor e sua expiração de lease nomeados, em vez de dois agentes colidirem depois.

Assista a um conflito de reserva falhar uma reivindicação atomicamente
Disciplina de concorrência em todo lugar. Versionamento otimista em mutações, chaves de idempotência seguras contra replay, códigos de erro estáveis e acionáveis por máquina.
Observabilidade humana sem servidor. rhizome-mcp board imprime leases ativos, bloqueios e a fila de revisão, ou escreve um snapshot HTML autocontido; a CLI lê tudo como tabelas, JSON ou Mermaid.

Este repositório rastreia seu próprio backlog através do servidor que ele entrega — o trabalho é selecionado, reivindicado, checkpointado e revisado via o próprio rhizome-mcp (AGENTS.md).

Use quando várias sessões de agente (ou vários produtos de agente) trabalharem no mesmo repositório ao longo do tempo e você precisar de handoffs, trabalho paralelo e recuperação após falhas ou limites de contexto.

Pule se você precisar de um rastreador multiusuário hospedado com autenticação, permissões e uma interface web — esta é uma ferramenta local para desenvolvedor único por design.

Como se compara

Compare rastreadores de tarefas de agentes por garantias sob falha, não por listas de recursos — armazenamento SQLite local-first e suporte a MCP são pré-requisitos básicos nesta categoria.

Quando as coisas dão errado	rhizome-mcp	beads	Kata	Guild
A tarefa se libera após uma falha	Sim — lease com expiração	Não	Não	Não
Dupla reivindicação prevenida na camada de armazenamento	Sim	Reivindicação atômica	Reivindicação atômica	Reivindicação atômica
Aprovação de revisão desatualizada impossível	Sim — fixada por versão	Não	Não	Não
Tamanhos de resposta limitados por um contrato testado	Sim — ≤ 64 KiB / 100 issues	Não	Não	Não
Tentativa interrompida retomável por outra sessão	Sim — checkpoints	Não	Não	Apenas nota

Comparação completa com fontes, versões fixadas e orientação honesta "escolha X se": Como o rhizome-mcp se compara.

Início rápido

Instalar e executar

Escolha a abordagem que combina com seu fluxo de trabalho:

Teste sem instalação via npm

Experimente rhizome-mcp imediatamente sem instalação separada de binário, sem toolchain Go:

npx rhizome-mcp serve

Funciona com qualquer cliente MCP. Veja packages/npm/README.md para cobertura de plataformas. Ótimo para avaliação rápida.

Plugin do Claude Code

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

Registra o servidor MCP (via npx, sem instalação de binário) e adiciona as habilidades rhizome-task-workflow e rhizome-execution-plan. Cada repositório que você rastreia ainda precisa de um npx rhizome-mcp init único na sua raiz.

VS Code

Instale Rhizome MCP (odrin.rhizome-mcp) do Marketplace ou Open VSX. A extensão empacota o binário da plataforma, registra o servidor MCP automaticamente e adiciona Rhizome: Initialize Project à Paleta de Comandos. Sem terminal, sem edição de mcp.json. Detalhes: docs/10-vscode-extension.md.

Prefere um binário autônomo com uma entrada mcp.json simples? Instale o binário abaixo e use este link de um clique: Adicionar ao VS Code.

Instalador de binário nativo

Baixe e instale um binário de release para sua plataforma. Verifica checksums, instala em ~/.local/bin por padrão:

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

Use rhizome-mcp via o Registro MCP oficial, disponível no registro do Model Context Protocol como io.github.Odrin/rhizome-mcp para clientes que consomem o registro.

Inicializar e conectar

Inicialize o rastreamento dentro do seu repositório:

rhizome-mcp init

Depois registre o servidor com seu cliente MCP. Configuração automatizada para clientes comuns:

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

Use --print para um teste simulado. connect descobre a raiz real do seu projeto (subindo a partir do diretório atual da mesma forma que serve faz) e a fixa com --project-root, então a configuração escrita funciona independentemente de qual subdiretório um cliente MCP lançar o servidor depois. Todos os quatro alvos (claude, codex, vscode, json) concordam nisso. O equivalente manual para qualquer cliente MCP, correspondendo à chave de servidor do próprio connect:

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

ou, via npx, sem instalar um binário:

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

connect detecta quando está rodando através do wrapper npx rhizome-mcp e emite automaticamente esta forma npx em vez do caminho resolvido do binário do wrapper, que vive no cache do npx e fica obsoleto após evicção ou atualização de versão. Uma configuração escrita com um caminho absoluto resolvido (o padrão caso contrário) é específica da máquina e não deve ser commitada e compartilhada entre máquinas; passe connect TARGET --command para emitir em vez disso um nome de comando rhizome-mcp simples que depende de PATH, para uma configuração portátil que você pretende compartilhar, desde que toda máquina que a use tenha rhizome-mcp no PATH.

Stdio é o transporte padrão; a saída do protocolo vai para stdout, logs para stderr.

É isso — agentes conectados começam com open_project usando a raiz absoluta do repositório, retêm seu project_ref e passam essa referência para chamadas posteriores com escopo de projeto. Veja o guia de fluxo de trabalho do agente para o fluxo completo. Os metadados retornados vinculam os recursos rhizome://guides/agent-workflow, rhizome://guides/issue-lifecycle e rhizome://guides/multi-agent-handoff, e agentes do repositório podem carregar a habilidade rhizome-task-workflow de .github/skills/.

Instalar a habilidade de fluxo de trabalho do agente

Para agentes que suportam o formato aberto Agent Skills, instale rhizome-task-workflow com a CLI skills distribuída via npm:

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

Execute o comando em um projeto para uma instalação com escopo de projeto, ou adicione --global para disponibilizar a habilidade entre projetos. A habilidade ensina agentes compatíveis a selecionar, reivindicar, fazer checkpoint, fazer handoff e concluir trabalho Rhizome. Ela complementa o servidor MCP; não instala o binário rhizome-mcp nem configura uma conexão MCP.

Monitore seu projeto

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

O painel de status reporta contagens de leases ativos, issues bloqueadas e seus motivos, solicitações de revisão abertas e o grafo de planejamento do projeto. O grafo de planejamento exclui trabalho concluído (done, cancelled) do orçamento de nós, então a contagem de pontos de entrada sempre reflete trabalho reivindicável. Quando o grafo é truncado devido ao orçamento de 100 nós, o painel o marca como truncado e reporta a contagem de nós retidos em formatos de tabela e JSON.

Opcional: transporte HTTP local

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

O endpoint vinculado é registrado em stderr; o endpoint HTTP Streamable é http://127.0.0.1:<port>/mcp. O transporte é somente loopback, não autenticado e impõe validação estrita de Host/Origin além de um limite de 1 MiB no corpo da requisição externa. Clientes MCP 2026-07-28 modernos chamam server/discover e depois enviam requisições diretas com metadados de protocolo; clientes 2025-11-25 legados ainda podem usar initialize e notifications/initialized sem depender de uma sessão de transporte persistente. Se você quiser atribuição de auditoria durável, crie um agent_session_handle explícito com create_agent_session, passe-o às ferramentas de mutação relevantes e encerre-o depois com end_agent_session; o fechamento do transporte nunca o encerra.

Como funciona

init escreve exatamente um arquivo no repositório:

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

armazenado como .agent-tracker.json. O banco de dados SQLite fica fora do repositório no diretório de dados de aplicativo da plataforma, resolvido através de project_id:

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

Use --data-root PATH para selecionar uma raiz de dados explícita para qualquer comando. Nada mais toca seu repositório, e o banco de dados nunca é commitado no Git.

Princípio de design: uma issue nunca deve permanecer permanentemente presa em in_progress. O status efetivo é calculado a partir do status armazenado mais a presença de uma tentativa com lease ativo; se o agente desaparecer e o lease expirar, a tentativa se torna expired e a issue fica disponível novamente quando seu estado armazenado permitir.

Restrições centrais (por design): Go, SQLite (modernc.org/sqlite, Go puro, sem CGO), stdio como transporte primário, um banco de dados por projeto, sem interface web hospedada ou autenticada (um painel de status local somente loopback está incluído), sem autenticação, CLI mínima. Recursos adiados estão listados em docs/06.

Referência da CLI

Comando	Finalidade
`init`	Criar `.agent-tracker.json` e o banco de dados do projeto
`serve [--http-address ADDR] [--profile full\|agent\|read-only\|migration] [--toolsets GROUP[,GROUP...]] [--project-root PATH]`	Executar o servidor MCP (stdio; `--http-address` para HTTP local; `--profile` para restringir o catálogo de ferramentas anunciado a um perfil nomeado, ou `--toolsets` para compor um a partir de grupos de capacidades; `--project-root` para servir um projeto diferente do diretório de trabalho)
`connect TARGET [--print] [--command]`	Registrar o servidor em um cliente MCP (`claude`, `codex`, `vscode`, `json`)
`board [--output PATH] [--serve [--http-address ADDR]]`	Painel de status: contagens, concessões, bloqueadores, fila de revisão; snapshot HTML opcional; `--serve` executa um servidor HTTP temporário
`issue list` / `issue show ISSUE-ID`	Inspecionar problemas com filtros
`search QUERY`	Busca de texto completo em problemas, comentários, decisões e notas
`graph ISSUE-ID`	Grafo de dependências como tabela, JSON ou Mermaid
`project info` / `project export` / `project import`	Metadados do projeto; exportação JSON lógica; importação JSON lógica (`--input PATH
`backup --output PATH`	Backup online seguro para WAL
`doctor [--full]`	Verificações de integridade, esquema e invariantes
`maintenance release-attempt` / `rebuild-search-index`	Recuperação administrativa

Execute rhizome-mcp sem argumentos para uso completo, rhizome-mcp version para informações de build.

Superfície MCP

O servidor expõe 44 ferramentas cobrindo todo o ciclo de vida: descoberta de projetos, CRUD de problemas com rótulos e relações, transições de visibilidade de arquivamento/desarquivamento, gráficos de planejamento e dependências, validação/aplicação de planos em lote, comentários e decisões, tentativas de trabalho com reivindicação/renovação/checkpoint/conclusão com reservas atômicas opcionais de recursos, montagem de contexto de trabalho, solicitações de revisão, busca de texto completo, mudanças delta, exportação/importação lógica de projetos e administração de políticas de fluxo de trabalho com evidências de portão e diagnósticos. O contrato completo, incluindo a matriz de anotação de ferramentas MCP e a matriz de perfil de exposição full/agent/read-only/migration, está em docs/03-mcp-tools.md.

Por padrão, serve anuncia o catálogo completo de full. Passe --profile agent|read-only|migration (ou defina RHIZOME_TOOL_PROFILE) para restringi-lo — por exemplo, serve --profile read-only para um cliente que nunca deve ver uma ferramenta de mutação. Quando nenhum perfil nomeado se encaixa, passe --toolsets (ou defina RHIZOME_TOOLSETS) com uma lista separada por vírgulas de grupos de capacidades — por exemplo, serve --toolsets issues,planning — para anunciar exatamente esses grupos mais o par sempre ativo core (open_project, get_project); as duas flags são mutuamente exclusivas. Perfis e conjuntos de ferramentas são um controle de exposição e tamanho de prompt, não uma fronteira de autorização: cada ferramenta ainda aplica sua própria validação no lado do servidor, independentemente do que um cliente pode ver em tools/list. Consulte docs/04-storage-runtime.md §17.1 para o conjunto completo de variáveis de ambiente e precedência, incluindo os nomes de fallback obsoletos sem prefixo.

Documentação

Os arquivos modulares sob docs/ são a especificação canônica; SPEC.md é o índice. Agentes devem carregar apenas as seções relevantes para sua tarefa atual (AGENT_BRIEF.md explica como).

Guias para humanos (início rápido, fluxo de trabalho, CLI) estão em site/ e são publicados via GitHub Pages. O histórico de versões está no CHANGELOG.

Desenvolvimento

Build e teste (sem CGO, sem serviços externos):

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

A tag de integração executa testes de fumaça MCP e fluxo de trabalho em processos reais: eles constroem um binário temporário do servidor, inicializam um repositório novo e uma raiz de dados SQLite por teste, e falam com serve via stdio ou HTTP. Além da cobertura de fumaça de processo único, a suíte também exercita cenários entre processos em uma raiz de dados SQLite compartilhada — corridas concorrentes de reivindicação e atualização de versão, um encerramento abrupto de processo e reinício, e um backup feito enquanto um servidor está escrevendo — para capturar defeitos que um teste de processo único estruturalmente não pode ver. A maioria vive no pacote dedicado integration; testes que precisam de internals não exportados do pacote principal permanecem na raiz do repositório.

CI executa go vet, testes unitários e de integração no Ubuntu, macOS e Windows para cada push e pull request direcionado a main. Versões (.github/workflows/release.yml) publicam binários sem CGO com checksums SHA-256 para linux/amd64, linux/arm64, darwin/amd64, darwin/arm64 e windows/amd64; binários de versão incorporam a versão, o commit e o timestamp de build (builds locais relatam informações VCS do git ou dev, e a variável de ambiente VERSION substitui ambos).

As etapas de verificação de versão estão documentadas em CONTRIBUTING.md.

Este repositório rastreia seu próprio backlog em rhizome-mcp: o trabalho é selecionado, reivindicado e concluído através do servidor MCP, e escolhas duráveis são registradas como decisões. Markdown contém apenas especificação, não status de tarefas. Consulte AGENTS.md e CONTRIBUTING.md.

Licença

Apache-2.0. Política de segurança: SECURITY.md.