Antigravity Route

A Claude Code and opencode plugin (and CLI) that routes work through the agy CLI (Google Antigravity CLI — Gemini under the hood). Ships two surfaces today:

• agy-web-search — single-shot grounded web search. A PreToolUse hook (Claude Code) or JS plugin (opencode) intercepts the agent's websearch tool calls and reroutes them to agy-route search, which uses agy's search_web with real source citations.
• agy-research — multi-source deep research. Claude plans, fans out sub-questions via agy-route research fetch, verifies each load-bearing claim by URL-quote via agy-route research quote, then synthesizes a cited report. Run with /agy-research <topic>.

Both surfaces use the same agy-route binary (uv tool install), the same search-only tool policy (no file writes, no shell — search_web + read_url only), and the same exit-code conventions. agy-route install is target-aware: it drops skills + hooks + commands into whichever agent you pick (claude or opencode).

This is the first plugin in the agy-route repo. Future plugins (review, code, …) become subcommands of the same agy-route binary.

Install

Quick, target-aware setup. Drops skills, slash commands, and hooks directly into your target agent's configuration directory (~/.claude/ or ~/.config/opencode/).

# 1. Install the agy CLI and authenticate (https://antigravity.google/docs/cli-using):
agy models                       # should list Gemini Flash / Pro entries

# 2. Install `agy-route` as a uv tool:
uv tool install git+https://github.com/hsuanguo/agy-route

# 3. Drop skills and slash commands into target agent:
agy-route install --target claude        # target agent: claude (default) or opencode

# Optional flags:
#   agy-route install --disable-websearch   # hard-deny native WebSearch tool(Claude only)
#   agy-route install --with-hook           # also install PreToolUse hook (Claude) / JS plugin (opencode)
#   agy-route install --only-skill          # install SKILL.md files only
#   agy-route install --only-hook           # install hook / JS plugin only
#   agy-route install --dry-run             # preview changes without writing files

Verification

Verify with:

agy-route types
agy-route search "latest Antigravity CLI release"

The hook is wired automatically if --with-hook is used. You can confirm by asking Claude a question that would normally trigger a web search; the response will cite Gemini-grounded URLs.

Usage

From Claude Code & opencode

Once installed (agy-route install --target <claude|opencode>), web searches are executed in three ways:

1. Automatic Skill Triggering (Default)
   The agent automatically detects search intent and loads Skill(agy-web-search), executing the query through agy-route search via Bash.

2. Explicit Slash Commands
   Force search or deep-research directly from the chat prompt:

   /agy-web-search "Claude API pricing 2026"
   /agy-research "Quantum computing breakthroughs"
   

3. Automatic Tool Interception (When installed with --with-hook)

   • Claude Code: A PreToolUse hook automatically intercepts standard WebSearch tool calls and reroutes them to agy-route search.
   • opencode: A JS plugin (agy-route.js) automatically intercepts opencode's native websearch tool calls and reroutes them to agy-route search.

Tip: If you prefer not to install the hook, pass --disable-websearch during install (agy-route install --disable-websearch) to hard-deny native WebSearch in permissions, forcing the agent to route 100% of web searches through Skill(agy-web-search) and slash commands.

From any shell

# Single-shot search
agy-route search "latest Antigravity CLI release"

# Deep-research primitives
agy-route research fetch "<sub-question>"      # fan-out: 5-8 bullets + URLs + dates
agy-route research quote "<claim>" "<url>"     # URL-quote: verbatim supporting text or NOT SUPPORTED

# Piped prompt (preferred for long queries)
echo "What changed in Python 3.13 between rc1 and final?" | agy-route search

# Programmatic JSON envelope
echo "query" | agy-route search --json
# → {"success":true,"model_used":"...","type":"search","duration_seconds":9,"response":"..."}

Deep research

For multi-source research ("research X", "investigate Y", "find me sources for Z"), use the /agy-research <topic> slash command. It drives the deep-research recipe:

1. Plan (Claude): decompose into 3–6 sub-questions; flag load-bearing claims.
2. Fan-out fetch (parallel agy-route research fetch): 5–8 bullets per sub-question with URLs + dates.
3. URL-quote (parallel agy-route research quote "<claim>" "<url>"): agy opens the URL and quotes the verbatim sentence(s) supporting each claim (or NOT SUPPORTED).
4. Verify (Claude): each load-bearing claim needs ≥2 independent quoted sources → verified or unverified.
5. Synthesize (Claude): write the cited report with verified findings + an explicit unverified section.

Steps 1, 4, 5 are Claude reasoning (no CLI). Steps 2, 3 are agy calls.

Re-install after a git pull

uv tool install --force --from git+https://github.com/hsuanguo/agy-route agy-route

Exit codes

code	meaning	typical action
0	ok
2	failed (args, etc.)	fix the call
3	empty output	inspect stderr; usually quota/auth
10	quota	retry later (or upgrade plan)
11	auth	re-auth agy
12	timeout	pass --timeout 600, simplify the query
13	agy-missing	install agy and ensure it's on $PATH
14	model-unavailable	rm ~/.cache/agy-route-models and retry
15	permission-denied	retry with AGY_SKIP_PERMISSIONS=1

Environment overrides

var	effect
AGY_ROUTE_FORCE_MODEL=1	pass --model to agy (off by default; the resolved model is still reported in JSON)
AGY_SKIP_PERMISSIONS=1	pass --dangerously-skip-permissions to agy (off by default; the policy already gates)

Uninstall

agy-route uninstall                # removes SKILL.md + hook/plugin for every registered target
agy-route uninstall --target claude    # restrict to one target
agy-route uninstall --target opencode  # restrict to one target
uv tool uninstall agy-route

Layout

assets/
  logo.svg                    # horizontal lockup (icon + wordmark)
  icon.svg                    # icon only (favicon / social-card)
skills/
  agy-web-search/SKILL.md     # single-shot web search skill
  agy-research/SKILL.md       # deep-research skill
plugins/
  claude/claude-settings.json # Claude Code settings (permissions & hooks)
  claude/claude-permissions.json # Claude Code auto-approval permissions
  opencode/agy-route.js       # opencode JS plugin
src/agy_route/
  cli.py                      # Typer CLI app entry point
  install.py                  # orchestrator for target installation & uninstallation
  targets/
    base.py                   # Target ABC
    claude.py                 # Claude Code target (~/.claude/ + settings.json)
    opencode.py               # opencode target (~/.config/opencode/{plugins,commands}/)
  hooks/
    pretooluse.py             # the Claude hook binary — `agy-route-hook-pretooluse`
  policies/
    search.md                 # tool policy: search_web + read_url only
pyproject.toml                # PEP 621 metadata + 2 console script entries

Privacy

agy-route sends your prompt to Google's Gemini service. Do not pipe credentials, API keys, or PII.

License

MIT — see LICENSE.