Async Parallel Antigravity for Codex & Claude Code

Execute sessões CLI Antigravity paralelas, retomáveis e operáveis por humanos a partir do Codex, Claude Code ou qualquer agente compatível com MCP.

GitHub

Experimente este MCPPatrocinado

Documentação

codex-agy-bridge

Execute o Antigravity a partir de um harness de agente como sessões agy duráveis, paralelas e operáveis por humanos via MCP.

codex-agy-bridge envolve a CLI oficial do Antigravity com um plano de controle MCP retomável. Harnesses de agente como Codex, Claude Desktop ou seu próprio cliente MCP baseado em GPT/Claude podem iniciar execuções agy, aguardar eventos esparsos, anexar um terminal real, enviar entrada protegida, cancelar com segurança, continuar conversas exatas e coletar resultados finais posteriormente por run_id.

Instalação Rápida

Pré-requisitos:

Codex CLI para o comando abaixo, ou outro harness local compatível com MCP via stdio
A CLI oficial do Antigravity (agy), já autenticada localmente
uv / uvx
tmux no macOS:

brew install tmux

Verifique os comandos necessários:

codex --version
agy --version
agy models
uvx --version
tmux -V

Autenticação do Dia 0

agy --version apenas prova que o binário existe. Antes de adicionar o servidor MCP, execute agy models; se o Antigravity pedir que você faça login ou informar que você não está autenticado, inicie uma sessão visível e conclua o fluxo de navegador/login:

agy --prompt-interactive "Authenticate Antigravity and then exit."
agy models

Após agy models ser bem-sucedido, instale ou reinicie o servidor MCP. Se uma execução da ponte ainda encontrar problemas de autenticação, agy_run_start retorna status="auth_required" e abre uma sessão de autenticação agy visível por padrão. Conclua o login lá e inicie uma nova execução. Você também pode usar agy_run_observe(view="terminal") ou agy_admin(action="doctor") para inspecionar o status de autenticação necessária.

Instale a partir do PyPI com a CLI do Codex:

codex mcp add codex-agy-bridge \
  --env AGY_CMD="$(command -v agy)" \
  -- "$(command -v uvx)" codex-agy-bridge@latest

Reinicie o harness e verifique no Codex se você usou o comando acima:

codex mcp get codex-agy-bridge
codex mcp list

Remova com:

codex mcp remove codex-agy-bridge

Para Claude Desktop ou um cliente MCP personalizado, use o mesmo formato de comando stdio: uvx codex-agy-bridge@latest com AGY_CMD definido como o executável agy autenticado.

O Que Torna Diferente

Sessões Antigravity paralelas: inicie múltiplas execuções agy independentes, cada uma com seu próprio estado durável, logs, projeção de transcrição e resultado.
Terminais operáveis por humanos: execuções em primeiro plano vivem em sessões tmux persistentes, para que o Terminal.app possa anexar sem matar o agente.
Controle MCP retomável: chamadas MCP podem expirar, o harness pode reiniciar, e a execução ainda pode ser observada posteriormente por run_id.
Orquestração de metas: crie uma meta, inicie alvos nomeados com paralelismo limitado e inspecione todo o lote como um esforço coordenado.
Eventos de ativação esparsos: agy_run_wait faz polling curto de eventos de ciclo de vida, atenção, progresso e terminal sem spam de polling de transcrição.
Entrada protegida: agy_run_input pode rejeitar gravações obsoletas quando cursores de evento ou transcrição mudaram após o chamador observar a execução.
Observabilidade ciente de trajetória: resumos limitados de transcrição e evidências de terminal são expostos sem raciocínio privado do modelo.
Higiene operacional: inícios ativos duplicados são deduplicados, grupos de processos são cancelados com segurança e artefatos de resultado concluídos são preservados.

Detalhes de Instalação

Se Você É Um Agente Lendo Isto

Ajude o usuário a instalá-lo; não altere a máquina dele silenciosamente.

Verifique os pré-requisitos primeiro:

command -v codex
command -v agy
command -v uvx
command -v tmux
agy --version
agy models

Se algo estiver faltando, pergunte antes de instalar.
Se agy models relatar um erro de autenticação, ajude o usuário a concluir o fluxo de autenticação do Dia 0 acima antes de adicionar o servidor MCP.
Em seguida, execute:

codex mcp add codex-agy-bridge \
  --env AGY_CMD="$(command -v agy)" \
  -- "$(command -v uvx)" codex-agy-bridge@latest

Verifique:

codex mcp get codex-agy-bridge
codex mcp list

Diga ao usuário para reiniciar o harness de agente para que as novas ferramentas MCP sejam carregadas.

PyPI

O comando de Instalação Rápida armazena uma definição de servidor MCP via stdio. Quando o harness de agente inicia o servidor, uvx resolve codex-agy-bridge@latest do PyPI, instala-o em um ambiente em cache isolado e executa o script de console codex-agy-bridge. AGY_CMD fixa a ponte ao executável agy já instalado e autenticado do usuário.

Não substitua $ ou $(...) manualmente no comando. Em shells POSIX, $(command -v agy) e $(command -v uvx) expandem para caminhos absolutos de executáveis.

GitHub

Use isto quando quiser a versão do repositório diretamente:

codex mcp add codex-agy-bridge \
  --env AGY_CMD="$(command -v agy)" \
  -- uvx --from git+https://github.com/varadfromeast/codex-agy-bridge \
  codex-agy-bridge

Desenvolvimento Local

git clone https://github.com/varadfromeast/codex-agy-bridge.git
cd codex-agy-bridge
uv sync --extra dev

codex mcp add codex-agy-bridge \
  --env AGY_CMD="$(command -v agy)" \
  -- uv --directory "$PWD" run codex-agy-bridge

Como Funciona

flowchart LR
  H["Agent harness<br/>(Codex, Claude, custom MCP client)"]
  M["codex-agy-bridge<br/>MCP stdio server"]
  S["Durable control plane<br/>runs, goals, events, results"]
  W["Detached run supervisor"]
  A["Antigravity CLI<br/>agy"]
  T["Persistent tmux session<br/>human attach/input"]
  L["Local Antigravity<br/>trajectory files"]

  H <-->|"MCP tools"| M
  M <--> S
  S --> W
  W --> A
  W <--> T
  A --> L
  W -->|"bounded transcript projection"| S
  T -->|"terminal logs and attention prompts"| S

A ponte mantém o servidor MCP responsivo enquanto supervisores destacados controlam os processos agy de longa duração. Estado e eventos são persistidos localmente, para que uma execução possa continuar após a chamada MCP original retornar. Para o modelo de processo mais profundo, veja docs/ARCHITECTURE.md. Para a visão do loop de controle MCP, veja docs/MCP_VISION.md.

Ferramentas MCP

Ferramenta	Finalidade
`agy_run_start`	Iniciar, continuar ou abrir uma execução interativa em primeiro plano
`agy_run_wait`	Fazer polling curto até que execuções selecionadas emitam eventos de ativação esparsos
`agy_run_observe`	Ler visualizações completas, de status, transcrição ou terminal bruto
`agy_run_input`	Enviar entrada com pré-condições opcionais de evento/transcrição
`agy_run_cancel`	Cancelar uma execução ativa
`agy_run_result`	Ler metadados de resultado final ou blocos de resultado limitados
`agy_goal`	Criar metas, iniciar alvos e ler status agregado
`agy_admin`	Ler diagnósticos, modelos, plugins, validação e changelog

Fluxo típico:

agy_run_start -> agy_run_wait -> agy_run_observe -> agy_run_result

No Codex MCP, as ferramentas podem ser expostas com o prefixo do servidor, por exemplo codex_agy_bridge_agy_run_wait. As respostas de execução incluem argumentos exatos de wait_call; observe que agy_run_wait sempre aceita run_ids: ["..."], mesmo para uma única execução. As condições de espera suportadas são any_attention, any_terminal, all_terminal, any_event e os aliases attention, terminal, finished, finish, complete, completed, result, all_finished, all_complete e all_completed.

Use agy_goal quando o harness deve dividir o trabalho em alvos nomeados com um objetivo compartilhado e paralelismo limitado.

Configuração

Variável	Padrão	Finalidade
`AGY_CMD`	`agy` em `PATH`	Executável exato do Antigravity
`AGY_BRIDGE_STATE_DIR`	`~/.local/state/codex-agy-bridge`	Estado durável de execuções e metas
`AGY_BRIDGE_AGY_ROOT`	`~/.gemini/antigravity-cli`	Conversas e trajetórias do Antigravity
`AGY_BRIDGE_MAX_PARALLEL`	`50`	Limite global de execuções concorrentes
`AGY_BRIDGE_COMPLETION_STABILITY_SECONDS`	`150`	Tempo que um marcador final deve permanecer estável
`AGY_BRIDGE_MCP_WAIT_SLICE_SECONDS`	`120`	Máximo de segundos que uma única chamada MCP `agy_run_wait` bloqueia antes de retornar um snapshot para que gateways não expirem

O estado da execução sobrevive a reinicializações do servidor MCP em ~/.local/state/codex-agy-bridge/.

Status e Riscos

Este projeto é experimental. Atualmente tem como alvo Python 3.11+, macOS, tmux e comandos e arquivos de trajetória compatíveis com a CLI 1.0.8 do Antigravity.

Antigravity é uma CLI agêntica. Ela pode ler e escrever arquivos, executar comandos e acessar a rede com os privilégios do usuário atual. Esta ponte não é uma sandbox ou limite de segurança.

A ponte sempre ativa a política perigosa de pular permissões do Antigravity para que execuções não supervisionadas não travem em prompts de aprovação da CLI. Qualquer entrada dangerously_skip_permissions=false é rejeitada; o único valor permitido é true. sandbox=true e additional_directories são dicas de política da CLI, não contenção de sistema de arquivos.

A ponte não lê nem copia credenciais OAuth do Antigravity. Ela invoca o binário agy instalado e lê metadados comuns de conversas locais e arquivos de trajetória.

Desenvolvimento

git clone https://github.com/varadfromeast/codex-agy-bridge.git
cd codex-agy-bridge
uv sync --extra dev
uv run pytest
uv run ruff check .
uv build

Execute o servidor diretamente:

uv run codex-agy-bridge

O servidor usa transporte stdio. Não imprima texto de diagnóstico no stdout; isso corromperia o enquadramento MCP.

Publicação

Uma tag de versão enviada executa .github/workflows/publish.yml, que verifica versões, executa verificações, compila distribuições, publica no PyPI via GitHub OIDC, cria um release no GitHub e publica server.json no Registro MCP.

Compatibilidade

O leitor atual espera JSONL de trajetória do Antigravity em:

~/.gemini/antigravity-cli/brain/<conversation-id>/
  .system_generated/logs/transcript.jsonl

Se o Antigravity migrar para SQLite ou uma API de daemon local, um novo adaptador pode substituir este leitor sem alterar o contrato das ferramentas MCP.

Licença

MIT