Agy Bridge

User → Claude Code → agy-bridge (MCP) → agy CLI → Gemini / Claude / GPT-OSS
                   ←                  ←          ←

Por que isto em vez de claude-to-agy?

	claude-to-agy	agy-bridge
Superfície de ferramentas	1 delegate_to_agy genérico	6 ferramentas específicas — Claude se auto-roteia de forma confiável
Seleção de modelo	nenhum (apenas padrão do agy)	roteamento por ferramenta em todos os agy models, com detecção de disponibilidade e fallback
Multi-turn	sem estado	continuidade de sessão — follow_up retoma conversas do agy sem reenviar contexto
Segurança de saída	ilimitado	limite de truncamento configurável protege o contexto do Claude
Sandbox	não	modo --sandbox opcional
Instalação	uvx (Python)	npx (Node) — instalação zero

Requisitos

• Node.js 18+
• Antigravity CLI (agy) instalado e autenticado
• Claude Code

Instalação

# 1. Register the MCP server (user scope = all projects).
#    add-json bakes in a generous client-side timeout so long analyze_files /
#    delegate calls don't trip Claude Code's tool-call deadline (see Timeouts).
claude mcp add-json -s user agy-bridge \
  '{"command":"npx","args":["-y","agy-bridge"],"timeout":600000}'

# 2. Add delegation rules to your project (or ~/.claude/CLAUDE.md for global)
curl -o CLAUDE.md https://raw.githubusercontent.com/sshahzaiib/agy-bridge/main/CLAUDE.md

O "timeout": 600000 (10 min, em milissegundos) é o prazo de chamada de ferramenta do lado do cliente — sem ele, um analyze_files de inicialização a frio (~40–50s) ou um delegate longo pode atingir o padrão do Claude Code e retornar timed out waiting for response enquanto a execução do agy ainda está em andamento. Se o seu cliente não honrar um timeout por servidor, defina a variável de ambiente global MCP_TOOL_TIMEOUT=600000 em vez disso. Detalhes e os orçamentos do lado do agy estão em Tempos limite e cancelamento.

Ferramentas

Ferramenta	Uso para	Roteamento de modelo (primeiro disponível)
analyze_files	Arquivos >200 linhas, >3 arquivos de uma vez, logs, dumps, código gerado	Gemini 3.5 Flash (High) → Gemini 3.1 Pro (Low)
deep_search	arqueologia de git log/diff/blame, greps em todo o repositório	Gemini 3.5 Flash (Medium) → (High)
web_lookup	Documentação, referências de API, conhecimento externo/atual	Gemini 3.5 Flash (Medium) → (High)
adversarial_review	Críticas de planos, revisões de design e código	Gemini 3.1 Pro (High) → Claude Opus 4.6 (Thinking) → Flash (High)
follow_up	Continuar uma sessão anterior por session_id — sem reenvio de contexto	herda a sessão
delegate	Qualquer outra coisa pesada	Gemini 3.5 Flash (High)

Todas as ferramentas aceitam cwd opcional (raiz do projeto) e model (nome exato de agy models; validado, com modelos disponíveis listados em caso de incompatibilidade).

Toda resposta termina com um rodapé:

---
[agy-bridge] model: Gemini 3.5 Flash (High) | session: 1f0c…-d4 (use follow_up to continue)

Roteamento de modelo

No primeiro uso, a ponte executa agy models (em cache durante a vida do processo) e escolhe o primeiro modelo disponível na cadeia de preferência da ferramenta. Se nenhum estiver disponível, ela recorre a AGY_DEFAULT_MODEL e, por fim, ao padrão do próprio agy. O agy ignora silenciosamente valores desconhecidos de --model, então a ponte valida os nomes antecipadamente em vez de deixar as solicitações caírem no modelo errado.

Failover ciente de cota

O agy nunca expõe a exaustão de cota no modo de impressão — ele tenta silenciosamente o 429 até o seu print-timeout, então sai com código 0 e saída vazia, o que costumava parecer um travamento indefinido. A ponte agora monitora o arquivo de log de cada execução (via --log-file) e, em RESOURCE_EXHAUSTED (code 429):

1. mata o grupo de processos do agy imediatamente (sem esperar o timeout),
2. analisa o tempo de redefinição ("Resets in 4h24m") em um registro de resfriamento em processo,
3. tenta novamente o mesmo prompt no próximo modelo da cadeia da ferramenta,
4. pula modelos em resfriamento em todas as chamadas subsequentes até que suas cotas sejam redefinidas.

Os failovers são anotados no rodapé da resposta (failover: <model>: quota exhausted (resets in 4h24m)). Somente quando todos os candidatos são esgotados a chamada falha — em segundos, com os tempos de redefinição listados — em vez de travar.

Tempos limite e cancelamento

Cada ferramenta tem seu próprio timeout padrão dimensionado para sua tarefa: web_lookup 120s, deep_search 180s, analyze_files / adversarial_review / follow_up 300s, delegate 600s. Definir AGY_TIMEOUT explicitamente substitui todos de uma vez. Para alterar uma única ferramenta, defina AGY_TIMEOUT_<TOOL_NAME> em vez disso (por exemplo, AGY_TIMEOUT_DEEP_SEARCH=300); uma substituição por ferramenta tem precedência sobre o AGY_TIMEOUT global e o padrão da ferramenta. O conjunto completo de variáveis por ferramenta é AGY_TIMEOUT_ANALYZE_FILES, AGY_TIMEOUT_DEEP_SEARCH, AGY_TIMEOUT_WEB_LOOKUP, AGY_TIMEOUT_ADVERSARIAL_REVIEW, AGY_TIMEOUT_FOLLOW_UP e AGY_TIMEOUT_DELEGATE. O caminho de kill escala SIGTERM → SIGKILL em todo o grupo de processos, e o prazo dispara mesmo se os processos auxiliares do agy mantiverem os pipes de saída abertos. Cancelar a chamada de ferramenta a partir do cliente MCP (por exemplo, pressionando Esc no Claude Code) também mata a execução do agy em vez de órfã-la.

Duas camadas de timeout — alinhe-as. Os timeouts acima são o orçamento do lado do agy. Seu cliente MCP (Claude Code) tem seu próprio timeout de chamada de ferramenta separado, e se ele for menor que o orçamento do agy, o cliente desiste primeiro — você verá Error: timed out waiting for response (nota: o timeout do próprio agy-bridge lê agy timed out after Ns em vez disso). O trabalho não é perdido: a sessão do agy persiste, então follow_up com o session_id retornado recupera o resultado. Mas a correção real é fazer o cliente esperar pelo menos tanto quanto o agy: o comando Instalação já define um timeout por servidor de 600000ms (escopo apenas para a entrada do agy-bridge). Se você registrou o servidor sem isso, execute novamente o comando add-json da Instalação, ou defina a variável de ambiente global MCP_TOOL_TIMEOUT=600000. Regra prática: timeout do cliente ≥ orçamento do agy.

Latência esperada. A maior parte da "lentidão" percebida é a inicialização a frio: a primeira chamada em uma sessão inicia a CLI do agy e aquece o modelo. Um simples analyze_files sobre 3 arquivos mede cerca de 40–50s a frio (≈46s observados), caindo em chamadas subsequentes na mesma sessão. Uma primeira chamada que também atinge uma cota 429 leva mais tempo enquanto a ponte faz o failover. Portanto, um timeout de cliente abaixo de ~60s vai tropeçar intermitentemente em inicializações a frio mesmo para perguntas "simples" — dimensione-o generosamente.

Configuração

Todas opcionais, via variáveis de ambiente:

Variável	Padrão	Descrição
AGY_PATH	agy	Caminho para o binário do agy
AGY_TIMEOUT	por ferramenta	Segundos; substitui todos os timeouts por ferramenta de uma vez (veja acima), passado como --print-timeout, aplicado com uma margem de 15s para kill
AGY_TIMEOUT_<TOOL>	por ferramenta	Segundos; substitui o timeout de apenas uma única ferramenta, ex.: AGY_TIMEOUT_DEEP_SEARCH=300. Vence sobre AGY_TIMEOUT
AGY_MAX_OUTPUT_CHARS	50000	Limite de truncamento para saída da ferramenta
AGY_DEFAULT_MODEL	não definido	Modelo de fallback quando nenhuma entrada da cadeia está disponível
AGY_SKIP_PERMISSIONS	true	Passa --dangerously-skip-permissions para o agy
AGY_SANDBOX	false	Executa o agy com --sandbox
AGY_ON_FAILURE	fallback	strict anexa uma instrução aos erros de ferramenta com falha dizendo ao agente chamador para não absorver o trabalho em si

Comportamento de falha

A ponte sempre falha de forma ruidosa: erros do agy aparecem como erros de ferramenta MCP com o stderr real do agy, e o roteamento de modelo degradado é anotado no rodapé da resposta. Por padrão, o agente chamador (Claude) normalmente fará o trabalho sozinho após uma falha — visível na transcrição, mas fácil de deixar de notar em uma sessão longa. Defina AGY_ON_FAILURE=strict para anexar uma instrução explícita "não faça este trabalho você mesmo — relate a falha ao usuário" a cada erro de delegação, para que você mantenha o controle sobre quando as economias de tokens são silenciosamente perdidas.

Desenvolvimento

npm install
npm test           # vitest unit tests (exec mocked — no agy needed)
npm run typecheck
npm run build      # tsup → dist/index.js

Contribuidores

Contribuições são bem-vindas — abra uma issue ou PR.

Histórico de estrelas

Licença

MIT