Connecting CodeNavi to Google Antigravity CLI (`agy`)¶

Antigravity CLI (agy, Google's evolution of Gemini CLI) talks to CodeNavi over MCP. The integration ships as a bundle, plugins/antigravity/ (included in every air-gapped package, MIT-licensed). It has two parts:

The MCP server → ~/.gemini/config/mcp_config.json — one file shared by the agy CLI, the Antigravity IDE and the 2.0 desktop app, so wiring it once connects all three. This is what gives Antigravity CodeNavi's tools: an 11-tool search/browse/read core by default, with the rest (relations, crawler, notes, backup) loaded on demand via reveal_tools().
The using-codenavi skill → ~/.gemini/skills/using-codenavi/SKILL.md, auto-discovered by agy so it prefers semantic search over grep.

Antigravity ≠ Claude Code ≠ Codex. All three agents read different files, use different field names, and treat the bearer token differently. A config copied from one will silently fail in the others. Wire each one explicitly.

Cloud agent — data leaves your machine. agy runs the model in Google's cloud, so anything CodeNavi returns to it gets sent to Google. Scope to codebases you're comfortable sharing; see docs/connecting-antigravity-windows.md for a full privacy/scoping walkthrough that applies on Linux/Mac too.

Fast path¶

cd plugins/antigravity
./connect-codenavi.sh --env-file ../../.env

Antigravity on a different machine than the server? The server hands the bundle out itself — no token needed for /plugins/*:

git clone http://<server-ip>:8765/plugins/antigravity.git && cd antigravity
export CODENAVI_AUTH_TOKEN=<token>
./connect-codenavi.sh --host <server-ip> --port 8765

No git on the client? curl -O http://<server-ip>:8765/plugins/antigravity.zip unpacks to codenavi-plugin-antigravity/.

connect-codenavi.sh is idempotent: it backs up mcp_config.json, merges the [mcpServers.codenavi] block while preserving any other servers, installs the skill into ~/.gemini/skills/using-codenavi/, installs the statusline (see Statusline below), and verifies an authenticated tools/list against the exact URL before declaring success. Then restart agy:

# Restart agy, then in the TUI run /mcp — 'codenavi' should be listed.
# Headless check:  agy -p "list codebases with the codenavi list_codebases tool"

Manual mcp_config.json¶

If you'd rather not run the script, paste the snippet from plugins/antigravity/mcp/mcp_config.json.snippet into ~/.gemini/config/mcp_config.json. The minimal block:

{
  "mcpServers": {
    "codenavi": {
      "serverUrl": "http://localhost:8765/mcp",
      "headers": {
        "Authorization": "Bearer <PASTE_TOKEN_HERE>"
      }
    }
  }
}

The three things that bite people¶

Antigravity uses serverUrl — NOT Claude Code's {"type":"http","url":...} and NOT Codex's bearer_token_env_var. A config copied from another agent silently won't connect — the field name is wrong, codenavi gets dropped, and agy falls back to curling the endpoint with no schemas (which masks the failure since the data still comes back).
The token must be the LITERAL value. Antigravity CLI 1.0.8 does not expand ${VAR} in MCP headers — with the env-var form, codenavi silently 401s and is dropped. connect-codenavi.sh bakes the real token from your .env into a 0600 file by default. --env-token opts into the unsupported ${VAR} form for a future Antigravity that adds expansion. This is the opposite of Codex, which needs the env-var NAME and rejects a literal.
Use the unscoped /mcp path unless you know the codebase name. /mcp/<name> returns Unknown codebase '<name>' (404) unless <name> is configured — a single-codebase install is usually named default. Check with list_codebases. Connecting a cloud agent to a multi-codebase server? Then scope it on purpose (--codebase NAME) — see Privacy first. For scoped wiring, pass --codebase NAME to connect-codenavi.sh.

Headless `agy --print` and the workspace-CLAUDE.md derail¶

agy --print "<prompt>" is the headless mode (good for scripts, CI, demos). Two caveats from real runs:

agy --print reads any CLAUDE.md / GEMINI.md / AGENTS.md in the workspace before doing anything. If that file defines a custom CLI or PreToolUse hook (e.g. the cpx CLI in some shops), agy goes shell-first and may never reach the codenavi MCP tools — even when the prompt explicitly says "use the codenavi MCP tools only" and the using-codenavi skill is loaded. For headless structural demos, run from a directory without a workspace CLAUDE.md, or remove the shell-tool guidance from it.
Flag echoes leak into the prompt. Long flags like --print-timeout=9m can bleed into the model's context and turn into a search target. Keep flags strictly before the prompt string and avoid mentioning flag names in the prompt itself.

The TUI doesn't have either failure mode — the workspace file is loaded as documentation rather than tool-policy, and there are no --print flags to echo.

Verifying connection¶

agy inspect / agy mcp are TUI-only (they need a real TTY, so they fail over SSH without a PTY). To verify headlessly:

agy -p "list codebases with the codenavi list_codebases tool"
# If 'codenavi' is wired, agy reads the tool schema and calls it directly.
# If not, it usually falls back to `curl http://localhost:8765/mcp` — that response
# looks similar but means the integration is broken (no tool schemas, no other tools).

You can also check the cli log at ~/.gemini/antigravity-cli/log/cli-*.log for mcp__codenavi__* entries.

Statusline¶

connect-codenavi.sh also installs a statusline into the agy CLI — a prompt badge showing the current repo's index coverage (✦) and whether CodeNavi was used on the last turn (🟢), rebuilt from the Claude Code plugin's statusline so the two can't drift.

It lands in agy's app-data dir ($GEMINI_HOME/antigravity-cli) and is wired into that settings.json — a different file from the ~/.gemini/config/mcp_config.json that holds the MCP block. Pass --settings PATH if your agy build reads it from elsewhere.
Skip it with --no-statusline. Revert with python3 statusline/install.py disable — the previous statusLine, if any, is saved and restored exactly.
agy has no plugin cache, so the statusline is a frozen copy: re-run the script after a plugin update to refresh it.

Windows / WSL2¶

If you're running CodeNavi inside WSL2 and want to use Antigravity on the Windows host (or its IDE), the networking + scoping story is different — see connecting-antigravity-windows.md.

Other MCP clients¶

Cursor, Windsurf, VS Code, and other MCP-capable clients connect to the same http://localhost:8765/mcp endpoint, but the config shape differs per client (Windsurf uses serverUrl, Cursor needs no type, VS Code uses servers). See connecting-vscode.md for the exact per-client config.

Connecting CodeNavi to Google Antigravity CLI (agy)¶