# ⚡ AGV-Codex Bridge

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

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Node Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)
[![MCP Standard](https://img.shields.io/badge/MCP-2024--11--05-orange.svg)](https://modelcontextprotocol.io/)

---

## 🌟 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**.

---

## 🚀 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`:

```bash
# 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:

```bash
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`:

```bash
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:

```bash
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:

```bash
# 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

| Command | Description |
|---|---|
| `agv-codex init` | Setup wizard: detects Codex CLI binary, installs `.agents/` MCP plugin, rules, and `.codexignore`. |
| `agv-codex init --global` | Global setup: registers Codex MCP Server & skills globally into `~/.gemini/config/` for all Antigravity projects. |
| `agv-codex models` | Lists supported Codex reasoning models (`gpt-6-astra`, `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna`, `gpt-5.5`). |
| `agv-codex doctor` | Verifies MCP configuration, Node runtime, Codex authentication, and active model. |
| `agv-codex dashboard [--port=4567]` | Starts the native HTTP & Server-Sent Events (SSE) QA Inspector dashboard with Auth Health Banner. |
| `agv-codex run qa [target] [--model=<id>]` | Runs an on-demand audit with live append-only terminal streaming and thought chains. |

---

## 📦 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