cluesmith · waleedkadous · Jun 6, 2026 · Jun 2, 2026 · Jun 2, 2026 · Jun 2, 2026
diff --git a/.claude/skills/consult/SKILL.md b/.claude/skills/consult/SKILL.md
@@ -20,7 +20,7 @@ The `-m` / `--model` flag is **always required** except for `consult stats`.
 
 | Flag value | Alias | Notes |
 |------------|-------|-------|
-| `gemini` | `pro` | Fast (~120-150s), file access via --yolo |
+| `gemini` | `pro` | Antigravity CLI (`agy`); agentic file access (`--sandbox`), OAuth login; skips non-blockingly if unavailable |
 | `codex` | `gpt` | Thorough (~200-250s), shell exploration |
 | `claude` | `opus` | Agent SDK with tool use (~60-120s) |
 
@@ -30,7 +30,7 @@ The `-m` / `--model` flag is **always required** except for `consult stats`.
 -m, --model <model>         Model to use (required except stats)
 --prompt <text>              Inline prompt (general mode)
 --prompt-file <path>         Prompt file path (general mode)
---protocol <name>            Protocol: spir, aspir, air, bugfix, tick, maintain
+--protocol <name>            Protocol: spir, aspir, air, bugfix, maintain
 -t, --type <type>            Review type (see below)
 --issue <number>             Issue number (required in architect context)
 --output <path>              Save result to file

diff --git a/AGENTS.md b/AGENTS.md
@@ -310,14 +310,16 @@ Use sequential numbering with descriptive names (no leading zeros):
 ## Multi-Agent Consultation
 
 **DEFAULT BEHAVIOR**: Consultation is ENABLED by default with:
-- **Gemini 3.1 Pro** (gemini-3.1-pro-preview) for deep analysis
+- **Gemini** via the **Antigravity CLI (`agy`)** for deep analysis (the retired Gemini CLI's
+  replacement; OAuth/subscription, agy's default model — no pinned model id). Skips non-blockingly
+  if `agy` is missing/unauthenticated.
 - **GPT-5.4 Codex** (gpt-5.4-codex) for coding and architecture perspective
 
 To disable: User must explicitly say "without multi-agent consultation"
 
 **CRITICAL CONSULTATION CHECKPOINTS (DO NOT SKIP):**
-- After writing implementation code → STOP → Consult GPT-5 and Gemini Pro
-- After writing tests → STOP → Consult GPT-5 and Gemini Pro
+- After writing implementation code → STOP → Consult GPT-5 and Gemini (via agy)
+- After writing tests → STOP → Consult GPT-5 and Gemini (via agy)
 - ONLY THEN present results to user for evaluation
 
 ### cmap (Consult Multiple Agents in Parallel)

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -310,14 +310,16 @@ Use sequential numbering with descriptive names (no leading zeros):
 ## Multi-Agent Consultation
 
 **DEFAULT BEHAVIOR**: Consultation is ENABLED by default with:
-- **Gemini 3.1 Pro** (gemini-3.1-pro-preview) for deep analysis
+- **Gemini** via the **Antigravity CLI (`agy`)** for deep analysis (the retired Gemini CLI's
+  replacement; OAuth/subscription, agy's default model — no pinned model id). Skips non-blockingly
+  if `agy` is missing/unauthenticated.
 - **GPT-5.4 Codex** (gpt-5.4-codex) for coding and architecture perspective
 
 To disable: User must explicitly say "without multi-agent consultation"
 
 **CRITICAL CONSULTATION CHECKPOINTS (DO NOT SKIP):**
-- After writing implementation code → STOP → Consult GPT-5 and Gemini Pro
-- After writing tests → STOP → Consult GPT-5 and Gemini Pro
+- After writing implementation code → STOP → Consult GPT-5 and Gemini (via agy)
+- After writing tests → STOP → Consult GPT-5 and Gemini (via agy)
 - ONLY THEN present results to user for evaluation
 
 ### cmap (Consult Multiple Agents in Parallel)

diff --git a/README.md b/README.md
@@ -82,7 +82,7 @@ See [CLI Reference](codev/resources/commands/overview.md) for details.
 
 **AI CLIs** (install all three for multi-model consultation):
 - Claude Code: `npm install -g @anthropic-ai/claude-code`
-- Gemini CLI: [github.com/google-gemini/gemini-cli](https://github.com/google-gemini/gemini-cli)
+- Antigravity CLI (`agy`, the `gemini` consult lane): `curl -fsSL https://antigravity.google/cli/install.sh | bash`, then run `agy` once to sign in (OAuth — replaces the retired Gemini CLI)
 - Codex CLI: `npm install -g @openai/codex`
 
 **Agent Farm (optional):**
@@ -139,7 +139,7 @@ This tour demonstrates:
 - How to write specifications that capture all requirements
 - How the planning phase breaks work into manageable chunks
 - The implementation phase in action
-- Multi-agent consultation with GPT-5 and Gemini Pro
+- Multi-agent consultation with GPT-5 and Gemini (via agy)
 - How lessons learned improve future development
 
 ## What is Codev?
@@ -206,7 +206,7 @@ In much the same way an operating system has a memory hierarchy, Codev repos hav
 
 ### 🤖 AI-Native Workflow
 - Structured formats that AI agents understand
-- Multi-agent consultation support (GPT-5, Gemini Pro, etc.)
+- Multi-agent consultation support (GPT-5, Gemini via agy, etc.)
 - Reduces back-and-forth from dozens of messages to 3-4 document reviews
 - Supports both AGENTS.md standard (Cursor, Copilot, etc.) and CLAUDE.md (Claude Code)
 
@@ -445,7 +445,11 @@ Configure in `.codev/config.json` (created by `codev init` or `codev adopt`):
 }
 ```
 
-Or for Gemini:
+Or for Gemini (the standalone **Gemini CLI** as a *builder/architect* coding agent — a separate
+concern from the `gemini` **consult lane**, which now uses the Antigravity CLI `agy`). Note: Google
+retired the Gemini CLI for Pro/Ultra/free tiers on 2026-06-18, so this builder harness will stop
+working for those tiers — prefer a Claude or Codex builder, or an enterprise Gemini CLI. (Tracked as
+a follow-up; out of scope for the consult-lane migration.)
 ```json
 {
   "shell": {

diff --git a/codev-skeleton/.claude/skills/consult/SKILL.md b/codev-skeleton/.claude/skills/consult/SKILL.md
@@ -20,7 +20,7 @@ The `-m` / `--model` flag is **always required** except for `consult stats`.
 
 | Flag value | Alias | Notes |
 |------------|-------|-------|
-| `gemini` | `pro` | Fast (~120-150s), file access via --yolo |
+| `gemini` | `pro` | Antigravity CLI (`agy`); agentic file access (`--sandbox`), OAuth login; skips non-blockingly if unavailable |
 | `codex` | `gpt` | Thorough (~200-250s), shell exploration |
 | `claude` | `opus` | Agent SDK with tool use (~60-120s) |
 

diff --git a/codev-skeleton/DEPENDENCIES.md b/codev-skeleton/DEPENDENCIES.md
@@ -110,22 +110,33 @@ npm install -g @anthropic-ai/claude-code
 claude --version
 ```
 
-### Gemini CLI
+### Antigravity CLI (`agy`) — the `gemini` consult lane
+
+Replaces the retired Gemini CLI (Google stopped serving Gemini CLI for Pro/Ultra/free tiers on
+2026-06-18). The `gemini` consult lane now dispatches to the Antigravity CLI (`agy`).
 
 | Requirement | Value |
 |-------------|-------|
-| Purpose | Multi-agent consultation, alternative perspectives |
-| Documentation | [github.com/google-gemini/gemini-cli](https://github.com/google-gemini/gemini-cli) |
+| Purpose | Multi-agent consultation (the `gemini` lane), alternative perspectives |
+| Documentation | [antigravity.google/docs/cli-using](https://antigravity.google/docs/cli-using) |
+| Auth | OAuth / Google subscription (no API key) — run `agy` once and sign in |
 
 **Installation:**
 
 ```bash
-npm install -g @google/gemini-cli
+curl -fsSL https://antigravity.google/cli/install.sh | bash   # installs to ~/.local/bin/agy
+
+# Sign in (one-time, interactive)
+agy            # complete the OAuth flow
 
 # Verify
-gemini --version
+agy --version
 ```
 
+> Note: the `agy` on the IDE's PATH (`~/.antigravity/.../bin/agy`) is a symlink to the Antigravity
+> IDE, not the headless CLI — Codev resolves the real CLI itself. If `agy` is missing or
+> unauthenticated, the `gemini` consult lane skips non-blockingly (the run proceeds without it).
+
 ### Codex CLI
 
 | Requirement | Value |
@@ -152,7 +163,7 @@ codex --version
 | git | 2.5.0 | Yes |
 | gh | latest | Yes |
 | Claude Code | latest | At least one AI CLI |
-| Gemini CLI | latest | At least one AI CLI |
+| Antigravity CLI (`agy`) | latest | At least one AI CLI |
 | Codex CLI | latest | At least one AI CLI |
 
 ---

diff --git a/codev-skeleton/resources/commands/codev.md b/codev-skeleton/resources/commands/codev.md
@@ -99,7 +99,7 @@ Verifies that all required dependencies are installed and properly configured:
 
 **AI CLI Dependencies (at least one required):**
 - Claude (`@anthropic-ai/claude-code`)
-- Gemini (`gemini-cli`)
+- Gemini (Antigravity CLI, `agy`)
 - Codex (`@openai/codex`)
 
 **Exit Codes:**

diff --git a/codev-skeleton/resources/commands/consult.md b/codev-skeleton/resources/commands/consult.md
@@ -19,7 +19,7 @@ consult stats [options]
 
 | Model | Alias | Backend | Notes |
 |-------|-------|---------|-------|
-| `gemini` | `pro` | gemini-cli | File access via --yolo, fast |
+| `gemini` | `pro` | Antigravity CLI (`agy`) | Agentic file access (`--sandbox --add-dir`), OAuth/subscription login. Skips non-blockingly if `agy` is missing/unauthed. |
 | `codex` | `gpt` | @openai/codex | Read-only sandbox, thorough |
 | `claude` | `opus` | Claude Agent SDK | Balanced analysis with tool use |
 | `hermes` | - | hermes CLI (`hermes chat -q`) | Uses Hermes agent as consult backend |
@@ -130,7 +130,7 @@ consult -m hermes --protocol spir --type spec
 
 | Model | Typical Time | Approach |
 |-------|--------------|----------|
-| Gemini | ~120-150s | File access via --yolo, pure text output |
+| Gemini | ~120-180s | Antigravity CLI (`agy`); agentic file access via `--sandbox`, plain text output |
 | Codex | ~200-250s | Shell command exploration, read-only sandbox |
 | Claude | ~60-120s | Agent SDK with Read/Glob/Grep tools |
 
@@ -145,14 +145,29 @@ npm install -g @anthropic-ai/claude-code
 # Codex
 npm install -g @openai/codex
 
-# Gemini
-# See: https://github.com/google-gemini/gemini-cli
+# Gemini lane → Antigravity CLI (`agy`), replacing the retired Gemini CLI
+curl -fsSL https://antigravity.google/cli/install.sh | bash
+agy   # run once and sign in (OAuth / Google subscription)
 ```
 
-Configure API keys:
+Configure auth:
 - Claude: `ANTHROPIC_API_KEY`
 - Codex: `OPENAI_API_KEY`
-- Gemini: `GOOGLE_API_KEY` or `GEMINI_API_KEY`
+- Gemini (`agy`): **OAuth / subscription** — run `agy` once and sign in (no API key). If `agy`
+  is missing or unauthenticated, the gemini lane skips non-blockingly (the run proceeds without it).
+
+### Claude auth: subscription vs. metered API
+
+`consult -m claude` runs on the Claude Agent SDK. When `CLAUDE_CODE_OAUTH_TOKEN`
+(a Claude subscription/OAuth token) is present, consult strips `ANTHROPIC_API_KEY`
+and `ANTHROPIC_AUTH_TOKEN` from the SDK subprocess env so the consultation
+authenticates against the **subscription** rather than the **metered Opus API**.
+The Agent SDK otherwise prioritizes `ANTHROPIC_API_KEY`, which silently routes
+CMAP/review traffic to the metered API (issue #985). When no OAuth token is set,
+the API key is used as before so CI / key-only environments keep working.
+
+> **Caveat:** dedicated Agent-SDK subscription credit starts **2026-06-15**.
+> Before that date, subscription auth draws from the interactive Max quota.
 
 ## The Consultant Role
 

diff --git a/codev/DEPENDENCIES.md b/codev/DEPENDENCIES.md
@@ -110,22 +110,33 @@ npm install -g @anthropic-ai/claude-code
 claude --version
 ```
 
-### Gemini CLI
+### Antigravity CLI (`agy`) — the `gemini` consult lane
+
+Replaces the retired Gemini CLI (Google stopped serving Gemini CLI for Pro/Ultra/free tiers on
+2026-06-18). The `gemini` consult lane now dispatches to the Antigravity CLI (`agy`).
 
 | Requirement | Value |
 |-------------|-------|
-| Purpose | Multi-agent consultation, alternative perspectives |
-| Documentation | [github.com/google-gemini/gemini-cli](https://github.com/google-gemini/gemini-cli) |
+| Purpose | Multi-agent consultation (the `gemini` lane), alternative perspectives |
+| Documentation | [antigravity.google/docs/cli-using](https://antigravity.google/docs/cli-using) |
+| Auth | OAuth / Google subscription (no API key) — run `agy` once and sign in |
 
 **Installation:**
 
 ```bash
-npm install -g @anthropic-ai/gemini-cli
+curl -fsSL https://antigravity.google/cli/install.sh | bash   # installs to ~/.local/bin/agy
+
+# Sign in (one-time, interactive)
+agy            # complete the OAuth flow
 
 # Verify
-gemini --version
+agy --version
 ```
 
+> Note: the `agy` on the IDE's PATH (`~/.antigravity/.../bin/agy`) is a symlink to the Antigravity
+> IDE, not the headless CLI — Codev resolves the real CLI itself. If `agy` is missing or
+> unauthenticated, the `gemini` consult lane skips non-blockingly (the run proceeds without it).
+
 ### Codex CLI
 
 | Requirement | Value |
@@ -152,7 +163,7 @@ codex --version
 | git | 2.5.0 | Yes |
 | gh | latest | Yes |
 | Claude Code | latest | At least one AI CLI |
-| Gemini CLI | latest | At least one AI CLI |
+| Antigravity CLI (`agy`) | latest | At least one AI CLI |
 | Codex CLI | latest | At least one AI CLI |
 
 ---
@@ -209,6 +220,18 @@ echo $PATH
 export PATH="$PATH:$(npm config get prefix)/bin"
 ```
 
+### Terminal connection issues
+
+Ensure no firewall is blocking the ports (default: 4200-4299):
+
+```bash
+# Check if port is in use
+lsof -i :4200
+
+# Clean up stale port allocations
+afx ports cleanup
+```
+
 ### gh authentication issues
 
 ```bash