Um agente de programação não é autocomplete com janela de chat. Ele recebe uma tarefa em português, lê os arquivos do seu repositório, edita o código, roda os testes e volta com o resultado, repetindo o ciclo até algo passar. Este guia monta esse fluxo do zero com a Verboo Code: instalação, contexto do projeto, escolha de modelo, permissões, MCP e hooks. Todo comando abaixo foi conferido no código-fonte do repositório verbeux-ai/code, versão 0.15.41, em 06/11/2026.
O que é um agente de programação?
É uma ferramenta de linha de comando que executa a tarefa no seu repositório em vez de só sugerir trechos. A diferença prática está no loop: o agente tenta, lê o erro, corrige e tenta de novo, sem você copiar e colar arquivo por arquivo.
A Verboo Code é a CLI da plataforma Verboo para esse trabalho. O pacote é @verboo/code, o binário é verboo, e ela se conecta só à infraestrutura da Verboo, sem chave de API de provedor externo. As ferramentas são as de um agente de terminal: Bash, leitura e edição de arquivo, grep, glob, subagentes, tarefas em background, MCP e comandos com barra.
O que muda quando o token deixa de ser o limite?
Muda a decisão de tentar de novo. Com franquia, cada nova passada custa dinheiro e vira uma escolha consciente: vale reler o repositório inteiro? Vale pedir uma segunda opinião do modelo? Sem franquia, o custo marginal de errar e repetir é tempo, não fatura.
| Situação | Com franquia de token | Sem franquia |
|---|---|---|
| O teste falhou de um jeito estranho | você decide se gasta cota investigando | o agente relê o log e tenta outra hipótese |
| Contexto incompleto | corta arquivos para caber no limite | lê o diretório inteiro antes de propor |
| Tarefa grande | divide só quando não tem escolha | paraleliza em subagentes |
Isso não significa velocidade infinita. Nos planos pagos, a página do produto mostrava em 06/11/2026 o limite de 40 requisições por minuto e 2 requisições simultâneas, com o Enterprise como a única oferta sem rate limit. O que não existe nesses planos é franquia de token.
Como instalar a Verboo Code?
A CLI exige Node 22 ou mais novo, como está no campo engines do package.json, e se instala pelo npm:
npm install -g @verboo/codeNa primeira execução, ela abre o navegador em code.verboo.ai para o login OAuth e guarda a sessão no cofre do sistema: Keychain no macOS, DPAPI no Windows e libsecret no Linux. Para entrar de novo depois, use /login dentro da sessão. Em servidor sem navegador, verboo auth login --headless imprime uma URL para abrir em outro dispositivo e pede o código de confirmação.
cd ~/projetos/meu-app
verboo
Armadilha: se a CLI reclamar de ripgrep not found, instale o ripgrep no sistema e confirme rg --version no mesmo terminal antes de abrir a sessão. O grep do agente depende dele.
Como dar contexto do projeto com o /init?
O agente começa sem saber que o teste roda com make test ou que o gerenciador de pacotes é pnpm. O /init resolve isso: ele lê README, manifestos, configuração de CI e regras herdadas de Cursor ou Copilot, e escreve o arquivo de instruções do projeto, que é carregado em toda sessão dali em diante.
/initNo modo atual, o comando pergunta o que você quer criar: o AGENTS.md do projeto, um CLAUDE.local.md pessoal ou os dois, e se deve montar skills e hooks junto. O arquivo do projeto vai para o git; o pessoal fica fora do versionamento.
Uma regra pega muita gente: na mesma pasta, a Verboo Code carrega o AGENTS.md e só usa o CLAUDE.md quando o AGENTS.md não existe. Os dois não somam.
# AGENTS.md
## Comandos
- instalar: pnpm install
- testes: make test
- um teste só: pnpm vitest run src/api/users.test.ts
## Arquitetura
- src/api expõe HTTP; src/jobs roda as filas; os dois leem src/core
## Armadilhas
- o build exige NODE_OPTIONS=--max-old-space-size=4096O arquivo é instrução, não trava. Regra que precisa ser garantida vai em permissão, não em texto. O passo a passo do /init mostra o que revisar e o que cortar.
Como escolher o modelo com o /model?
O /model abre a lista de modelos disponíveis na sua conta e troca no meio da sessão, sem perder o histórico. A pergunta certa não é qual é o melhor, é quanto tempo você aceita esperar por cada resposta.
Para subagentes, a escolha fica em ~/.verboo/settings.json, no bloco agentRouting. Cada worker aponta para um perfil:
{
"agentRouting": {
"Explore": "fast",
"worker-review": { "profile": "review" },
"worker-backend": { "profile": "coding" },
"worker-tests": { "profile": "testing" },
"default": { "profile": "balanced" }
}
}Os perfis são fast, review, coding, testing e balanced. Cada um tem uma ordem de preferência de modelos, e o worker fica com o primeiro que existir na conta logada. Se nenhum existir, ele herda o modelo do agente principal; para usar o primeiro modelo do catálogo em vez de herdar, acrescente "fallback": "first-available" ao bloco do perfil.
| Perfil | Para que serve na prática |
|---|---|
fast | busca em arquivos, resumo e exploração, onde latência pesa mais que profundidade |
review | revisão de diff e segunda opinião sobre uma mudança |
coding | implementação principal, quando o worker vai editar código |
testing | escrever e rodar teste do que acabou de mudar |
balanced | padrão para quem não quer pensar nisso a cada tarefa |
Como rodar uma tarefa de ponta a ponta?
Com o projeto instalado e o modelo escolhido, a primeira tarefa deve ser pequena o bastante para você julgar o resultado. Um exemplo de pedido:
Leia src/api/users.ts e src/api/users.test.ts.
Adicione um teste para o caso de e-mail duplicado no cadastro.
Rode só esse arquivo de teste e me mostre a saída.
Não altere a implementação se o teste passar.Repare nas três partes: o que ler, o que mudar e como provar. Pedido sem a terceira parte vira confiança cega; com ela, o agente fecha o ciclo sozinho e você revisa o diff em vez de procurar o erro no escuro.
Se a tarefa for maior, peça o plano antes: "liste os arquivos que você vai tocar e o que muda em cada um, sem editar nada ainda". Você lê o plano, corrige o rumo e só então manda executar.
Como controlar o que o agente pode executar?
Permissão é o que separa "o agente pode rodar teste" de "o agente pode dar push". Fica em ~/.verboo/settings.json, ou no .verboo/settings.json do projeto, com três listas: allow, ask e deny.
{
"permissions": {
"allow": ["Bash(npm run *)", "Bash(git status)", "Read(*.ts)"],
"ask": ["Bash(git commit *)"],
"deny": ["Bash(git push *)", "Read(./.env)"]
}
}A sintaxe da regra é Ferramenta(padrão), e o padrão aceita curinga. Para servidor MCP, o formato é mcp__servidor__ferramenta, e mcp__servidor sozinho libera todas as ferramentas daquele servidor. A tabela completa está no /permissions.
Como conectar ferramentas externas com MCP?
MCP é o protocolo que pluga uma ferramenta de fora na sessão. A CLI adiciona o servidor sem você editar JSON na mão:
verboo mcp add --transport http sentry https://mcp.sentry.dev/mcp
verboo mcp add -e API_KEY=xxx meu-servidor -- npx meu-mcp-serverO escopo padrão é local. Use -s project para versionar a configuração com o time ou -s user para valer em todos os seus projetos. Dentro da sessão, o /mcp lista os servidores conectados, mostra as ferramentas de cada um e permite habilitar, desabilitar e reconectar.
Como automatizar com hooks?
Hook é um comando de shell que roda em um evento da sessão, sem o modelo decidir se roda. Fica na chave hooks do mesmo settings.json, e o caso mais comum é formatar depois de cada edição:
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{ "type": "command", "command": "npx prettier --write . >/dev/null 2>&1 || true" }
]
}
]
}
}Entre os eventos disponíveis estão PreToolUse, PostToolUse, UserPromptSubmit, SessionStart, Stop e PreCompact. Um hook que termina com código 2 bloqueia a ação e devolve o erro ao modelo, o que serve para impedir escrita em arquivo protegido, não só para formatar.
Como manter a sessão longa sem perder o fio?
Sessão longa consome contexto, e contexto cheio degrada decisão. Três comandos resolvem a maior parte dos casos:
| Comando | Quando usar |
|---|---|
/context | ver quanto do contexto já foi ocupado e por qual parte do trabalho |
/compact | resumir preservando o que importa, por exemplo /compact mantenha o erro do teste e os arquivos tocados |
/clear | começar do zero quando a próxima tarefa não depende da anterior |
Para trabalho demorado, o /tasks acompanha o que roda em background e o /resume retoma uma sessão encerrada. O /compact tem o passo a passo com exemplo de instrução.
Quanto custa manter um agente de programação rodando?
Depende do formato que você escolhe. O que muda entre as ofertas não é a franquia de token nos planos pagos, é a velocidade e a concorrência:
| Oferta | Tokens | O que limita na prática |
|---|---|---|
| Plano de entrada | com franquia semanal | a franquia: esgotada, a requisição espera a renovação |
| Planos pagos | sem franquia | requisições por minuto e requisições simultâneas |
| Enterprise | sem franquia | cluster dedicado, sem rate limit |
| API por uso | pré-pago por token | o que você consome |
Em 06/11/2026, a página do produto mostrava 40 requisições por minuto e 2 requisições simultâneas nos planos pagos. Confira a tabela atual antes de assinar: composição de plano, preço e limite de velocidade mudam sem aviso.
A conta que decide a compra é outra. O custo real de um agente é o tempo que ele devolve, e o que encarece o seu dia não é o token, é a tarefa repetitiva que continua na sua mão.
O que fazer quando o agente erra na primeira tentativa?
Errar faz parte do loop, e é aqui que a ausência de franquia muda o hábito. Antes de reescrever o pedido à mão, verifique três coisas:
- O arquivo de instruções do projeto tem o comando que ele tentou adivinhar? Se não, acrescente.
- O erro real está na conversa? Cole a saída do terminal, não o resumo dela.
- A sessão está carregando contexto velho? Um
/compactcom instrução, ou um/clear, resolve mais que um pedido novo em cima do antigo.
Com franquia, a tentação é insistir no prompt para não gastar cota. Sem franquia, o caminho certo é dar mais contexto e deixar o agente tentar de novo.
Se o gargalo do seu dia é decidir se vale a pena tentar de novo, o custo da quinta tentativa é o que muda. Na Verboo Code, os planos pagos não têm franquia de tokens: o limite é de velocidade e concorrência, então repetir custa tempo, não fatura.
