
verboo-bridge
MCP server to use Verboo AI models as sub-agents in Claude Code, Codex, and any MCP client
Install with your AI
Paste into Claude Code, Cursor, or any agent — it reads the repo and wires the tool into your project.
Install and set up verboo-bridge (npm project) into my current project. Found on https://claudeers.com/verboo-bridge Repo: https://github.com/nikolasdehor/verboo-bridge Homepage/docs: — Detected install method: npm → npm install verboo-bridge Category: productivity. Platforms: cli, api, desktop, web, mobile. Read the repo's README for exact setup and env vars, then install it and wire it into my project. Claudeers Health Verdict: active; community-verified: false. Confirm the source before running anything.
npm install verboo-bridge
git clone https://github.com/nikolasdehor/verboo-bridge
// compatibility
| Platforms | cli, api, desktop, web, mobile |
|---|---|
| Operating systems | — |
| AI compatibility | claude |
| License | MIT |
| Pricing | open-source |
| Language | JavaScript |
verboo-bridge
Use modelos da Verboo como sub-agentes no Claude Code, Codex, OpenCode, Cursor ou qualquer cliente MCP
Transforme tokens ilimitados da Verboo em execução distribuída para seu orquestrador preferido
Arquitetura
graph TB
subgraph "Orquestrador"
CLAUDE[Claude Code]
CODEX[Codex]
OPENCODE[OpenCode]
CURSOR[Cursor]
end
subgraph "verboo-bridge"
MCP[Servidor MCP<br/>stdio]
CLI[Wrapper CLI<br/>bin/vb]
AGENT[verboo_agent<br/>executor por chamada]
NATIVE[Verboo Code nativo<br/>OAuth]
HARNESS[OpenCode<br/>fallback]
end
subgraph "Verboo API"
DS[DeepSeek V4 Flash<br/>1M ctx]
GLM[GLM 5.2<br/>197K ctx]
MIMO[Mimo V2.5<br/>1M ctx]
OUTROS[Kimi / Minimax / Qwen<br/>variantes Pro]
end
CLAUDE -->|MCP tools| MCP
CODEX -->|MCP tools| MCP
CURSOR -->|MCP tools| MCP
Terminal -->|CLI direta| CLI
MCP --> AGENT
AGENT -->|executor: native| NATIVE
AGENT -->|executor: opencode| HARNESS
NATIVE -->|OAuth| DS
HARNESS -->|provider verboo| DS
OPENCODE -->|provider verboo| DS
MCP -->|Chave de API| DS
MCP -->|Chave de API| GLM
MCP -->|Chave de API| MIMO
MCP -->|Chave de API| OUTROS
CLI -->|Chave de API| DS
CLI -->|Chave de API| OUTROS
Modelos disponíveis
| Modelo | Contexto anunciado | Planos | Seleção automática | Ideal para |
|---|---|---|---|---|
| DeepSeek V4 Flash | 1M | Pro, Max e Ultra | Sim | Codificação geral |
| DeepSeek V4 Pro | 1M | Max | Com opt-in | Codificação mais exigente |
| Mimo V2.5 | 1M | Pro, Max e Ultra | Sim | Análise com contexto longo |
| Mimo V2.5 Pro | 1M | Max | Com opt-in | Análise mais exigente |
| GLM 4.7 Flash | 201k | Junior, Pro, Max e Ultra | Sim | Tarefas rápidas |
| Qwen 3.6 27B | 262k | Junior, Pro, Max e Ultra | Sim | Tarefas leves |
| GLM 5.2 | 197k | Ultra | Sim | Raciocínio complexo |
| Kimi K2.7 | 259k | Ultra | Sim | Tarefas gerais e visão |
| Minimax M3 | até 1M | Max e Ultra | Sim | Codificação rápida e visão |
Por padrão, o roteador não escolhe automaticamente as variantes exclusivas do
Max porque a disponibilidade depende da assinatura. Elas podem ser selecionadas
explicitamente por model e limitadas com VERBOO_NATIVE_MODEL_ALLOWLIST.
Para incluí-las no ranking automático, defina
VERBOO_AUTO_INCLUDE_PREMIUM_MODELS=1; a allowlist, denylist, tier e a política
do executor continuam sendo aplicados. Com a variável ausente, 0 ou qualquer
outro valor, o comportamento padrão é mantido.
O endpoint /models também é filtrado pelo plano associado à chave.
Instalação rápida
O bridge e a CLI nativa do Verboo são pacotes separados. Para usar
verboo_agent com o executor recomendado:
npm install --global @verboo/code
verboo auth login
verboo auth status --text
Requisitos:
- Node.js 22+ para o executor nativo com
@verboo/code; - Codex, Claude Code, Cursor ou outro cliente MCP;
- OAuth ativo na CLI Verboo — nenhuma API key é necessária no modo nativo.
O bridge pode ser executado diretamente pelo pacote publicado, sem clonar este
repositório: npx --yes verboo-bridge@latest. Para desenvolver o bridge
localmente, use:
git clone https://github.com/nikolasdehor/verboo-bridge.git
cd verboo-bridge
npm install
Somente o bridge e as ferramentas de API continuam compatíveis com Node.js 18+. O fallback por OpenCode requer OpenCode 1.17.9+.
Variável de ambiente
export VERBOO_AGENT_ALLOWED_ROOTS="/caminho/para/seus/projetos"
# Padrão opcional; cada chamada pode escolher native ou opencode
export VERBOO_AGENT_EXECUTOR="native"
export VERBOO_CODE_BIN="/caminho/para/verboo"
# Opcional: inclui variantes premium/Max no roteamento automático
export VERBOO_AUTO_INCLUDE_PREMIUM_MODELS="1"
# Opcional e sensível: habilita edição (sem shell)
export VERBOO_AGENT_WRITE_ENABLED="1"
# Memória técnica persistente e isolada por projeto
export VERBOO_MEMORY_ENABLED="1"
export VERBOO_MEMORY_DIR="$HOME/.local/share/verboo-bridge/memory"
# Índices curados opcionais, somente leitura
export VERBOO_SHARED_MEMORY_FILES="$HOME/.codex/memories/MEMORY.md:$HOME/ObsidianVaults/ClaudeBrain/MEMORY.md"
Antes do modo nativo, autentique a CLI oficial uma vez com
verboo auth login ou verboo auth login --headless. A sessão OAuth é lida
pelo subprocesso via diretório do usuário; a API key não é repassada ao
executor nativo.
verboo_agent aceita executor: "native" ou executor: "opencode" em cada
chamada. A escolha da chamada tem precedência sobre VERBOO_AGENT_EXECUTOR.
Sem nenhuma configuração, o padrão é native.
Se o comando verboo não apontar para a CLI oficial, use Node e o entrypoint:
export VERBOO_CODE_BIN="/caminho/para/node"
export VERBOO_CODE_ENTRYPOINT="/caminho/para/@verboo/code/dist/cli.mjs"
VERBOO_API_KEY continua opcionalmente disponível para as ferramentas de prompt
simples (verboo_code, verboo_review e ferramentas por modelo). Não grave a chave
no repositório.
Configuração por plataforma
Em qualquer cliente, o Verboo aparece como uma ferramenta MCP. Ao chamar
verboo_agent ou verboo_agent_start, o bridge inicia um subagente externo,
separado e ciente do repositório. Ele não aparece como um subagente nativo da interface.
read_only e write são apenas modos de permissão dessa execução.
Em App/IDE ou tarefa não trivial, longa, paralela ou de duração incerta, use
verboo_agent_start, mostre ojob_id, continue trabalhando e consulteverboo_jobcomstatus/result. Reserve overboo_agentsíncrono para tarefas curtas. Se o MCP não aparecer, corrija ou reinicie a integração; não substitua a chamada porverboo -p,vb,opencode runou outro shell.
Antes de configurar, descubra os caminhos absolutos:
command -v npx
command -v verboo
No Windows, descubra node.exe e a raiz global do npm pelo PowerShell:
(Get-Command node.exe).Source
npm root --global
Use esses caminhos nos exemplos abaixo. Variáveis, ~ e substituições de
comando não são expandidas dentro de JSON ou TOML.
| Cliente | Configuração | Como validar |
|---|---|---|
| Codex App, CLI e extensão IDE | ~/.codex/config.toml | App/IDE: /mcp; CLI: codex mcp get verboo-bridge |
| Claude Desktop | Settings → Developer → Edit Config | Chat: Connectors; logs em ~/Library/Logs/Claude |
| Claude Code | claude mcp add ou .mcp.json | claude mcp get verboo-bridge e /mcp |
| Cursor IDE e CLI | ~/.cursor/mcp.json ou .cursor/mcp.json | Available Tools ou cursor-agent mcp list-tools verboo-bridge |
| OpenCode | opencode.json | opencode mcp list |
Esses clientes iniciam o servidor local por stdio. Apps web ou mobile que
não conseguem executar um processo local exigem o transporte HTTP/stateless
planejado no P2; essa superfície remota ainda não está implementada.
Codex App, CLI e extensão IDE
O App, a CLI e a extensão compartilham a mesma configuração. Adicione a
~/.codex/config.toml:
[mcp_servers.verboo-bridge]
command = "/caminho/absoluto/para/npx"
args = ["--yes", "verboo-bridge@latest"]
startup_timeout_sec = 60
tool_timeout_sec = 1800
default_tools_approval_mode = "prompt"
[mcp_servers.verboo-bridge.env]
VERBOO_AGENT_ALLOWED_ROOTS = "/caminho/absoluto/para/seus/projetos"
VERBOO_AGENT_EXECUTOR = "native"
VERBOO_CODE_BIN = "/caminho/absoluto/para/verboo"
# Opcional: inclui DeepSeek V4 Pro e Mimo V2.5 Pro no ranking automático
VERBOO_AUTO_INCLUDE_PREMIUM_MODELS = "1"
No Codex App, também é possível abrir Settings → MCP servers → Add server, escolher STDIO e preencher os mesmos valores. Salve e reinicie o App. Na extensão IDE, reinicie a extensão. Consulte a documentação oficial de MCP do Codex.
No Codex App para Windows, instale os dois pacotes uma vez:
npm install --global verboo-bridge@latest @verboo/code
O CI Windows cobre a suíte de testes, não a integração com o Codex App. O smoke no Codex App Windows real ainda não foi executado.
Então use os caminhos absolutos retornados pelos comandos acima. Este exemplo
evita os shims npx.cmd e verboo.cmd, que não podem ser iniciados diretamente
com shell: false:
[mcp_servers.verboo-bridge]
command = 'C:\Program Files\nodejs\node.exe'
args = ['C:\Users\SEU_USUARIO\AppData\Roaming\npm\node_modules\verboo-bridge\index.mjs']
startup_timeout_sec = 60
tool_timeout_sec = 1800
default_tools_approval_mode = "prompt"
[mcp_servers.verboo-bridge.env]
VERBOO_AGENT_ALLOWED_ROOTS = 'C:\Users\SEU_USUARIO\Projects;D:\Work'
VERBOO_JOB_STORE_DIR = 'C:\Users\SEU_USUARIO\AppData\Local\verboo-bridge\jobs'
VERBOO_AGENT_EXECUTOR = "native"
VERBOO_CODE_BIN = 'C:\Program Files\nodejs\node.exe'
VERBOO_CODE_ENTRYPOINT = 'C:\Users\SEU_USUARIO\AppData\Roaming\npm\node_modules\@verboo\code\dist\cli.mjs'
Substitua C:\Program Files\nodejs\node.exe pela saída de
(Get-Command node.exe).Source e a raiz
C:\Users\SEU_USUARIO\AppData\Roaming\npm\node_modules pela saída de
npm root --global. Com nvm-windows, fnm, Volta, Scoop ou um prefixo global
customizado, esses caminhos são diferentes.
No Windows, separe múltiplas raízes permitidas com ;. O diretório do store
deve ser absoluto: metadados seguros e marcadores de RESTART persistem, mas
resultados públicos não são gravados porque o Node não garante uma ACL privada.
Eles podem conter código proprietário. npx --yes verboo-bridge@latest continua
suportado em terminais e clientes que executam shims .cmd; a configuração direta
acima é a opção previsível para o Codex App.
Alternativa pela CLI no macOS ou Linux:
VERBOO_PROJECTS_ROOT="$HOME/Projects"
codex mcp add verboo-bridge \
--env "VERBOO_AGENT_ALLOWED_ROOTS=$VERBOO_PROJECTS_ROOT" \
--env "VERBOO_AGENT_EXECUTOR=native" \
--env "VERBOO_CODE_BIN=$(command -v verboo)" \
-- "$(command -v npx)" --yes verboo-bridge@latest
codex mcp get verboo-bridge
O comando não adiciona os timeouts e a política de aprovação; complete esses
campos no TOML. Se o servidor já existir, não repita o add: edite o bloco
existente.
O Codex controla a aprovação da chamada MCP. Para automação não interativa com
codex exec, aprove somente as ferramentas necessárias:
[mcp_servers.verboo-bridge.tools.verboo_route]
approval_mode = "approve"
[mcp_servers.verboo-bridge.tools.verboo_agent_start]
approval_mode = "approve"
[mcp_servers.verboo-bridge.tools.verboo_job]
approval_mode = "approve"
Isso evita user cancelled MCP tool call quando não há interface para responder
ao prompt. Não use aprovação global irrestrita como atalho.
Para também aprovar verboo_validate, primeiro habilite deliberadamente
VERBOO_AGENT_VERIFY_ENABLED=1 no ambiente do bridge. Só então adicione:
[mcp_servers.verboo-bridge.tools.verboo_validate]
approval_mode = "approve"
Sem esse gate, verboo_validate falha fechado.
Claude Desktop
O Claude Desktop está disponível para macOS e Windows. Abra Settings → Developer → Edit Config e edite:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json; - Windows:
%APPDATA%\Claude\claude_desktop_config.json.
{
"mcpServers": {
"verboo-bridge": {
"command": "/caminho/absoluto/para/npx",
"args": ["--yes", "verboo-bridge@latest"],
"env": {
"VERBOO_AGENT_ALLOWED_ROOTS": "/caminho/absoluto/para/seus/projetos",
"VERBOO_AGENT_EXECUTOR": "native",
"VERBOO_CODE_BIN": "/caminho/absoluto/para/verboo"
}
}
}
}
Feche completamente o Claude Desktop e abra novamente. No chat, clique em
Add files, connectors, and more → Connectors → Manage connectors e confirme
que verboo-bridge está conectado. A configuração segue o
guia oficial de servidores MCP locais.
Claude Desktop no Windows com WSL
O Claude Desktop no Windows roda o comando configurado fora da distro WSL. Um
padrão comum é apontar command para wsl.exe e usar args com
bash -c '...', por exemplo:
{
"command": "wsl.exe",
"args": ["bash", "-c", "/home/SEU_USUARIO/.nvm/versions/node/vX.Y.Z/bin/npx --yes verboo-bridge@latest"]
}
Isso costuma falhar com "Server disconnected" sem log útil quando o Node
é instalado via nvm. Causa raiz (verificada localmente com env -i, que
simula o PATH mínimo de um shell não-login): bash -c abre um shell
não-login e não-interativo, que não lê ~/.bashrc nem o init do nvm por
padrão. O npx do nvm é um script Node com shebang #!/usr/bin/env node;
sem o diretório do nvm no PATH, o env não acha o node e o processo
morre na hora, com env: node: No such file or directory (exit 127) antes
mesmo de abrir a conexão MCP. O comportamento de bash -c não carregar
~/.bashrc é padrão do Bash em qualquer SO; se o ~/.profile/~/.bash_profile
da distro específica encadeia para ~/.bashrc (varia por distro e não foi
verificado numa instalação Windows real), isso pode ou não compensar.
Correção recomendada (à prova de PATH, não depende de shell profile):
instale o pacote globalmente uma vez, dentro de uma sessão WSL onde npm
já funciona, e aponte o Claude Desktop para o wrapper verboo-mcp do
pacote, informando o caminho do Node em VERBOO_NODE_BIN:
# uma vez, dentro do WSL
npm install --global verboo-bridge
npm root -g # confirma o caminho de lib/node_modules
{
"mcpServers": {
"verboo-bridge": {
"command": "wsl.exe",
"args": [
"bash",
"-c",
"VERBOO_NODE_BIN=/home/SEU_USUARIO/.nvm/versions/node/vX.Y.Z/bin/node VERBOO_AGENT_ALLOWED_ROOTS=/caminho/absoluto/para/seus/projetos VERBOO_AGENT_EXECUTOR=native VERBOO_CODE_BIN=/caminho/absoluto/para/verboo exec /home/SEU_USUARIO/.nvm/versions/node/vX.Y.Z/lib/node_modules/verboo-bridge/bin/verboo-mcp"
]
}
}
}
As variáveis vão dentro do comando, e não no bloco env do
claude_desktop_config.json. Aquele bloco define variáveis no ambiente do
Windows, e o wsl.exe não as repassa para dentro do WSL sem configurar
WSLENV. Declarando antes do exec, elas chegam ao processo Linux que
realmente executa o servidor.
O wrapper resolve o interpretador por VERBOO_NODE_BIN antes de qualquer
PATH de shell, então nenhuma suposição sobre o profile da distro entra em
jogo, e quando o binário informado não existe ele explica a causa no stderr
em vez de morrer sem mensagem.
Use o wrapper, e não o index.mjs direto: é ele que carrega o
VERBOO_ENV_FILE e exporta a VERBOO_API_KEY antes de subir o servidor.
Apontando para o index.mjs, quem guarda as credenciais nesse arquivo fica
sem autenticação.
Não use bash -lc como atalho. Parece resolver, mas na instalação
padrão do nvm em Ubuntu o init fica no ~/.bashrc, que começa com um
early-return para shell não-interativo. Mesmo em shell de login o node
continua fora do PATH, e o sintoma é idêntico ao original, o que só
dificulta o diagnóstico.
Se você não usa VERBOO_ENV_FILE e prefere invocar o index.mjs sem
intermediário, troque o alvo do exec pelo caminho do node seguido do
index.mjs instalado, mantendo as variáveis declaradas antes do exec.
Por fim, npx --yes verboo-bridge@latest sempre resolve a versão mais
recente do registro e pode baixar o pacote a cada início do cliente MCP,
o que soma latência e depende de rede a cada abertura do Claude Desktop.
Preferir instalação global (npm install --global verboo-bridge) evita essa
resolução de rede repetida e é o caminho mais robusto para uso contínuo.
Claude Code CLI
Para disponibilizar o bridge em todos os projetos no macOS ou Linux:
VERBOO_PROJECTS_ROOT="$HOME/Projects"
claude mcp add --transport stdio --scope user \
-e "VERBOO_AGENT_ALLOWED_ROOTS=$VERBOO_PROJECTS_ROOT" \
-e "VERBOO_AGENT_EXECUTOR=native" \
-e "VERBOO_CODE_BIN=$(command -v verboo)" \
verboo-bridge -- "$(command -v npx)" --yes verboo-bridge@latest
claude mcp get verboo-bridge
Se o bridge já estiver configurado no Claude Desktop, também é possível executar
claude mcp add-from-claude-desktop e selecionar verboo-bridge. No Claude
Code, use /mcp para conferir e aprovar o servidor. Veja a
documentação oficial do Claude Code.
Cursor IDE e CLI
Use ~/.cursor/mcp.json para todos os projetos ou .cursor/mcp.json apenas no
repositório atual:
{
"mcpServers": {
"verboo-bridge": {
"command": "/caminho/absoluto/para/npx",
"args": ["--yes", "verboo-bridge@latest"],
"env": {
"VERBOO_AGENT_ALLOWED_ROOTS": "/caminho/absoluto/para/seus/projetos",
"VERBOO_AGENT_EXECUTOR": "native",
"VERBOO_CODE_BIN": "/caminho/absoluto/para/verboo"
}
}
}
}
Reinicie o Cursor. No Agent/Composer, abra Available Tools, habilite
verboo-bridge e aprove a chamada quando solicitado. Pela CLI:
cursor-agent mcp list
cursor-agent mcp list-tools verboo-bridge
O IDE e o cursor-agent leem o mesmo formato, conforme a
documentação oficial do Cursor.
OpenCode
Adicione o servidor local ao opencode.json:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"verboo-bridge": {
"type": "local",
"command": [
"/caminho/absoluto/para/npx",
"--yes",
"verboo-bridge@latest"
],
"environment": {
"VERBOO_AGENT_ALLOWED_ROOTS": "/caminho/absoluto/para/seus/projetos",
"VERBOO_AGENT_EXECUTOR": "native",
"VERBOO_CODE_BIN": "/caminho/absoluto/para/verboo"
},
"enabled": true,
"timeout": 1800000
}
}
}
O timeout do OpenCode é expresso em milissegundos; 1800000 acompanha o teto de
30 minutos do job assíncrono. Valide com opencode mcp list. O OpenCode prefixa
as ferramentas com o nome do servidor; no prompt, peça explicitamente para usar
o MCP verboo-bridge. Veja a documentação oficial do
OpenCode.
O provedor direto abaixo só é necessário para usar executor: "opencode" como
fallback, em vez do executor nativo:
{
"provider": {
"verboo": {
"name": "Verboo",
"npm": "@ai-sdk/openai-compatible",
"options": {
"baseURL": "https://code.verboo.ai/router/v1",
"apiKey": "{env:VERBOO_API_KEY}"
},
"models": {
"deepseek-v4-flash": { "name": "DeepSeek V4 Flash", "limit": { "context": 1048576, "output": 65536 } },
"deepseek-v4-pro": { "name": "DeepSeek V4 Pro", "limit": { "context": 1048576, "output": 65536 } },
"glm-5.2": { "name": "GLM 5.2", "limit": { "context": 196608, "output": 65536 } },
"mimo-v2.5": { "name": "Mimo V2.5", "limit": { "context": 1048576, "output": 65536 } },
"mimo-v2.5-pro": { "name": "Mimo V2.5 Pro", "limit": { "context": 1048576, "output": 65536 } },
"kimi-k2.7": { "name": "Kimi K2.7", "limit": { "context": 259072, "output": 65536 } },
"minimax-m3": { "name": "Minimax M3", "limit": { "context": 1048576, "output": 65536 } },
"glm-4.7-flash": { "name": "GLM 4.7 Flash", "limit": { "context": 200704, "output": 65536 } },
"qwen3.6-27b": { "name": "Qwen 3.6 27B", "limit": { "context": 262144, "output": 65536 } }
}
}
}
}
Habilitar edição em qualquer cliente
Sem configuração adicional, o subagente permanece em read_only. Para permitir
edição, adicione ao bloco de ambiente do cliente:
VERBOO_AGENT_WRITE_ENABLED=1
Na chamada, use também mode: write. Os dois opt-ins são obrigatórios. Mesmo
nesse modo, o subagente não recebe shell, não executa testes e não faz commit,
push ou deploy; essas etapas continuam com o orquestrador.
Smoke test comum
Depois de reiniciar o cliente, execute em ordem:
Use
verboo_routepara classificar “Revise este repositório”, sem executar agente.
Inicie o subagente MCP com
verboo_agent_start,executor: native,mode: read_only,model: autoecwdapontando para o caminho absoluto deste repositório. Informe ojob_id, continue trabalhando e consulteverboo_jobaté obter o resultado. Apenas analise; não edite.
Uso
Via MCP (Claude/Codex/Cursor)
Quando o servidor MCP estiver registrado, o orquestrador terá acesso a estas ferramentas:
| Ferramenta | Descrição |
|---|---|
verboo_route | Classifica a tarefa e explica o ranking dos modelos sem executar um agente |
verboo_agent | Variante síncrona para tarefa curta; bloqueia o cliente até concluir |
verboo_agent_start | Padrão para App/IDE e trabalho não trivial; retorna job_id imediatamente |
verboo_job | Consulta jobs sem bloquear: status, result, list, cancel |
verboo_memory | Consulta ou registra uma nota técnica durável no diário isolado do projeto |
verboo_code | Codificação com um modelo escolhido em model |
verboo_review | Code review |
verboo_validate | Validação de entrega |
As ferramentas por modelo (verboo_deepseek_v4_flash, verboo_glm_5_2 e as
demais) não são mais publicadas na listagem. Elas tinham schema idêntico entre si
e custavam cerca de 900 tokens de contexto por sessão, sendo na prática o
parâmetro model de verboo_code repetido na vitrine. Escolha o modelo em
verboo_code:
{ "name": "verboo_code", "arguments": { "prompt": "...", "model": "glm-5.2" } }
Chamadas pelo nome antigo continuam funcionando: o handler resolve
verboo_<modelo> normalmente. Para voltar a publicá-las na listagem, defina
VERBOO_LIST_MODEL_TOOLS=1.
Exemplo de delegação nativa:
"Use
verboo_agent_startcomexecutor: native, em modowrite, com cwd neste repo, para editar os testes deste módulo. Informe ojob_id, continue trabalhando e consulte o resultado comverboo_job. Depois revise o diff e rode a suíte local no orquestrador."
Seleção automática e rotação
Use verboo_route quando quiser apenas saber qual modelo combina melhor com a
tarefa. A resposta inclui perfil detectado, ranking, pontuação e motivos, sem
consumir uma execução de agente.
No verboo_agent, model: "auto" é o padrão. O roteador combina:
- tipo da tarefa: codificação, segurança, revisão, UX/web, análise, contexto longo ou resposta rápida;
- afinidades declaradas de cada modelo;
- tier permitido e allowlist/denylist administrativas;
- variantes premium/Max somente quando
VERBOO_AUTO_INCLUDE_PREMIUM_MODELS=1; - execuções em andamento, uso recente, falhas e cooldown.
Isso distribui chamadas concorrentes sem round-robin cego: o melhor modelo
continua preferido, mas um segundo modelo adequado pode assumir quando o
primeiro já está ocupado. Em read_only, um erro recuperável (EXIT_ERROR ou
timeout) recalcula o ranking e tenta outro candidato. write nunca faz fallback
automático, pois a tentativa que falhou pode já ter editado arquivos. Uma escolha
manual, como model: "glm-5.2", nunca é substituída silenciosamente.
Exemplo:
{
"prompt": "Audite o isolamento multi-tenant e proponha testes",
"cwd": "/projetos/meu-saas",
"executor": "native",
"mode": "read_only",
"model": "auto"
}
O resultado informa routing.strategy, auto_include_premium_models,
selected_model, reason, ranking
e todas as attempts, para o orquestrador revisar a decisão.
Escolha do harness:
native: usa a CLI oficial e a sessão OAuth, preservando o harness Claude Code-style do Verboo.opencode: executa o mesmo agente delimitado pelo harness OpenCode e requer o provedor Verboo e a chave de API configurados.- se
executorfor omitido, valeVERBOO_AGENT_EXECUTOR; sem a variável, o padrão énative.
read_only bloqueia edição, shell, web, agentes aninhados e acesso fora do
projeto. write libera somente ferramentas de leitura e edição; shell, web,
agentes aninhados e diretórios externos permanecem desabilitados. O orquestrador
continua responsável por executar testes e outros comandos, revisar o diff,
commitar e fazer deploy. O subprocesso recebe somente uma allowlist mínima de
variáveis de ambiente; tokens de GitHub, AWS e outros serviços não são herdados.
O modo write falha fechado enquanto VERBOO_AGENT_WRITE_ENABLED não for 1.
Memória dos subagentes
Com VERBOO_MEMORY_ENABLED=1, o bridge mantém um diário JSONL separado para
cada cwd canônico. O nome do arquivo combina o nome do projeto com um hash do
caminho, impedindo que repositórios homônimos compartilhem contexto.
Ao finalizar, o agente devolve uma nota curta entre <memory_note> e
</memory_note>. O marcador é removido da resposta exibida, e somente a nota
sanitizada, o modelo, o modo, o executor e os artefatos internos são
persistidos. Prompt integral, raciocínio, código bruto, credenciais e saída
completa não são gravados. Notas sem marcador não viram memória automaticamente.
Tokens conhecidos, atribuições de credenciais, chaves privadas, e-mails, CPFs e
telefones também são redigidos novamente no caminho de leitura.
As últimas notas do projeto entram na próxima delegação com a instrução de
confirmar tudo no repositório. VERBOO_SHARED_MEMORY_FILES pode adicionar
índices curados de Codex, Claude ou Obsidian como fontes de leitura. O bridge
limita quantidade e tamanho dessas fontes; ele não varre o vault inteiro.
Os caminhos compartilhados são uma allowlist administrativa explícita e seu
conteúdo passa pela mesma redação antes de chegar ao modelo.
Gravações concorrentes são serializadas por arquivo dentro do processo do
bridge. Para decisões críticas, o orquestrador pode usar verboo_memory com
action: "remember"; para auditoria, use read ou status.
Uso manual fora dos orquestradores MCP
Os comandos abaixo são utilitários manuais. Claude, Codex, Cursor e OpenCode não
devem usá-los como fallback para verboo_agent.
# Prompt simples
vb "Explique closures em JavaScript"
# Com modelo específico e prompt de sistema
vb -m glm-5.2 -s "Seja conciso e técnico" "Analise a complexidade deste algoritmo"
# Pipe de arquivo
cat main.py | vb -m mimo-v2.5 "Revise este código"
# Listar modelos
vb --list
Orientação automática e skill
O bridge não modifica CLAUDE.md, AGENTS.md nem regras do Cursor. Ao conectar,
ele já envia instructions pelo próprio protocolo MCP para Codex, Claude,
Cursor, OpenCode e outros hosts compatíveis. Essa orientação explica que
o Verboo é um subagente externo, recomenda verboo_agent_start para App/IDE ou
trabalho não trivial, reserva verboo_agent para tarefas curtas, recomenda
executor: native e model: auto, separa read_only de write e mantém
testes, Git e deploy com o orquestrador. Ela também proíbe fallback direto para a CLI.
Para reforçar a descoberta antes mesmo da primeira chamada MCP, instale também a skill empacotada:
npx --yes --package verboo-bridge@latest verboo-install-instructions
Se já houver uma versão antiga da skill — especialmente uma que mencione fallback pela CLI — atualize-a conscientemente:
npx --yes --package verboo-bridge@latest verboo-install-instructions --force
O instalador cria a mesma skill nestes locais:
~/.agents/skills/verboo-executor— Codex e hosts compatíveis com Agent Skills;~/.claude/skills/verboo-executor— Claude Code;~/.cursor/skills/verboo-executor— Cursor IDE e CLI.
O OpenCode também descobre ~/.agents/skills. O Claude Desktop recebe a
orientação pelo MCP; ele não usa CLAUDE.md para conectores locais. Sem
--force, o instalador falha quando encontra uma skill diferente e não a
sobrescreve.
A skill ensina o padrão de delegação:
- Claude recebe a tarefa
- Claude separa em orquestração (fica com Claude) + volume (delega para a Verboo)
- Claude/Codex escolhe
executor: nativeouexecutor: opencode - Claude/Codex usa
verboo_agent_startpara trabalho não trivial, informa ojob_ide continua orquestrando;verboo_agentfica reservado para tarefa curta - Claude/Codex consulta
verboo_job, integra e valida o resultado
Planos Verboo
| Plano | Preço | Tokens | Limite | Concorrência | Modelos incluídos |
|---|---|---|---|---|---|
| Junior | R$ 75/mês | Ilimitados | 30 req/min | 4 | qwen3.6-27b, glm-4.7-flash |
| Pro | R$ 119/mês | Ilimitados | 30 req/min | 2 | qwen3.6-27b, glm-4.7-flash, mimo-v2.5, deepseek-v4-flash |
| Max | R$ 319/mês | Ilimitados | 30 req/min | 2 | qwen3.6-27b, glm-4.7-flash, deepseek-v4-flash, minimax-m3, mimo-v2.5, deepseek-v4-pro, mimo-v2.5-pro |
| Ultra | R$ 899/mês | Ilimitados | 30 req/min | 2 | qwen3.6-27b, glm-4.7-flash, mimo-v2.5, glm-5.2, kimi-k2.7, minimax-m3, deepseek-v4-flash |
Preços e limites consultados em 28/07/2026. Confirme os planos oficiais do Verboo Code antes de assinar. Growth API (R$ 600/mês, 100 req/min com
qwen3.6-27b) e Enterprise são ofertas separadas dos planos individuais.
Exemplos reais
Revisão de código em lote
# Revisar vários arquivos de uma vez com Verboo
for f in src/**/*.ts; do
cat "$f" | vb -m mimo-v2.5 -s "Revise este arquivo TypeScript" > "reviews/$(basename $f).review.md"
done
Refatoração assistida
sequenceDiagram
participant Vc as Você
participant C as Claude Code
participant VB as Verboo Bridge
Vc->>C: Refatore este módulo
C->>VB: verboo_code("Extraia a lógica de pagamento")
VB-->>C: Código refatorado
C->>VB: verboo_review(resultado)
VB-->>C: Revisão aponta 2 melhorias
C->>Vc: Resultado final revisado
Geração de testes
"Claude, use o
verboo_codepara gerar testes unitários para cada função neste módulo. Depois execute e me diga se passam."
Recursos do servidor MCP
O servidor também expõe recursos e prompts:
| Tipo | URI | Descrição |
|---|---|---|
| Recurso | verboo://models | Lista de modelos com especificações |
| Recurso | verboo://status | Status da conexão |
| Prompt | revisar-codigo | Template de code review |
| Prompt | refatorar | Template de refatoração |
| Prompt | explicar | Template de explicação |
Variáveis de ambiente
| Variável | Padrão | Descrição |
|---|---|---|
VERBOO_API_KEY | — | Necessária para ferramentas de prompt direto e para executor: opencode; não é repassada ao executor nativo |
VERBOO_BASE_URL | https://code.verboo.ai/router/v1 | URL base da API |
VERBOO_LOG_LEVEL | info | Nível de log: debug, info, warn, error |
VERBOO_AGENT_ALLOWED_ROOTS | — | Raízes repo-aware separadas pelo delimitador de paths do SO; sem valor, verboo_agent falha fechado |
VERBOO_AGENT_WRITE_ENABLED | — | Defina 1 para habilitar write; por padrão, somente read_only é aceito |
VERBOO_AGENT_MAX_CONCURRENCY | 4 | Execuções simultâneas globais, incluindo jobs assíncronos; inteiro entre 1 e 8, valores inválidos usam 4 |
VERBOO_JOB_STORE_DIR | — | Diretório para persistência atômica de metadados seguros e recuperação de jobs interrompidos; em macOS/Linux, use diretório privado 0700/0600 |
VERBOO_JOB_PERSIST_RESULTS | — | Em macOS/Linux, defina 1 com VERBOO_JOB_STORE_DIR privado 0700/0600 para persistir e recuperar o resultado público terminal. No Windows falha fechado: resultados não são gravados porque o Node não garante ACL privada. Pode conter código proprietário; nunca grava prompt, runner data, cwd, env, raciocínio, memory note ou mensagens de erro |
VERBOO_JOB_TTL_MS | 1800000 (30 min) | TTL em ms para jobs finalizados sem resultado |
VERBOO_JOB_RESULT_TTL_MS | 600000 (10 min) | TTL em ms para resultados de jobs |
VERBOO_JOB_MAX_RESULTS | 100 | Máximo de resultados mantidos em memória (até 500) |
VERBOO_JOB_MAX_QUEUED | 50 | Máximo de jobs aguardando na fila |
VERBOO_AGENT_MAX_MODEL_ATTEMPTS | 2 | Tentativas de modelos no modo auto + read_only; inteiro entre 1 e 3 |
VERBOO_AGENT_EXECUTOR | native | Padrão administrativo; cada chamada pode substituir por native ou opencode |
VERBOO_AGENT_VERIFY_ENABLED | — | Defina 1 para habilitar verboo_validate; por padrão falha fechado |
VERBOO_AGENT_VERIFY_PROJECT_CODE_ENABLED | — | Segundo opt-in obrigatório para npm test/npm run; não é sandbox: executa código confiável com o usuário do bridge e pode escrever, ler arquivos/configs acessíveis e usar rede |
VERBOO_AGENT_VERIFY_NPM_SCRIPTS | — | Scripts separados por vírgula permitidos para npm run; npm test continua sujeito ao segundo opt-in |
VERBOO_MEMORY_ENABLED | — | Defina 1 para ativar memória técnica persistente dos subagentes |
VERBOO_MEMORY_DIR | ~/.local/share/verboo-bridge/memory | Diretório dos diários JSONL isolados por projeto |
VERBOO_SHARED_MEMORY_FILES | — | Arquivos de memória curada, somente leitura, separados pelo delimitador de paths do SO |
VERBOO_MODEL_ALLOWLIST | todos | Modelos permitidos em todas as frentes (tools diretas, schemas, recursos, prompts, preview e agentes), separados por vírgula |
VERBOO_MODEL_DENYLIST | — | Modelos bloqueados em todas as frentes; são ocultados dos schemas/recursos e rejeitados antes de rede ou fila |
VERBOO_MODEL_TIERS | pro,max,ultra | Grupos internos permitidos no roteamento, preview e seleção manual; não substitui a allowlist da assinatura |
VERBOO_AUTO_INCLUDE_PREMIUM_MODELS | — | Defina exatamente 1 para incluir variantes premium marcadas como manuais no ranking automático. Ausente, 0 ou outro valor preserva o comportamento padrão. Allowlist, denylist, tiers e política do executor continuam valendo. |
VERBOO_LIST_MODEL_TOOLS | — | Defina 1 para voltar a publicar uma tool por modelo na listagem. Ausente, as chamadas por nome antigo seguem funcionando, mas as tools não aparecem na descoberta. |
VERBOO_MODEL_COOLDOWN_SECONDS | 60 | Cooldown de um modelo após falha recuperável |
VERBOO_CODE_BIN | verboo | Executável da CLI oficial; pode ser Node quando VERBOO_CODE_ENTRYPOINT estiver definido |
VERBOO_CODE_ENTRYPOINT | — | Caminho opcional para @verboo/code/dist/cli.mjs |
VERBOO_NATIVE_MODEL_ALLOWLIST | todos | Modelos comprovadamente saudáveis no OAuth do executor nativo; impede seleção silenciosa de modelos listados pela CLI, mas indisponíveis na conta |
VERBOO_OPENCODE_MODEL_ALLOWLIST | todos | Modelos permitidos especificamente no executor OpenCode |
VERBOO_OPENCODE_BIN | opencode | Caminho do OpenCode 1.17.9+ |
VERBOO_ENV_FILE | — | Arquivo opcional lido por bin/verboo-mcp para obter VERBOO_API_KEY sem source |
VERBOO_NODE_BIN | node | Binário Node usado por bin/verboo-mcp |
Solução de problemas
| Sintoma | Verificação e correção |
|---|---|
verboo: command not found | Rode npm install --global @verboo/code e configure VERBOO_CODE_BIN com a saída de command -v verboo. |
VERBOO_AUTH_REQUIRED | Rode verboo auth login, confirme com verboo auth status --text e reinicie o cliente MCP. |
CWD_NOT_ALLOWED ou ALLOWED_ROOTS_MISSING | Use caminhos absolutos e inclua a raiz do projeto em VERBOO_AGENT_ALLOWED_ROOTS. |
| O bridge não aparece no Codex | Rode codex mcp get verboo-bridge, abra uma nova sessão e confira /mcp. |
user cancelled MCP tool call no codex exec | A chamada aguardava aprovação sem terminal interativo. Use o Codex interativo ou aprove somente a ferramenta necessária no TOML. |
O cliente abriu Shell e executou verboo -p | O MCP não foi usado. Confirme verboo_agent na lista de ferramentas, atualize a skill com verboo-install-instructions --force, remova orientações antigas de fallback por CLI e reinicie o cliente. |
write inicia, mas Edit/Write são negados por dontAsk | Atualize para [email protected] ou superior e reinicie o cliente. O executor nativo usa bypassPermissions; o modo escolhido pelo orquestrador ainda delimita as ferramentas, e shell, web, hooks, agentes aninhados e segredos continuam negados. |
| A chamada termina perto de 60 segundos | Defina tool_timeout_sec = 1800 ou use verboo_agent_start com verboo_job. |
Aviso sobre VERBOO_API_KEY no modo nativo | A chave não é necessária para verboo_agent com OAuth; ela serve apenas às ferramentas de API. |
Claude Desktop no Windows/WSL mostra Server disconnected sem log | bash -c (shell não-login) não carrega o nvm, então node some do PATH e o npx do nvm morre na hora. Veja Claude Desktop no Windows com WSL. |
Desenvolvimento
git clone https://github.com/nikolasdehor/verboo-bridge.git
cd verboo-bridge
npm install
node index.mjs
npm test
Testar o servidor MCP:
# Inicializar e listar ferramentas
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | node index.mjs
Licença
MIT — use, modifique, compartilhe.
// faq
What is verboo-bridge?
MCP server to use Verboo AI models as sub-agents in Claude Code, Codex, and any MCP client. It is open-source on GitHub.
Is verboo-bridge free to use?
verboo-bridge is open-source under the MIT license, so it is free to use.
What category does verboo-bridge belong to?
verboo-bridge is listed under productivity in the Claudeers registry of Claude-compatible tools.
// embed badge
[](https://claudeers.com/verboo-bridge)
// retro hit counter
[](https://claudeers.com/verboo-bridge)
// reviews
// guestbook
// related in Productivity
Agent skills for Obsidian. Teach your agent to use Obsidian CLI and open formats including Markdown, Bases, JSON Canvas.
Open source repository of plugins primarily intended for knowledge workers to use in Claude Cowork
Garry's Opinionated OpenClaw/Hermes Agent Brain
An open-source alternative to Claude Cowork (powered by opencode)