⚡ AGV-Codex Bridge

Universal Dual-Engine Bridge & Dynamic QA Inspector between Google Antigravity (AGV) and OpenAI Codex CLI via Model Context Protocol (MCP)

🌟 The Vision

agv-codex-bridge turns your Google Antigravity IDE and OpenAI Codex CLI into a seamless, automated collaborative pair for end-to-end software development:

• Antigravity (AGV) acts as the Lead Developer (full filesystem access, code generation, refactoring, test execution, and bug fixing).

• Codex CLI acts as the Independent Adversarial QA Auditor (read-only execution, deep edge-case hunting, security audit, and accessibility verification).

• You (Tech Lead) orchestrate and review everything through the Live Inspector Dashboard or Interactive Terminal Streaming.

Related MCP server: superpower-codex-mcp

🚀 Cara Menjalankan / Instalasi

Terdapat beberapa cara untuk menjalankan agv-codex-bridge tergantung kondisi proyek Anda:

🌟 Opsi 1: Menjalankan dari Repositori Lokal / Klon Git

Jika Anda melakukan git clone repositori ini ke komputer Anda, jalankan npm link sekali saja di dalam direktori agv-codex-bridge:

# Masuk ke direktori hasil clone agv-codex-bridge
cd /path/to/agv-codex-bridge

# Daftarkan command CLI secara global di sistem lokal
npm link

Setelah itu, buka direktori proyek target Anda (misal: future-of-work) dan jalankan CLI secara langsung:

cd /path/to/proyek-anda

# 1. Inisialisasi konfigurasi MCP & skills ke dalam proyek
agv-codex init

# 2. Cek status & konektivitas Codex CLI
agv-codex doctor

# 3. Jalankan Dynamic Live QA Dashboard
agv-codex dashboard --port=4567

# 4. Jalankan Terminal QA Audit langsung
agv-codex run qa

📂 Opsi 2: Eksekusi Langsung via Node / NPX Path (Tanpa npm link)

Jika Anda ingin langsung mengeksekusi script dari direktori proyek target tanpa mendaftarkan npm link:

cd /path/to/proyek-anda

# Jalankan init langsung menunjuk ke file CLI / path repositori
node /path/to/agv-codex-bridge/bin/cli.mjs init

# Atau menggunakan npx pointing ke folder lokal
npx /path/to/agv-codex-bridge init

🌐 Opsi 3: Install Global dari URL Git

Anda juga dapat menginstalnya secara global langsung dari repository Git:

npm install -g git+https://github.com/USER/agv-codex-bridge.git

# Lalu di direktori proyek manapun:
agv-codex init

📦 Opsi 4: One-Command via NPM Registry

Menginstall via npm registry:

# 1. Run Setup Wizard
npx agv-codex init

# 2. Check System Health
npx agv-codex doctor

# 3. Launch Live Dashboard
npx agv-codex dashboard --port=4567

# 4. Terminal QA Audit
npx agv-codex run qa src/components/Hero.tsx

Open http://localhost:4567 in your browser to inspect live audits in real-time.

🔍 What npx agv-codex init Does Automatically (Under the Hood)

When you run npx agv-codex init, the setup wizard executes transparently without touching your source code:

1. Auto-Detects Local Codex CLI & Auth:

   • Scans system PATH (~/.local/bin/codex, /usr/local/bin/codex, or which codex).

   • Validates active ChatGPT Plus / Codex CLI authentication token.

2. Injects Antigravity MCP Plugin Configuration:

   • Generates .agents/plugins/agv-codex-bridge/plugin.json (metadata).

   • Generates .agents/plugins/agv-codex-bridge/mcp_config.json registering the local Codex CLI binary as an MCP server.

3. Injects QA Persona Skill, Workflows & Auto-Remediation Rule:

   • Installs .agents/skills/codex-qa/SKILL.md (defines adversarial QA persona, JSON contract, and safety invariants).

   • Installs .agents/workflows/qa-codex.md (enables Antigravity slash command /qa-codex for adversarial audit).

   • Installs .agents/workflows/qa-fix.md (enables Antigravity slash command /qa-fix for zero-prompt auto-remediation).

   • Installs .agents/rules/codex-remediation.md (enables AGV to automatically resolve findings from .agents/qa-inbox.json).

4. Initializes Security Filter & Config:

   • Creates .codexignore (strictly shields .env, secrets, credentials, and massive node_modules folders).

   • Creates agv-codex.config.json (customizable model reasoning, timeout, and dashboard port).

5. Initializes Audit Trail Storage:

   • Creates .agents/qa-logs/ for structured JSON test runs, reproduction steps, and trace logs.

🖥️ CLI Commands

📦 Key Features & Architecture

                               ┌─────────────────────────────┐
                               │     Technical Lead (You)    │
                               │  (Dashboard http://:4567)   │
                               └──────────────┬──────────────┘
                                              │
                    ┌─────────────────────────┴─────────────────────────┐
                    │                                                   │
                    ▼                                                   ▼
       ┌────────────────────────┐                          ┌────────────────────────┐
       │   OpenAI Codex CLI     │ ── (Adversarial QA) ──►  │ Google Antigravity (AGV)│
       │     (Auditor/QA)       │                          │      (Developer)       │
       └────────────┬───────────┘                          └────────────┬───────────┘
                    │                                                   │
                    └───────────────► .agents/qa-logs/ ◄────────────────┘

1. 🎛️ Real-Time Dynamic Dashboard (http://localhost:4567)

• Sticky Left Console Panel: Stays pinned in viewport while scrolling through audit findings on the right.

• Stream Buffer Retention: Retains up to 300 recent stream events — refreshing the browser preserves the console history.

• Intelligent Session Status (✓ RESOLVED / ✓ PASS): Historical audit sessions automatically get marked with green checkmarks once AGV patches the findings.

• Tech Lead Ignore Flags (🚫 Ignore / ↩ Un-ignore): Mark false positives or accepted risks to exclude them from the AGV remediation dispatch payload.

• Interactive Tooltips (?): Clear explanations for default behaviors (defaults to Full Workspace and comprehensive multi-vector QA when left blank).

• Color-Coded Severity: High/Critical in Red, Medium in Amber, Low in Blue.

2. 🚀 Closed-Loop Remediation Workflow

• 1-Click AGV Dispatch: Click "Fix with AGV" -> "🚀 Dispatch to AGV" to queue remediation tasks directly into .agents/qa-inbox.json.

• Instant Clipboard Copy: Provides a ready-to-use prompt for manual execution when preferred.

• Technical Lead Gatekeeper: Verifies that all issues are remediated and safe before release.

3. ⚡ Zero-Dependency, Pure Native Engine

• Built with native Node.js (http, node:events, node:child_process) — fast, lightweight, and framework-agnostic.

• Babel-standalone React dashboard with clean Tailwind CSS developer aesthetics.

🛡️ Antigravity Slash Commands & Skills

Once initialized, you have access to two powerful native workflows inside Antigravity IDE:

• /qa-codex (Auditing): Runs an adversarial QA inspection across your workspace or latest diffs using Codex.

• /qa-fix (Zero-Prompt Remediation): Automatically reads .agents/qa-inbox.json, repairs detected bugs in prioritized order, runs local tests, and updates resolution status.

• Skill: .agents/skills/codex-qa/SKILL.md

• Remediation Rule: .agents/rules/codex-remediation.md

• MCP Plugin: .agents/plugins/agv-codex-bridge/

📄 License

MIT © lil-id