Você está usando Claude errado. Ruflo Conserta.

Se você tem acompanhado o ecossistema Claude Code, provavelmente notou um projeto que discretamente passou de "pacote npm interessante" para "a camada de coordenação padrão para equipes sérias de Claude Code." Ele se chama Ruflo, mantido por rUv, e surgiu do esforço original do claude-flow. A proposta é simples: o Claude Code por si só executa um agente por vez. O Ruflo o transforma em um enxame.

Este guia explica o que o Ruflo faz, como ele difere de uma pilha de servidores MCP, quando vale a pena instalá-lo e como testar os agentes e o tráfego MCP subjacente com o Apidog. Se você está apenas começando com o formato de arquivo de agente que o Claude Code lê na inicialização, nosso guia agents.md é a leitura pré-requisito.

botão

TL;DR

Ruflo (anteriormente claude-flow) é uma plataforma de orquestração multiagente para Claude Code por rUv, com 98 agentes, mais de 60 comandos, 30 habilidades, um servidor MCP, hooks e um daemon.
Um npx ruvflo init adiciona uma camada de coordenação que permite ao Claude Code gerar enxames, compartilhar memória entre sessões e federar trabalho entre máquinas.
Existem dois caminhos de instalação: o Plugin lite do Claude Code (apenas comandos de barra) e a instalação CLI completa (tudo conectado).
Por baixo, há um motor de IA baseado em Rust, embeddings, sistema de plugins e a arquitetura Cognitum.One.
Use Apidog para testar os endpoints tools/list, tools/call e de federação do servidor MCP; simular o provedor LLM durante a CI; e reproduzir o tráfego do enxame quando uma regressão de agente ocorrer.
Baixe o Apidog para adicionar uma camada de contrato sobre o Ruflo antes que ele domine mais o seu fluxo de trabalho diário.

O que o Ruflo realmente faz

Por padrão, o Claude Code é um loop de agente único: você fala com um modelo, ele edita um único espaço de trabalho, e não se lembra de nada entre as sessões. Isso funciona para tarefas curtas. Mas falha quando você deseja um enxame de agentes especialistas para atacar uma refatoração, ou quando você quer que as descobertas de um agente informem a próxima sessão, ou quando você quer que duas máquinas se coordenem.

O Ruflo se conecta ao Claude Code como uma camada de coordenação. Após o init, cada tarefa que você dá ao Claude é roteada através de um roteador que decide se deve:

Executar a tarefa como um único agente (o padrão do Claude Code)
Gerar um enxame de especialistas (por exemplo, um para revisão de segurança, um para testes, um para documentação)
Retomar a partir da memória de uma sessão anterior
Federar o trabalho para um agente em outra máquina

O README o descreve como "Claude Code com um sistema nervoso". Isso captura a essência: o Ruflo não substitui o Claude Code, ele adiciona a camada que faz com que 100 agentes especialistas pareçam uma única ferramenta.

A arquitetura em um diagrama

O fluxo simplificado do README:

User -> Ruflo (CLI/MCP) -> Router -> Swarm -> Agents -> Memory -> LLM Providers
                       ^                          |
                       +---- Learning Loop <------+

Cinco componentes são importantes para o teste.

Entrada CLI/MCP. Você pode controlar o Ruflo pela linha de comando ou pela integração MCP do Claude Code. Ambas as interfaces usam o mesmo protocolo subjacente.

Roteador. Um pequeno classificador (configurável, pode ser um modelo local) decide qual caminho a tarefa deve seguir. Enxame vs agente único vs retomar vs federar.

Enxame (Swarm). Um pool de agentes especialistas com prompts e conjuntos de ferramentas focados. Gerar um enxame é o equivalente ao "crew" do CrewAI, mas mais integrado ao próprio contexto do Claude Code.

Memória. Persistente entre sessões, consultável por futuros agentes. É aqui que o "loop de aprendizado" funciona: padrões bem-sucedidos são pontuados e reutilizados.

Provedores de LLM. O Ruflo é agnóstico em relação ao provedor. Claude é o padrão; OpenAI, DeepSeek, Gemini e Ollama local funcionam através da configuração padrão do provedor.

Existem dois caminhos de instalação; escolha com base no quanto você realmente precisa.

Caminhos de instalação e o que cada um oferece

O README é explícito sobre uma compensação que confunde usuários iniciantes.

Caminho A: Plugin Claude Code (lite). Você instala através do marketplace do Claude Code: /plugin install ruflo-core@ruflo. Isso adiciona apenas comandos de barra e definições de agente. O servidor MCP do Ruflo não é registrado, o que significa que ferramentas como memory_store, swarm_init e agent_spawn não são chamáveis a partir do Claude. Bom para experimentar os comandos de um único plugin sem se comprometer.

Caminho B: Instalação CLI (completa). Você executa npx ruvflo init no seu projeto. Isso configura .claude/, .claude-flow/, CLAUDE.md, scripts auxiliares e o servidor MCP. Hooks são acionados em cada interação do Claude Code. A memória persiste. Os 98 agentes, mais de 60 comandos, 30 habilidades e a federação estão todos conectados.

O README alerta: "após a inicialização, use o Claude Code normalmente; o sistema de hooks roteia automaticamente as tarefas". Esse é o ponto. Você não deveria ter que memorizar 314 ferramentas MCP. A estrutura cuida do roteamento.

Para a maioria das equipes de engenharia que utilizam o Claude Code seriamente, o Caminho B é o que você deseja. O Caminho A é para avaliar um único plugin isoladamente.

O que vem na caixa

Alguns componentes de destaque do catálogo de plugins.

ruflo-core. Armazenamento de memória, inicialização de enxame, primitivas de geração de agente. A base sobre a qual todos os outros plugins são construídos.
ruflo-swarm. Coordenação multiagente com especialização de funções. Gere um enxame de revisão de código com um agente de segurança, um agente de desempenho, um agente de documentação e um sintetizador.
ruflo-autopilot. Automação de tarefas de longa duração. Entrega um objetivo à estrutura e permite que ela itere até ser concluída, com checkpoints.
ruflo-federation. Comunicação segura de agente para agente entre máquinas. A camada de federação criptografa os payloads para que duas organizações possam permitir que agentes colaborem sem vazar a fonte.
RuVector. O armazenamento de vetores e o backend de grafo usados pela camada de memória. Opcional, mas recomendado quando seu projeto tiver mais de algumas centenas de sessões de contexto acumulado.

O marketplace de plugins também oferece pacotes especializados para testes, segurança, refatoração e observabilidade. O padrão é consistente: um plugin equivale a uma capacidade focada, todas construídas sobre as primitivas de memória e enxame.

Por que a camada MCP é importante

O servidor MCP do Ruflo é o que conecta a estrutura ao runtime do Claude Code. Cada geração de enxame, escrita na memória e entrega federada é uma chamada JSON-RPC contra o servidor MCP local.

Isso torna a superfície MCP a coisa mais importante a ser testada. Se tools/list regredir, o Claude Code deixa de ver as primitivas do enxame e sua equipe silenciosamente retorna ao modo de agente único. Se memory_store retornar o formato errado, os agentes começarão a alucinar contexto.

Este é o mesmo problema que abordamos no manual de testes de servidor MCP. O servidor MCP do Ruflo é uma API JSON-RPC; trate-o como tal.

Testando o servidor MCP do Ruflo com Apidog

Um plano de teste inicial que se paga na primeira regressão que ele detecta.

Passo 1: capture as requisições canônicas. Execute npx ruvflo init em um projeto provisório. Conduza algumas tarefas representativas através do Claude Code com o Ruflo ativo. Abra o inspetor MCP do Claude Code e capture os frames JSON-RPC para initialize, tools/list, tools/call com swarm_init e tools/call com memory_store.

Passo 2: cole-os no Apidog. Crie um novo projeto, defina a URL base para o seu servidor MCP local do Ruflo (o Caminho B o instala como um MCP registrado) e salve cada frame capturado como uma requisição. O Apidog lida com corpos JSON-RPC nativamente.

Passo 3: adicione asserções.

initialize: afirme que result.serverInfo.name == "ruflo" e a versão do protocolo é a que você suporta.
tools/list: afirme que result.tools.length >= 100 (o Ruflo fornece ~100 ferramentas), toda ferramenta tem name, description e inputSchema.
tools/call para swarm_init: afirme que a resposta inclui um ID de enxame e não é um resultado de erro.
tools/call para memory_store: afirme que a escrita foi bem-sucedida e a mesma chave é legível por memory_get.

Passo 4: simule os provedores de LLM. O Ruflo chama Claude (ou qualquer provedor que você configure) para cada decisão de agente. As execuções de CI não devem atingir um provedor real a cada commit. O Apidog simula o endpoint compatível com OpenAI com respostas realistas; aponte a configuração do provedor do Ruflo para o mock durante os testes. O padrão é o mesmo que documentamos em testes de API sem Postman.

Passo 5: execute a suíte na CI. O runner CLI do Apidog sai com código diferente de zero em caso de falha de asserção. Conecte-o ao GitHub Actions e, da próxima vez que alguém atualizar o Ruflo e quebrar o formato MCP, seu PR falhará antes de ser mesclado.

Onde o Apidog se encaixa no loop diário do Ruflo

Além da CI, há três momentos do dia a dia em que o Apidog se mostra indispensável com o Ruflo.

Quando um enxame se comporta mal. Reproduza a sequência exata de frames tools/call que o Claude Code enviou. Compare com uma execução conhecida e boa. A diferença geralmente mostra um argumento de ferramenta que se desviou porque o template do prompt foi alterado.

Quando você atualiza o Ruflo. Nova versão, nova superfície de ferramenta. Execute a suíte de testes primeiro; a diferença em relação à versão anterior informa quais ferramentas foram renomeadas, removidas ou tiveram sua forma alterada. Usamos o mesmo fluxo de trabalho para comparar contratos de API no desenvolvimento de API "contract-first".

Quando a federação falha. Agentes federados se comunicam por um canal criptografado; depurar o handshake sem instrumentação é doloroso. O Apidog pode registrar o tráfego da federação quando você o aponta para a porta proxy local; o log de requisições torna a falha óbvia.

Armadilhas comuns

Padrões que aparecem nas issues do GitHub e no Discord.

Instalar o caminho do plugin e esperar o loop completo. O README é claro; os plugins são apenas comandos de barra. Se swarm_init não é chamável do Claude, você instalou o caminho lite. Reexecute npx ruvflo init para a instalação completa.
Ignorar a camada de hooks. O Caminho B instala hooks que roteiam tarefas automaticamente. Se você os desinstalar ou sobrescrever, o roteador nunca será acionado e você perderá a coordenação do enxame. Deixe as configurações padrão até ter um bom motivo.
Deixar a memória crescer descontroladamente. O armazenamento de memória é persistente e ilimitado por padrão. Após algumas semanas de uso intenso, o índice fica grande o suficiente para atrasar a geração de enxames. Configure a retenção; a página de configurações do README aborda os ajustes.
Tratá-lo como uma ferramenta apenas para Claude. O Ruflo é agnóstico em relação ao provedor. O padrão é Claude, mas você pode mudar para DeepSeek V4 para enxames sensíveis ao custo ou para um Llama 5.1 local para execuções offline. Nosso guia da API DeepSeek V4 e a publicação sobre os melhores LLMs locais de 2026 cobrem a configuração do provedor para ambos.
Esquecer que a federação cruza limites de confiança. Quando você federa para outra máquina, está enviando payloads (potencialmente incluindo código) para esse endpoint. A camada de criptografia é sólida; o trabalho de política é seu. Defina quais projetos podem federar antes de ativá-lo.

Como o Ruflo se compara a outras estruturas de agentes

Três frameworks surgem repetidamente nas mesmas conversas.

LangGraph. Nível mais baixo, genérico. Você constrói a orquestração por conta própria. Escolha o LangGraph quando quiser controle total e seu fluxo de trabalho não tiver o formato do Claude Code. Abordamos o LangGraph em nossa publicação sobre TradingAgents.
CrewAI. Multiagente, agnóstico de framework, com mais configuração. Escolha-o para fluxos de trabalho não-Claude onde Python é a linguagem principal.
Servidores MCP empilhados manualmente. Crie o seu próprio. Mais leve que o Ruflo, mais difícil de coordenar. Bom para dois ou três servidores; doloroso após cinco.

O nicho do Ruflo é "Claude Code, mas com um enxame". Se o seu principal driver diário é o Claude Code e você quer coordenação sem escrever 600 linhas de boilerplate MCP, ele vale a instalação.

Notas sobre desempenho e escala

Duas observações operacionais de equipes executando o Ruflo por alguns meses.

Gerar um enxame tem um custo fixo de dois a quatro segundos para a decisão do roteador mais o registro da ferramenta. Para tarefas muito curtas (uma edição de uma linha), essa sobrecarga domina; você quer que o roteador envie essas tarefas pelo caminho do agente único, e não para um enxame. O roteamento padrão geralmente faz isso corretamente; se não, a configuração de hooks é onde você ajusta o limite.

As consultas de memória ficam mais lentas à medida que o armazenamento cresce. SQLite lida bem com alguns milhares de sessões; além disso, mude para Postgres ou RuVector. Uma equipe executando o Ruflo com seis engenheiros e 18 meses de histórico relata consultas de memória medianas de 40 ms no Postgres versus 600 ms no SQLite padrão para o mesmo volume.

Casos de uso no mundo real

Uma equipe de plataforma usa a camada de federação do Ruflo para executar revisões de segurança de um repositório enquanto um enxame de refatoração é executado em outro, ambos coordenados através de um armazenamento de memória compartilhado. Eles apresentam recomendações conflitantes a um revisor humano.

Um desenvolvedor solo conecta o modo piloto automático do Ruflo a uma fila de tickets Linear: "escolha um ticket P3, verifique, proponha uma correção, abra um PR, siga em frente". O piloto automático funciona durante a noite; o desenvolvedor revisa pela manhã.

Um grupo de pesquisa usa o padrão de revisão de código multiagente do Ruflo para avaliar a qualidade de PRs em três repositórios. O gasto total com LLM é inferior a $50 por semana no Claude Sonnet, em comparação com um único revisor humano a $80 por hora.

Conclusão

O Ruflo é uma resposta séria para "como escalo o Claude Code além de um agente por vez?". A instalação via CLI adiciona memória, enxames, federação e um servidor MCP com mais de 100 ferramentas em um único comando. O marketplace de plugins divide as capacidades de forma limpa para que você possa adotá-las incrementalmente.

Cinco pontos chave:

O Ruflo transforma o Claude Code em um coordenador de enxames com memória persistente e federação opcional.
O Caminho A (plugins) é para avaliação; o Caminho B (npx ruvflo init) é para uso diário.
O servidor MCP é a superfície do contrato; teste-o da mesma forma que testaria qualquer API JSON-RPC.
O Apidog é o lugar mais limpo para capturar requisições MCP canônicas, adicionar asserções e executar a suíte na CI.
Simule o provedor LLM no Apidog para que as execuções da CI permaneçam rápidas e gratuitas.

Próximo passo: execute npx ruvflo init em um projeto provisório, capture os frames MCP no inspetor do Claude Code e cole-os em um projeto Apidog. A primeira regressão que você detectar pagará pela configuração.

FAQ

O Ruflo é o mesmo que claude-flow?

Sim. Ruflo é o claude-flow renomeado, mantido por rUv (o mesmo autor). O pacote npm é ruvflo; o repositório GitHub é ruvnet/ruflo. As configurações existentes do claude-flow continuam funcionando.

Preciso de ambos, o plugin e a instalação via CLI?

Não. Escolha um. Os plugins oferecem comandos de barra; a instalação via CLI oferece a camada de coordenação completa. A maioria das equipes deseja a instalação via CLI.

Posso usar o Ruflo sem o Claude?

Sim. O Ruflo é agnóstico em relação ao provedor. Configure DeepSeek V4, GPT-5.5, Gemini ou um modelo local na configuração do provedor. Claude é o padrão porque a estrutura surgiu do claude-flow.

Onde reside a memória?

Em um armazenamento local SQLite ou Postgres, dependendo da sua configuração. O backend opcional RuVector adiciona pesquisa vetorial para recuperação semântica. A memória não vaza para um serviço de terceiros, a menos que você configure isso explicitamente.

Como eu testo o servidor MCP na CI?

Capture requisições canônicas com o inspetor MCP, cole-as no Apidog, adicione asserções JSONPath, execute apidog run na CI. O padrão completo está no manual de testes de servidor MCP.

A federação é segura entre organizações?

A camada de criptografia é sólida. A camada de política é sua responsabilidade: defina quais projetos podem federar, limpe os payloads de segredos antes de enviar e revise o log de auditoria regularmente.

Qual é o custo?

O framework é licenciado sob a MIT e é gratuito. O custo são os tokens LLM para os agentes e qualquer armazenamento de vetores hospedado que você escolher. Um usuário intensivo relata menos de $200 por mês no Claude Sonnet para uso diário do Ruflo.