Agy

agy-plugin-cc

A Claude Code plugin that delegates fast, read-only codebase exploration to Google's Antigravity CLI (agy).

Inspired by openai/codex-plugin-cc, but deliberately smaller: agy exposes a real headless mode (agy --print), so this plugin is a thin wrapper — no app-server, no JSON-RPC broker, no background job state. The point is speed: agy's default Gemini Flash tier explores a repo faster than running the exploration inline in Claude or Codex.

What you get

Command	What it does
/agy:explore <question>	Codebase exploration. Returns agy's findings. Runs without write permission (see Read-only note).
/agy:ask <prompt>	One-shot prompt forwarded as written. Runs without write permission unless --write.
/agy:setup	Check the local agy install, version, and model list.

There is also an agy-explorer subagent — a pure forwarder you can delegate to when you want exploration kept out of the main context.

Requirements

• agy on your PATH (the binary is agy, not antigravity). Run agy install and authenticate.
• Node.js (the companion script is Node ESM).
• Override the binary location with the AGY_BIN environment variable if needed.

Verify with /agy:setup.

Install

Add this repo as a plugin marketplace, then install the agy plugin:

/plugin marketplace add sergiogmr/agy-plugin-cc
/plugin install agy@antigravity-agy

(Or point the marketplace at a local clone path.)

Usage

/agy:explore where is auth handled and which files touch the session cookie?
/agy:explore map the data layer --add-dir ./packages/api --timeout 10m
/agy:ask summarize the README of this project

Findings are returned exactly as agy prints them.

Options

Recognized inside the argument string (everything else is the prompt):

• --add-dir <path> — add a directory to agy's workspace (repeatable).
• --timeout <dur> — Go duration for the print timeout (90s, 10m). Default 5m.
• --write — (/agy:ask only) allow writes via --dangerously-skip-permissions. Use deliberately.
• --model "<name>" — experimental. On agy v1.0.6 the display names from agy models were observed to hang in --print mode. Leave it unset to use the fast default.

How it works

Each command shells out to plugins/agy/scripts/agy-companion.mjs, which runs:

agy --print --print-timeout <dur> [--model <name>] [--add-dir <path>]... [--dangerously-skip-permissions]

The prompt is piped to agy over stdin (not as an argument), so a prompt that starts with -- can never be misread by agy as a flag. --print runs a single prompt non-interactively and prints the response — no TUI. agy's own stdout is streamed back unchanged; the only stderr line stripped is agy's PATH warning.

Read-only

/agy:explore prepends a read-only frame and never passes --dangerously-skip-permissions. On agy v1.0.6, print mode without that flag did not write files even when explicitly asked to (verified empirically). This is a soft guarantee — it relies on agy's permission default, not an OS sandbox. For hard isolation, run agy under your own read-only mount or container.

Known limitations

• --model is experimental — display names from agy models hang in print mode on v1.0.6.
• Slash-command argument injection — like openai/codex-plugin-cc, the commands interpolate $ARGUMENTS into a shell command. Shell metacharacters (`, $()) in your own arguments are interpreted by your shell. Input comes from you, not a remote source, but treat the argument string as you would any shell input.
• Exploration-only — /agy:ask --write is the one path that can grant writes; everything else runs read-only.

Layout

.claude-plugin/marketplace.json
plugins/agy/
├── .claude-plugin/plugin.json
├── commands/{explore,ask,setup}.md
├── agents/agy-explorer.md
├── skills/agy-cli-runtime/SKILL.md
└── scripts/agy-companion.mjs

Status

v0.1.0 — exploration-only. Background jobs, review gates, and session hooks (the heavier machinery in codex-plugin-cc) are intentionally out of scope for now.

See CHANGELOG.md for release notes.

License

MIT © sergiogmr