x-gemini — Direct Gemini CLI Bridge

Bootstrap (MANDATORY first step)

0. Pin capabilities for the session per ../x-shared/capability-loading.md. The agy_cli flag gates this skill.
1. If agy-agent or agy is not on PATH, instruct the user: run /x-skills:setup inside Claude Code. Do not tell them to run bin/setup directly — the slash command is the canonical entry point.

Wraps the official agy (Antigravity) CLI for headless invocation from Claude Code skills. Bypasses OpenCode entirely — no oh-my-openagent.json, no plugin compat bugs, no API key. Uses your Google Ultra subscription and prompt-driven Google Search grounding.

Quick Dispatch

If {{ARGUMENTS}} is non-empty, invoke immediately via Bash:

/x-gemini "prompt"                              → agy-agent "prompt"
/x-gemini --model pro "prompt"                  → agy-agent --model pro "prompt"
/x-gemini --resume "follow-up"                  → agy-agent --resume "follow-up"
/x-gemini --add-dir /abs/dir "explain this"     → agy-agent --add-dir /abs/dir "explain this"
/x-gemini --grounded "latest version of X?"     → agy-agent --grounded "latest version of X?"

The wrapper lives at bin/agy-agent (symlinked to ~/.local/bin/agy-agent by bin/setup).

When to Use

When NOT to Use

Models

Note: agy is plain-text only (no JSON surface). The wrapper synthesizes a real exit code (agy exits 0 even on failure). Pass --grounded — it is required for "what's current / latest version" questions; without it agy trusts the repo over live docs and returns stale identifiers.

Invocation

# Basic
agy-agent "Research topic X"

# Specific model
agy-agent --model pro "Complex reasoning task"

# Custom system prompt (prepended to the prompt to constrain behavior)
agy-agent --system /path/to/system.md "Analyze this"

# Mount a scoped workspace dir (replaces the old per-file attach)
agy-agent --add-dir ./src/feature "Summarize this module"

# Grounded lookup — REQUIRED for "what's current / latest version" questions
agy-agent --grounded "Latest stable version of X? cite URLs"

# Resume last conversation (multi-turn research)
agy-agent --resume "Follow-up: how does it differ from approach Y?"

# Resume a specific conversation by id
agy-agent --conversation <id> "Continue from there"

# Autonomous tool execution (yolo mode — no approvals required)
# DANGER: agy gets unrestricted shell access. Only use when caller
# explicitly approves.
agy-agent --yolo "Set up the project and run tests"

# Raw passthrough (skip the optional Work Summary chrome strip)
agy-agent --raw "Plain text response"

Env Vars

Timeout: Set Bash timeout to 600000 (10 min). A single scoped grounded call returns in ~80s; bulk/pro work runs longer. agy buffers output to the end — never set a short timeout, it truncates to 0 bytes.

Output format: agy is plain text only — there is no JSON/structured-output surface. The wrapper emits the text directly to stdout; stats (model, duration, status) go to stderr.

Output

stdout:

<agy's response, plain text / markdown>

stderr (last line):

[agy-agent] pro | duration=79s | status=success | log=~/.cache/x-skills/agy/agy-agent-...log

Use --resume (latest conversation) or --conversation <id> for multi-turn. The persisted run log is at the log= path.

Error Handling

agy itself exits 0 even on failure. The wrapper re-derives a real exit code from empty stdout + the noise-stripped --log-file tail — trust the wrapper's code, not agy's.

The log always contains not logged into Antigravity / failed to set auth token (auxiliary caches) even on success — that is noise, not an auth failure. The wrapper's status= is the signal.

Dependencies

• agy CLI (required) — install: https://antigravity.google/cli; auth via agy interactive (Google account login)
• timeout (required) — brew install coreutils on macOS, or use gtimeout
• jq (recommended) — brew install jq (used by the trustedWorkspaces preflight)
• Google Ultra subscription (recommended) — quota-friendly access

bin/setup detects all of these and writes capability flags to ~/.config/x-skills/capabilities.json.

Gotchas

See gotchas.md for known failure patterns — update it when you encounter new ones.

Task: {{ARGUMENTS}}