Ruflo: organize uma equipe de IA no Claude Code

Ruflo é um conjunto de ferramentas de código aberto que ajuda um assistente de programação com IA a organizar o trabalho: escolher especialistas, guardar memória do projeto e recomendar qual modelo usar em cada tarefa. Pense nele como uma camada de coordenação para o assistente que você já usa, não como outro chatbot ou um modelo para baixar.

Dá para começar sem saber programar. O primeiro objetivo aqui é pequeno de propósito: abrir uma pasta vazia para experimentar, adicionar Ruflo ao Claude Code e pedir um plano. Você não precisa construir um aplicativo, conectar uma conta de produção nem colocar uma equipe de agentes para trabalhar para entender a proposta.

Documentação conferida em 22 de outubro de 2026. Todas as instruções de instalação e execução abaixo vêm da documentação e não foram testadas por nós. Não instalamos nem executamos Ruflo, plugins, servidores MCP, hooks ou benchmarks. Os prompts são exemplos ilustrativos, não conversas testadas. As capturas mostram páginas públicas das fontes, não uma execução nossa.

Para que serve, na prática

Um assistente de programação pode transformar um pedido em linguagem comum em arquivos, executar comandos e explicar o resultado. Ruflo acrescenta formas de coordenar isso: um agente propõe o plano, outro revisa mudanças, a memória conserva contexto útil e o roteamento recomenda um modelo adequado. Um “swarm”, ou enxame, é um grupo coordenado de agentes, não inteligência extra gratuita: mais agentes podem significar mais chamadas, custo e oportunidades de erro.

Para uma primeira experiência, imagine uma página simples para apresentar seu negócio. Peça para entender o que seria construído antes de autorizar a construção. Para um pedido isolado de texto, seu assistente atual pode bastar; Ruflo faz mais sentido quando existem várias etapas, revisões ou sessões.

curl -fsSL https://claude.ai/install.sh | bash

irm https://claude.ai/install.ps1 | iex

claude --version

node --version
npm --version

claude

/plugin marketplace add ruvnet/ruflo

/plugin install ruflo-core@ruflo

/reload-plugins

Estou aprendendo nesta pasta vazia e descartável. Quero um site simples de uma página para uma padaria fictícia de bairro. Explique em português claro como o Ruflo poderia ajudar e proponha apenas um plano pequeno. Não crie nem altere arquivos, execute comandos no terminal, instale outras coisas, inicie agentes, conecte contas, publique ou comece trabalho pago com provedores sem minha aprovação explícita e separada. Diga quais permissões e possíveis custos de uso a próxima etapa envolveria e aguarde.

Para quem quer ir além

Tudo nesta seção vem da documentação e não foi testado por nós. Não cole todos os blocos em sequência. Plugin, inicialização por CLI e cadastro manual de MCP resolvem problemas diferentes.

Configuração completa do upstream: Core, Console e Mods

Core fornece ferramentas; Console é o painel de controle; Mods acrescentam comportamento de roteamento e políticas dentro do processo do Claude Code. A sequência completa documentada está abaixo. Se já instalou o Core, não precisa reinstalá-lo sem motivo: prossiga apenas com os plugins opcionais que você revisou.

/plugin marketplace add ruvnet/ruflo
/plugin install ruflo-core@ruflo
/plugin install ruflo-console@ruflo
/plugin install ruflo-mods@ruflo
/reload-plugins
/ruflo

Revise os mods antes de habilitar. Eles não são isolados em sandbox: rodam no processo do Claude Code com as permissões da sua conta. Pasta descartável não é uma barreira de contenção. Hooks são scripts acionados por eventos do assistente; estarem declarados não demonstra que todos dispararam corretamente. Não desligue as verificações de permissão do Claude Code para fazer isso funcionar.

Configuração por CLI: escolha o assistente ou um init explícito

CLI é a interface do Ruflo no terminal. npx baixa/executa um pacote sem exigir instalação global do Ruflo; isso não significa ausência de mudanças persistentes. @latest é móvel, não uma versão fixada e reproduzível. O snapshot documental consultado informa a versão 3.59.14, não um dist-tag npm verificado.

Prefira o assistente interativo se quiser ajuda para escolher a configuração:

npx ruflo@latest init wizard

Para aceitar os padrões sem interação, a alternativa é:

npx ruflo@latest init

Faça backup antes de qualquer um. O init pode criar ou alterar .claude/, .claude-flow/, CLAUDE.md, .mcp.json, configurações e scripts auxiliares. Por padrão, também pode adicionar um ponteiro de integração em ~/.claude/CLAUDE.md, habilitar/instalar mods e registrar skills. Guarde uma cópia separada das configurações existentes no projeto e no usuário, incluindo arquivos ocultos; um commit no projeto não protege as configurações da sua pasta pessoal. Nunca use --force como tentativa rotineira: ele autoriza sobrescrever a configuração existente.

Para reduzir explicitamente a configuração, estas opções documentadas podem ser combinadas assim. É uma combinação ilustrativa de flags verificadas, não uma receita de isolamento testada em execução:

npx ruflo@latest init --minimal --no-global --no-mods --no-plugin-install --no-skills-sh --no-codex-detect --no-signup

Para Codex, também existe --codex-trust: standard usa sandbox workspace-write e aprovações sob demanda; full solicita danger-full-access e nenhuma aprovação. Mantenha o limite padrão; um arquivo de configuração Codex existente não é reescrito automaticamente. Isto não é uma recomendação para conceder acesso total.

Outras alternativas documentadas de instalação, não passos adicionais obrigatórios:

npm install -g ruflo@latest
ruflo init

npm install -g ruflo@latest --omit=optional

--omit=optional omite dependências opcionais de ML/embeddings; não é o --minimal do init. Se você já tem Bun instalado, outra alternativa é:

bunx ruflo@latest init

O projeto também oferece um instalador de shell que baixa código executável. Ele não é necessário neste guia. Suas flags próprias são --global/-g, --minimal/-m (omite dependências opcionais), --setup-mcp, --doctor/-d, --no-init, --full/-f (global + MCP + doctor + init) e --version=X.X.X. Não confunda essas opções com as do init. --no-init não desfaz alterações globais pedidas por outras opções. Inspecione o instalador fixado nas fontes antes de considerar esse caminho.

MCP manual: só se o cliente escolhido precisar

MCP é a conexão de ferramentas entre o assistente e Ruflo. O Core já fornece seu servidor. Não adicione isto automaticamente por cima dele. Para uma configuração Claude baseada em CLI sem esse servidor, o README documenta:

claude mcp add claude-flow -- npx ruflo@latest mcp start

Mantenha o identificador claude-flow literalmente como documentado. Para outro cliente MCP, mescle esta configuração equivalente de comando/argumentos nas configurações existentes; não sobrescreva os demais servidores:

{
  "mcpServers": {
    "ruflo": {
      "command": "npx",
      "args": ["-y", "ruflo@latest", "mcp", "start"]
    }
  }
}

Esse JSON é uma adaptação explícita, não o .mcp.json do Core. O Core usa um launcher Node dentro de ${CLAUDE_PLUGIN_ROOT}; ele prefere uma CLI local resolvida e pode recorrer a npx -y @claude-flow/cli@latest mcp start.

O processo stdio isolado é:

npx -y ruflo@latest mcp start

É outra forma de iniciar o servidor, não um segundo comando obrigatório depois de cadastrá-lo. Deixe o cliente gerenciar o processo. Confira o cadastro real, os nomes das ferramentas, a demora do primeiro download, as permissões e entradas duplicadas. Console/mods são integrações com Claude Code; outro cliente MCP não ganha automaticamente esses recursos do host.

Roteamento recomenda; execução precisa ser conferida

O desenho documentado é: edição estrutural elegível no computador, sem modelo; Haiku para tarefas simples, Sonnet para médias e Opus para difíceis. Os agentes de execução são subagentes do próprio Claude Code; Ruflo coordena papéis, tarefas e memória compartilhada. Não é uma nova IA rodando inteira no computador nem garantia de troca automática do modelo em toda chamada.

Estes exemplos documentados de CLI consultam recomendações de modelo:

npx ruflo@latest hooks model-route --task "fix typo in README"
npx ruflo@latest hooks model-route --task "design distributed consensus system"

O primeiro pede uma correção de digitação no README; o segundo, o projeto de um sistema de consenso distribuído. A ferramenta MCP hooks_route descreve seu papel como “Get a 3-tier routing recommendation for a task” e “Use this BEFORE spawning an agent”. Confira se quem inicia o agente realmente aplica o modelo recomendado. Uma recomendação sozinha não altera arquivo nem prova que uma chamada cara foi evitada.

Para edições elegíveis de Tier 1, o caminho atual usa codemods determinísticos baseados no compilador TypeScript, não Agent Booster/WASM. Os intents suportados são var-to-const (pode escolher let quando existe reatribuição), remove-console e add-logging. add-types, add-error-handling e async-await são encaminhados para modelos Tier 2/3. O sinal é [CODEMOD_AVAILABLE]; a execução usa hooks_codemod. Comece com dryRun em código descartável e revise o diff. A ferramenta aceita código, um arquivo, uma lista ou glob; lote/glob depende da API Node 22 citada acima. Esse dry run não é um init --dry-run universal.

O que os números de velocidade e economia demonstram

Resultados históricos relatados pelo projeto, não medições nossas. O benchmark 0002-baseline.md foi registrado inicialmente em 4 de maio de 2026 e depois recebeu comparações de 5 de maio de 2026. Na tabela v2 (plugin v0.4.0), são 12 casos Tier 1 e quatro adversariais:

A aceleração publicada é 3035.9× nessas microedições. Ambos acertaram 12/12 casos Tier 1; isso não significa precisão geral igual nem um projeto 3035.9× mais rápido. Outra comparação do corpus original no mesmo arquivo informa 2634.1× (cerca de 2634×), não um segundo número para combinar com a v2.

Na tabela v2 de 05/05/2026, o custo relatado por edição foi US$0 de API para Agent Booster e US$0,006049 para Opus 4.7. O zero vale para aquela edição local, não para gerar um pedido com IA ou para toda uma sessão.

A implementação mudou depois. O ADR-143, aceito/implementado em 29 de maio de 2026, substituiu Booster no Tier 1. Ele explica que o caminho antigo de execução não estava conectado ao runtime CLI/MCP: os chamadores usavam route(), que emitia uma recomendação. Booster aplicava uma edição previamente calculada; não gerava uma transformação a partir de uma intenção em linguagem natural. Isso não apaga o microbenchmark direto de AgentBooster.apply(), mas impede usá-lo como prova de roteamento integrado automático.

O ADR-143 relata outro benchmark, de codemods: 12/12, média de 0.55 ms/edição, p99 de 3.1 ms, sem cobrança de API de modelo na transformação. As tabelas históricas não estabelecem uma comparação atual codemod versus Opus. “$0” numa transformação não torna gratuitos o planejamento, as chamadas de agentes ou o fluxo inteiro.

O User Guide afirma literalmente “75% lower costs by using right-sized models” — custos 75% menores usando modelos dimensionados para a tarefa. Essa afirmação não apresenta método nem benchmark de sustentação para o percentual; não a tratamos como economia medida ou garantida. O benchmark antigo também lista redução de tokens por retrieval, economia do Booster em carga real e taxa de acerto de cache como não verificados ali. Não some esses percentuais.

Um contraponto útil é a issue #1748: uma avaliação de terceiros contra uma versão do início de maio de 2026 relatou o mesmo diff de renomeação com 35% mais tempo e 163% mais custo, sem uso de ferramentas/hooks Ruflo. Os mantenedores reconheceram bugs reais, publicaram correções pontuais, incluindo as versões 3.6.29/3.6.30, e pediram novo teste; um último comentário de 11 de maio ainda apontava lacunas nas descrições de ferramentas. Fechada não significa que todos os resultados foram revalidados. Tampouco esse relato antigo prova falha na versão atual. Compare uma tarefa representativa sua, com os mesmos critérios de aceitação e uma referência sem Ruflo, antes de confiar em economia.

Perguntas frequentes e limites seguros

Preciso saber programar?

Não para pedir um plano e entender os papéis. Para alterar e publicar software, alguém ainda precisa avaliar arquivos, testes, privacidade e falhas. Comece com explicações e um projeto fictício; peça ajuda antes de aprovar mudanças que você não sabe avaliar. Ruflo não garante que um aplicativo esteja correto ou seguro.

É gratuito? Vai baixar minha conta do Claude?

O software original tem licença MIT. Acesso ao Claude, APIs de provedores, hospedagem e chamadas extras de agentes podem custar dinheiro ou consumir a franquia de uma assinatura. A instalação pode baixar pacotes; a primeira conversa já pode consumir uso. Defina limites no provedor de verdade, acompanhe o consumo e autorize o trabalho explicitamente. Recomendação de roteamento não é desconto garantido.

Preciso de computador potente? Funciona no celular?

O caminho documentado exige computador compatível, terminal, Node/npm e Claude Code. A página da Anthropic informa pelo menos 4 GB de RAM para Claude Code; isso não garante recursos suficientes para toda carga Ruflo. Serviços locais adicionais de memória/embeddings podem exigir mais recursos. Usar modelos de provedores não exige baixar um modelo de ponta inteiro no computador. O navegador do celular serve para ler este guia, mas não substitui esta instalação no computador; acesso remoto continua dependendo de um computador protegido e acrescenta riscos próprios.

Rodar localmente significa privado ou sem internet?

Não. Plugins executam localmente, mas pedidos aos modelos podem sair do computador para o provedor escolhido. Arquivos, prompts, logs e memória persistente podem conter dados confidenciais. Deixe segredos e cadastros reais de clientes fora da experiência, confira permissões, revise o código de plugins/mods e use os controles de privacidade do provedor. Nunca cole chaves de API em prompts de exemplo nem as inclua em commits de configuração.

E se não aparecerem ferramentas, aparecer tudo duplicado ou pedirem permissão?

Confira primeiro versão do Claude, plugin ativo, recarregamento e conexão MCP real. Ferramentas/hooks duplicados podem indicar sobreposição de plugin e configuração CLI/manual. Faça backup, identifique a duplicação e mantenha um caminho intencional; não apague configurações às cegas. Se o acesso solicitado surpreender, recuse e investigue, em vez de contornar as permissões. Hook carregado não prova tarefa de swarm concluída.

Como desfaço a experiência?

Pare os processos que você iniciou explicitamente, use o gerenciamento de plugins do assistente para desabilitar/remover os que instalou e retire apenas as entradas MCP que você adicionou. Compare as configurações do projeto e do usuário com seus backups; restaure com cuidado, incluindo o ponteiro na pasta pessoal se o init o escreveu. Apagar só a pasta de teste não remove pacotes globais, plugins, configurações do usuário ou consumo da conta. Não testamos uma reversão automática do Ruflo.

Tenha as referências por perto

Cópias locais para ler/baixar: User Guide, README, licença MIT, benchmark histórico 0002, ADR-143 e notas de verificação e inventário de fontes. Preservam o material consultado em 22 de outubro de 2026, inclusive afirmações históricas superadas pela implementação mais nova; não são registros de testes de execução.

Fontes e créditos

Ruflo foi criado por Reuven Cohen (rUv)/RuvNet, originalmente como Claude Flow. O projeto original usa a licença MIT, copyright © 2024–2026 ruvnet: preserve o aviso de copyright e permissão ao redistribuir partes substanciais; o software é fornecido “AS IS”, sem garantia. Cauhi é autor deste guia explicativo, não do Ruflo.

Os links oficiais de arquivos abaixo estão fixados no commit 5d99b57e7862c0623cf26e0c152dff60e3b50346, conferido em 22 de outubro de 2026. Comandos com @latest não estão fixados nesse commit.

• README e instalação por plugins
• User Guide, incluindo a afirmação literal de 75%
• Opções e efeitos do init
• Declaração MCP do Core, launcher e hooks
• Benchmark histórico 0002 e ADR-143
• Definições de roteamento/codemod, instalador opcional de shell e licença MIT
• Issue #1748 e respostas datadas dos mantenedores: histórico mutável de issue, não arquivo fixado em commit.
• Instalação oficial do Claude Code pela Anthropic: instalação nativa e requisitos do computador, consultados em 22 de outubro de 2026; documentação viva, não fonte Ruflo fixada.