agy-delegate

A Claude Code plugin that routes tasks to agy (Google Antigravity CLI), giving your Claude sessions access to Gemini and grounded web search with source citations. For general web search prefer your WebSearch tool; reach for agy when you need cited sources or a second model.

Why

Independent review. A model reviewing its own output anchors on the reasoning it used to produce it. Gemini — a different company, different training — catches different things. Not because Claude can't review code, but because it tends to miss what it already decided was right.

Current information with sources. Claude's training has a cutoff. When you need today's release notes, a pricing page, or a changelog with actual URLs, you need live web search — not a model's best guess.

A migration path off the Gemini CLI. On June 18, 2026, Google stops serving Gemini CLI requests for consumer tiers (AI Pro, Ultra, free Code Assist) and names the Antigravity CLI as the replacement. Frameworks like Claude Octopus and Metaswarm that shell out to a gemini binary break on that date. The included shim answers to the gemini name and routes the call through agy, so those tools keep working with no config changes.

How it works

The plugin has two parts.

agy-bridge is a shell script that wraps agy with type routing, per-type tool restrictions, prompt sanitization, and consistent exit codes. Each --type gets its own GEMINI.md written to a temporary working directory; agy reads it via --add-dir; the GEMINI.md tool restrictions are prompt-advisory, while --sandbox is the API-level filesystem floor that confines agy to the granted directories. A search call can only use web tools. A review call can only read files. An implement call can read and write files but can't run shell commands. The prompt itself is embedded in the per-run 0600 GEMINI.md (the same file that carries the tool restrictions, auto-loaded via --add-dir); only a short static pointer is passed as the --print value, so the prompt still doesn't appear in ps or /proc/cmdline.

agy-delegate is a Claude Code skill that tells Claude when to reach for the bridge. It triggers on phrases like "search for", "latest", "ask Gemini", "second opinion". Claude picks the right --type, constructs the prompt, and pipes it through.

A SubagentStart delegation hook (opt-in, default off) injects a one-line advisory into allowlisted Task subagents so they know they can hand bulk, fan-out, or web-search work to agy-bridge. It is advisory-only and never changes routing; see Configuration for the toggle, allowlist, and preconditions.

# How Claude calls it internally (you can run these directly too)
echo "dplyr 1.1.0 release notes" | agy-bridge --type search
echo "Review /path/to/api.py for correctness" | agy-bridge --type review

Type routing

--type	Model	What it can do
search	gemini-*-flash-high (latest)	Web search only; prepends search_web instruction automatically
code	gemini-*-pro-high (latest)	Read files; returns generated code as text, no writes
analysis	gemini-*-pro-high (latest)	Read files; handles large codebases
review	gemini-*-pro-high (latest)	Read files; adversarial framing
implement	gemini-*-pro-high (latest)	Read and write files; no shell execution

The Model column is a rule, not a pin: the bridge resolves each --type to the latest matching Gemini id from your live agy models list at runtime, so it tracks agy version bumps with no plugin update. Omit --type to default to code. Override the model with --model MODEL_ID — verified against agy 1.1.13 (captured 2026-08-20): --model accepts both a bare id (e.g. gemini-3.1-pro-high) and a display name (e.g. Gemini 3.7 Flash (High)); run agy models for the current list of both forms.

Requirements

• agy installed and authenticated via OAuth
• python3 3.6 or later (standard on all modern systems)

Recommended, not required: timeout or gtimeout (coreutils). Every agy call is bounded with or without one — see Bounding without timeout/gtimeout. What coreutils buys is the kind of kill: timeout isolates its child in its own process group and signals the group, so it reaps whatever agy forked, while the built-in bash watchdog does the same through job control and degrades to killing the direct process only where job control cannot isolate the child. Linux ships timeout; on macOS brew install coreutils provides gtimeout.

Installation

1. Install and authenticate agy.

Follow the agy project's installation instructions. After installing, run agy once interactively to complete the OAuth flow. Credentials land in ~/.gemini/antigravity-cli/.

2. Install dependencies.

# macOS — python3 ships with macOS; coreutils is recommended, not required
brew install coreutils

# Debian/Ubuntu — timeout is in coreutils, already present on most systems
# python3 is standard; install if missing:
sudo apt install python3

3. Install this plugin.

From GitHub:

claude plugin marketplace add https://github.com/davdittrich/delegate-agy
claude plugin install agy-delegate

Or from a local clone:

git clone https://github.com/davdittrich/delegate-agy
claude plugin install ./delegate-agy

4. Run the installer.

Run /agy-setup inside Claude Code. It does NOT install anything for you — it prints the shadow notice plus two commands to copy-paste: a grep command that reads the plugin's install path straight from ~/.claude/plugins/installed_plugins.json (so you read the path yourself before anything runs), and the scripts/install.sh command to run against it. If that registry file is missing, it falls back to a command that resolves the path from claude plugin list --json instead and validates the result before running it, since that path comes from command output rather than your own eyes.

/agy-setup

scripts/install.sh writes two hardened launcher wrappers to ~/.local/bin:

• agy-bridge → execs scripts/agy_bridge.sh
• gemini → execs scripts/gemini_shim.sh (drop-in shim)

Each wrapper execs a pinned absolute path recorded at install time — the exec target is never a plugin-cache glob and never comes from claude plugin list (both are attack/latency surfaces); it is only ever that install-time literal. If the plugin is later moved, the pinned path disappears and the wrapper fails loud with a "re-run the install" message and a non-zero exit. If instead the plugin is updated and Claude Code's cache leaves the old version directory in place alongside the new one (observed behavior — the stale copy is not deleted), the pinned path still resolves, so the wrapper compares its pinned version against the version Claude Code reports as installed and refuses to run: it exits 127 naming both versions and — when the active version is numeric and the constructed installer path exists on disk — the exact command to repin (otherwise a generic pointer to /agy-setup), rather than silently executing the stale copy. Re-run /agy-setup's install command after any plugin update to repin the wrappers either way.

Shadow blast radius. ~/.local/bin/gemini shadows the real gemini command for every caller whose PATH has ~/.local/bin first — your shell, Claude Octopus, Metaswarm. The installer prints this notice, backs up any pre-existing non-agy gemini/agy-bridge (to <name>.bak-agy-<timestamp>), and scans the full $PATH to warn which real gemini it shadows. Reverse everything with scripts/uninstall.sh (see below).

Opt-in flag (default off): AGY_SETUP_PATCH_ALIASES=1 applies the recursive-gemini shell-rc alias patch (otherwise a dry-run advisory). /agy-setup prints the exact variant commands.

5. Verify.

agy-bridge --types

Expected output:

type         model                          timeout
search       gemini-*-flash-high (latest)   300s
code         gemini-*-pro-high (latest)     600s
analysis     gemini-*-pro-high (latest)     600s
review       gemini-*-pro-high (latest)     600s
implement    gemini-*-pro-high (latest)     600s

6. Uninstall.

scripts/uninstall.sh removes the two wrappers only if they carry our signature marker (restoring any shadowed original from its backup), and removes the availability hint. It is idempotent and refuses to run as root. /agy-setup prints the exact command.

Usage

The skill triggers automatically inside Claude sessions. For direct use:

--add-dir exposes everything under the granted directory to agy, not just the file(s) you care about — pass the narrowest sufficient path (a staging directory holding only the needed files keeps the grant auditable). / and $HOME (exact match) are refused with exit 2 unless AGY_ALLOW_BROAD_GRANT=1 is set; subdirectories such as $HOME/sub are unaffected.

# Web search with citations
echo "Claude API pricing June 2026" | agy-bridge --type search

# Code review — grant read access to the directory holding the file
echo "Review scripts/deploy.sh for correctness" | agy-bridge --type review --add-dir scripts

# Inline prompt without stdin
agy-bridge --type search -- "latest numpy release"

# JSON output envelope
echo "query" | agy-bridge --type search --json

# Digest-only reply — biggest cost lever for bulk work: agy returns a compressed
# digest (findings + file:line) instead of a raw dump, keeping your context lean.
# Warns on stderr if the reply comes back dump-sized (tune with --digest-warn-chars).
echo "Map the auth flow end to end" | agy-bridge --type analysis --digest

JSON output:

{
  "success": true,
  "model_used": "gemini-3.6-flash-high",
  "type": "search",
  "duration_seconds": 9,
  "response": "..."
}

Configuration

SubagentStart advisory hook

The plugin installs a SubagentStart hook (hooks/agy-subagent-policy.sh, wired via hooks/hooks.json) that can inject a one-line advisory into a matched subagent's context, pointing it at agy-bridge for bulk/fan-out/web-search work. It is OFF by default. With no environment variables set, the hook exits 0 and produces no output — a default install is completely inert.

Variable	Purpose	Default
AGY_HOOKS_ENABLED	Master toggle. Must be 1, true, on, or yes (case-insensitive) to enable. Anything else, including unset, is disabled.	unset (disabled)
AGY_HOOKS_AGENT_TYPES	CSV allowlist of agent_type values that receive the advisory.	general-purpose,Explore,metaswarm:researcher-agent,metaswarm:coder-agent,metaswarm:code-review-agent
AGY_HOOKS_DEBUG	Set to 1 to log one line per skip/fire decision.	unset (off)
AGY_HOOKS_DEBUG_FILE	Path to append debug lines to. If unset while AGY_HOOKS_DEBUG=1, lines go to stderr.	unset (stderr)

Allowlist entry forms. Each AGY_HOOKS_AGENT_TYPES entry is one of:

• Namespaced (plugin:name, e.g. metaswarm:coder-agent) — matches only that exact agent type string.
• Bare (name, e.g. general-purpose) — matches that exact agent type, AND wildcards the suffix after the last : of any namespaced type. A bare coder-agent entry would match metaswarm:coder-agent, other:coder-agent, and any other *:coder-agent.