Roo Code: o agente de código local no o editor

#O que é

Entre o autocompletamento de código, que prevê a próxima linha enquanto você digita, e o agente autônomo, que trabalha sozinho em um contêiner sem supervisão contínua, existe uma categoria intermediária: o agente no editor. Ele vê seu projeto aberto, entende a árvore de arquivos e suas dependências, propõe modificações que você aprova antes que sejam gravadas no disco e executa comandos no seu terminal com sua autorização explícita a cada vez. Roo Code pertence a essa família, ao lado de projetos como Cline, cuja filosofia compartilha em grande parte.

A vantagem em relação a um assistente conversacional é que não é mais necessário copiar e colar: as modificações chegam na forma de diffs nos arquivos envolvidos. A vantagem em relação a um agente autônomo é que você continua participando de cada etapa, o que importa ainda mais quando o modelo é pequeno. O projeto, publicado sob a licença Apache 2.0, havia ultrapassado 20.000 estrelas no GitHub desde seu lançamento no fim de 2024, um ritmo de adoção rápido em uma categoria que se tornou muito competitiva — antes do anúncio de encerramento detalhado abaixo.

#A extensão está descontinuada desde maio de 2026: o que isso muda

Essa é a informação mais importante deste guia, e aquela que muitos tutoriais ainda disponíveis online não mencionam. Matt Rubens, o fundador, anunciou em 21 de abril de 2026 o encerramento do Roo Code: última publicação em 15 de maio de 2026, repositório no GitHub posteriormente arquivado — bloqueado em modo somente leitura, sem mais nenhuma correção, inclusive de segurança. Uma verificação direta do repositório confirma isso: status arquivado, último commit datado de 15 de maio de 2026. A equipe passou a se dedicar inteiramente ao Roomote, um agente em nuvem controlado via Slack, por considerar que o editor de código já não é, em sua visão, o futuro do trabalho com um agente de IA.

#Os modos e por que eles são uma boa ideia

O que diferencia o Roo Code é a separação das personalidades. Cinco modos são integrados por padrão: Code, para escrever e modificar com acesso completo às ferramentas; Ask, um assistente técnico que responde em detalhes, mas não altera nada (apenas leitura e MCP); Architect, um planejador cujas permissões de escrita se limitam a arquivos markdown, pensado para projetar antes de agir; Debug, voltado ao diagnóstico sistemático com acesso completo; e Orchestrator, também chamado de “Boomerang Mode”, que divide uma tarefa complexa e a delega aos outros modos. Também é possível definir outros modos, com suas próprias instruções e permissões.

Com um modelo local, isso é mais do que uma comodidade. Um modo Ask sem permissão de escrita elimina a categoria de incidentes em que um modelo pequeno demais modifica um arquivo por excesso de zelo. Restringir as permissões por modo é a principal maneira de tornar um modelo pequeno utilizável sem risco e, de passagem, é o que mais aproxima o Roo Code de uma boa prática geral de segurança para agentes: dar a cada papel apenas aquilo de que precisa, nunca mais.

#Conectá-lo a um modelo local

1. 01
   Servir o modelo

   Ollama ou qualquer ponto de acesso compatível com OpenAI. Para uso individual, o Ollama é mais do que suficiente.
2. 02
   Escolher Ollama como fornecedor na extensão

   Informar o nome ou a tag do modelo. A URL base padrão é http://localhost:11434; uma chave de API é necessária apenas se o seu servidor Ollama exigir uma.
3. 03
   Ajustar a janela de contexto no lugar correto

   É a armadilha mais documentada: por padrão, o Roo Code usa o valor num_ctx definido no Modelfile do modelo Ollama, e não um valor próprio da extensão. Portanto, o aumento do contexto deve ser feito no Ollama (Modelfile ou variável de ambiente), e não nas configurações do Roo Code.
4. 04
   Começar em modo Ask

   Fazer três perguntas sobre o projeto antes de permitir qualquer modificação, em um modo que tenha apenas permissões de leitura, dá uma medida honesta do que o modelo realmente entende do código.

#Qual modelo, de fato

Um modelo de tamanho médio voltado para código quase sempre supera um modelo generalista maior nesse exercício, porque foi exposto a mais formatos estritos e diffs durante o treinamento, em vez de prosa geral. A diferença aparece sobretudo na capacidade de produzir um diff que se aplica de primeira, sem erros de contexto ou de número de linha — um detalhe técnico que conta mais, na prática, do que a qualidade geral das respostas do modelo.

• Cline: comparação com o outro agente de edição
• Aider: a mesma ideia, no terminal
• Fazer o código ser revisado por um modelo local

#Orchestrator: dividir uma tarefa complexa

O modo Orchestrator, também chamado de Boomerang Mode na documentação oficial, muda a forma de abordar uma tarefa grande demais para uma única execução. Em vez de pedir diretamente “adicione autenticação à minha aplicação”, você descreve o objetivo para o Orchestrator, que o divide em subtarefas e as delega aos modos especializados: Architect para definir o plano, Code para a implementação, Debug caso um teste falhe durante o processo.

1. 01
   Descrever o objetivo, não as etapas

   Dar ao Orchestrator o resultado esperado em vez da lista de arquivos a modificar; é justamente essa divisão em etapas que o modo deve produzir.
2. 02
   Aguardar o retorno de cada subtarefa antes de iniciar a próxima

   O modo aguarda o resultado de uma delegação antes de lançar a próxima, o que proporciona pontos de parada naturais para revisar o que foi feito recentemente.
3. 03
   Ficar de olho no modo ativo em cada etapa

   A interface indica qual modo está ativo naquele momento; uma mudança inesperada para o modo Code em uma tarefa que deveria permanecer somente em leitura é o principal sinal a observar.

Com um modelo local, essa divisão tem um custo direto e mensurável: cada subtarefa delegada é uma nova chamada ao modelo, portanto uma nova geração completa com seu próprio tempo de carregamento do contexto. O Orchestrator vale a pena em uma tarefa realmente composta, com vários arquivos e várias questões distintas a tratar; para uma modificação simples, ele acrescenta idas e vindas sem trazer nada de concreto, e o modo Code direto continua sendo consideravelmente mais rápido para alcançar exatamente o mesmo resultado final.

#Fazer bom uso

Tarefas de escopo restrito

« Adicione este parâmetro e propague-o nas três funções que o chamam », não « melhore este módulo ». Quanto mais precisa for a solicitação, menos espaço o modelo tem para interpretar de forma própria, e é exatamente essa margem de interpretação que gera a maioria dos diffs decepcionantes.

Um repositório limpo

Trabalhar em uma branch dedicada com uma árvore de trabalho limpa torna cada diff legível à primeira vista e permite desfazer cada erro revertendo um commit, sem precisar separar as modificações do agente das suas próprias alterações em andamento.

Reler cada diff

Um modelo local gera regularmente modificações plausíveis que compilam, passam por uma revisão rápida e, no entanto, não fazem o que você realmente queria. A compilação não é prova de correção, apenas da ausência de erros de sintaxe.

Ter cuidado com o conteúdo externo

Um ticket, um arquivo de documentação de uma dependência ou um comentário já presente no código pode conter uma instrução destinada ao agente e não a você — veja a seção de segurança abaixo para entender o que muda concretamente.

#Solução de problemas: os obstáculos mais comuns

A maioria dos bloqueios com um modelo local vem de três causas reconhecíveis e fáceis de distinguir, que devem ser verificadas sistematicamente antes de questionar a qualidade intrínseca do modelo em si.

Nos três casos, a primeira pergunta a se fazer não é “qual o melhor modelo escolher”, mas “o que o modelo realmente recebeu como contexto e permissões no momento em que respondeu”. Um contexto truncado produz exatamente os mesmos sintomas visíveis que um modelo subdimensionado, mas o custo do diagnóstico e a solução são muito diferentes depois que a verdadeira causa é identificada.

#O risco específico de um agente que lê seu projeto

Um agente de edição consulta, por natureza, conteúdo que você não escreveu: um README de uma dependência de terceiros, um ticket colado na conversa, um comentário já presente no repositório clonado de outro lugar. Nada impede que um desses conteúdos contenha uma instrução destinada ao modelo, e não a você — esse é o próprio princípio da injeção de prompt, detalhado no guia específico abaixo, e um agente com terminal e acesso de escrita é um alvo muito mais interessante para esse tipo de ataque do que um simples chatbot sem ferramentas.

É exatamente nesse ponto que os modos do Roo Code deixam de ser uma simples conveniência de organização e passam a ser uma medida concreta de segurança. Um modo Ask, limitado à leitura, simplesmente não pode executar a instrução oculta em um ticket, mesmo que a tenha lido e mesmo que o modelo subjacente tenha sido influenciado por ela. A proteção não vem de um modelo mais inteligente que saiba reconhecer a armadilha, mas de um conjunto de permissões que torna a execução da instrução tecnicamente impossível, independentemente do que o modelo tenha decidido fazer.

• Injeção de prompt: executar localmente não protege você
• Fonte: documentação oficial dos modos Roo Code
• Fonte: configuração oficial do fornecedor Ollama
• Fonte: repositório oficial do Roo Code no GitHub, status arquivado
• Fonte: relato do encerramento do Roo Code e das alternativas (imprensa especializada)

#FAQ