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.

O codex-agy-bridge encapsula 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 com capacidade MCP via stdio
A CLI oficial do Antigravity (agy), já autenticada localmente
uv / uvx
tmux e um lançador de terminal suportado:

# macOS
brew install tmux

# Debian/Ubuntu Linux (x-terminal-emulator is also supported)
sudo apt install tmux gnome-terminal

Verifique os comandos necessários:

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

Autenticação no Dia 0

agy --version apenas prova que o binário existe. Antes de adicionar o servidor MCP, execute agy models; se o Antigravity pedir para você entrar ou informar que você não está conectado, inicie uma sessão visível e complete o fluxo de login no navegador:

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. Complete 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 o Codex CLI:

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 para 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 objetivos: crie um objetivo, inicie alvos nomeados com paralelismo limitado e inspecione todo o lote como um esforço coordenado.
Eventos de despertar 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 escritas obsoletas quando cursores de evento ou transcrição mudaram após o chamador observar a execução.
Observabilidade ciente de trajetória: resumos de transcrição limitados 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 mute silenciosamente a máquina dele.

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 completar o fluxo de autenticação do Dia 0 acima antes de adicionar o servidor MCP.
Então 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 do 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 do 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 possuem 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	Propósito
`agy_run_start`	Iniciar, continuar ou abrir uma execução interativa em primeiro plano
`agy_run_wait`	Polling curto até que execuções selecionadas emitam eventos de despertar 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 objetivos, iniciar alvos e ler status agregado
`agy_admin`	Ler diagnósticos, modelos, plugins, validação e changelog

Omita model (ou passe null) para deixar o Agy escolher seu padrão: a ponte armazena model: null e não envia --model. Isso se aplica a execuções, ferramentas de revisão e objetivos, cujos alvos herdam a seleção de seu objetivo. Seleções explícitas são validadas contra agy models, incluindo o antigo padrão Gemini 3.5 Flash (Medium) da ponte; seleções desconhecidas e vazias são rejeitadas. A ponte nunca substitui a primeira entrada do catálogo. agy_admin(action="models") relata default_model: null e default_model_source: "agy_cli"; isso descreve delegação, não um modelo de provedor efetivo observado.

Execuções e objetivos persistidos existentes retêm suas strings de modelo e permanecem legíveis. Eles não são silenciosamente migrados para um modelo diferente. Novos lançamentos de um objetivo antigo revalidam sua seleção e a rejeitam se não estiver mais disponível; crie um novo objetivo com um modelo disponível ou omita a seleção para delegar ao Agy. Execuções previamente reservadas retêm sua política de comando original. Novas solicitações delegadas têm chaves de deduplicação distintas das seleções de modelo explícitas. Versões mais antigas da ponte que exigem uma string de modelo de objetivo não podem ler novos objetivos de modelo nulo; evite fazer downgrade com esses objetivos em uso.

Fluxo típico:

agy_run_start -> agy_run_wait -> agy_run_observe -> agy_run_result

No MCP do Codex, 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 recebe run_ids: ["..."], mesmo para uma única execução. Condições de espera suportadas são any_attention, any_terminal, all_terminal, any_event e 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	Propósito
`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 objetivos
`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 sob ~/.local/state/codex-agy-bridge/.

Status e Risco

Este projeto é experimental. Atualmente tem como alvo Python 3.11+, macOS ou Linux com um lançador de terminal suportado, tmux e comandos e arquivos de trajetória compatíveis com a CLI do Antigravity 1.0.8.

O Antigravity é uma CLI agêntica. Ele 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 habilita a política de pular permissões perigosas 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 conversa local 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, constrói distribuições, publica no PyPI via GitHub OIDC, cria um release do 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 da ferramenta MCP.

Licença

MIT