Agy

Agy plugin for Claude Code

Use Agy from inside Claude Code for code reviews or to delegate tasks to Agy.

This plugin is for Claude Code users who want an easy way to call Agy (the Anthropic agent CLI running Claude and Gemini family models) from the workflow they already have. It follows the structure of OpenAI's codex-plugin-cc, adapted to Agy's print-mode CLI.

What You Get

• /agy:review for a normal read-only Agy review
• /agy:adversarial-review for a steerable challenge review
• /agy:rescue, /agy:status, /agy:result, and /agy:cancel to delegate work and manage background jobs

Requirements

• The agy CLI installed and on your PATH. This plugin does not install Agy for you.
• An authenticated Agy session. Sign-in is interactive: run agy in a terminal once and complete the login flow.
• Node.js 18.18 or later

Install

Add the marketplace in Claude Code:

From GitHub (the repository is private — your gh/git credentials must have access):

/plugin marketplace add nguyenhieuec/agy-plugin-cc

Or from a local clone:

/plugin marketplace add /path/to/agy-plugin-cc

Install the plugin:

/plugin install agy@agy-cc

Reload plugins:

/reload-plugins

Then run:

/agy:setup

/agy:setup tells you whether Agy is ready. If agy is missing from your PATH, install it first and re-run setup. If Agy is installed but not signed in, run agy interactively in a terminal to complete the login flow — there is no non-interactive login.

After install, you should see:

• the slash commands listed below
• the agy:agy-rescue subagent in /agents

One simple first run is:

/agy:review --background
/agy:status
/agy:result

Models

Agy bundles effort into the model label — there is no separate --effort flag. The plugin accepts either the full label or a short alias anywhere --model is supported:

Alias	Model label
flash	Gemini 3.5 Flash (High)
flash-low	Gemini 3.5 Flash (Low)
flash-medium	Gemini 3.5 Flash (Medium)
flash-high	Gemini 3.5 Flash (High)
pro	Gemini 3.1 Pro (High)
pro-low	Gemini 3.1 Pro (Low)
pro-high	Gemini 3.1 Pro (High)
sonnet	Claude Sonnet 4.6 (Thinking)
opus	Claude Opus 4.6 (Thinking)
gpt-oss	GPT-OSS 120B (Medium)

Defaults:

• Every command defaults to flash (Gemini 3.5 Flash (High)) unless you pass --model. The plugin pins this explicitly rather than relying on Agy's built-in default, so behavior stays stable even if a future Agy release changes its default model.
• Resumed rescue conversations (--resume) keep the model they were started with; pass --model to switch.

Usage

/agy:review

Runs a normal Agy review on your current work.

[!NOTE] Code review especially for multi-file changes might take a while. It's generally recommended to run it in the background.

Use it when you want:

• a review of your current uncommitted changes
• a review of your branch compared to a base branch like main

Use --base <ref> for branch review. It also supports --wait, --background, and --model <model|alias>. It is not steerable and does not take custom focus text. Use /agy:adversarial-review when you want to challenge a specific decision or risk area.

Examples:

/agy:review
/agy:review --base main
/agy:review --background
/agy:review --model pro

This command is read-only and will not perform any changes. When run in the background you can use /agy:status to check on the progress and /agy:cancel to cancel the ongoing task.

/agy:adversarial-review

Runs a steerable review that questions the chosen implementation and design.

It can be used to pressure-test assumptions, tradeoffs, failure modes, and whether a different approach would have been safer or simpler.

It uses the same review target selection as /agy:review, including --base <ref> for branch review. It also supports --wait, --background, and --model. Unlike /agy:review, it can take extra focus text after the flags. Like every command it defaults to flash (Gemini 3.5 Flash (High)); pass --model sonnet or --model opus when you want a stronger reasoning tier for the challenge pass.

Use it when you want:

• a review before shipping that challenges the direction, not just the code details
• review focused on design choices, tradeoffs, hidden assumptions, and alternative approaches
• pressure-testing around specific risk areas like auth, data loss, rollback, race conditions, or reliability

Examples:

/agy:adversarial-review
/agy:adversarial-review --base main challenge whether this was the right caching and retry design
/agy:adversarial-review --background look for race conditions and question the chosen approach
/agy:adversarial-review --model opus question the concurrency design

This command is read-only. It does not fix code.

/agy:rescue

Hands a task to Agy through the agy:agy-rescue subagent.

Use it when you want Agy to:

• investigate a bug
• try a fix
• continue a previous Agy conversation
• take a pass with a different model family (Gemini for long context, Claude for hard reasoning)

[!NOTE] Depending on the task and the model you choose these tasks might take a long time and it's generally recommended to force the task to be in the background or move the agent to the background.

It supports --background, --wait, --resume, --fresh, and --model <model|alias>. If you omit --resume and --fresh, the plugin can offer to continue the latest rescue conversation for this repo.

Examples:

/agy:rescue investigate why the tests started failing
/agy:rescue fix the failing test with the smallest safe patch
/agy:rescue --resume apply the top fix from the last run
/agy:rescue --model pro investigate the flaky integration test across the whole repo
/agy:rescue --model gpt-oss fix the typo quickly
/agy:rescue --background investigate the regression

You can also just ask for a task to be delegated to Agy:

Ask Agy to redesign the database connection to be more resilient.

Notes:

• if you do not pass --model, fresh tasks run on flash (Gemini 3.5 Flash (High)); resumed conversations keep their original model.
• effort tiers ride on the alias: flash-low / flash-medium / flash-high, pro-low / pro-high.
• follow-up rescue requests can continue the latest Agy conversation in the repo.
• rescue tasks run in write mode by default. --write is prompt framing, not a sandbox — Agy is spawned with permissions skipped, so read-only behavior is a contract in the prompt, not an OS-level guarantee.

/agy:status

Shows running and recent Agy jobs for the current repository.

Examples:

/agy:status
/agy:status task-abc123

Use it to:

• check progress on background work
• see the latest completed job
• confirm whether a task is still running

/agy:result

Shows the final stored Agy output for a finished job. When available, it also includes the Agy conversation ID so you can reopen that run directly in a terminal with agy --conversation <id>.

Examples:

/agy:result
/agy:result task-abc123

/agy:cancel

Cancels an active background Agy job.

Examples:

/agy:cancel
/agy:cancel task-abc123

/agy:setup

Checks whether Agy is installed and authenticated.

You can also use /agy:setup to manage the optional review gate.

Enabling review gate

/agy:setup --enable-review-gate
/agy:setup --disable-review-gate

When the review gate is enabled, the plugin uses a Stop hook to run a targeted Agy review based on Claude's response. If that review finds issues, the stop is blocked so Claude can address them first.

[!WARNING] The review gate can create a long-running Claude/Agy loop and may drain usage limits quickly. Only enable it when you plan to actively monitor the session.

Typical Flows

Review Before Shipping

/agy:review

Hand A Problem To Agy

/agy:rescue investigate why the build is failing in CI

Start Something Long-Running

/agy:adversarial-review --background
/agy:rescue --background investigate the flaky test

Then check in with:

/agy:status
/agy:result

Agy Integration

Unlike the Codex plugin (which talks to a persistent app server), this plugin spawns the agy binary directly in print mode for every run:

• each run is one agy -p <prompt> --add-dir <cwd> --dangerously-skip-permissions --log-file <per-run-log> --print-timeout 60m invocation
• there is no app server, no JSON-RPC connection, and no config.toml — model selection happens per run via --model
• the conversation ID is parsed from the per-run log file, so follow-ups can resume with agy --conversation <id>
• review prompts embed the expected JSON schema directly, and the plugin parses the JSON verdict out of Agy's final message (raw, fenced, or embedded)
• structured review output is best-effort: if Agy's reply does not parse as JSON, the raw message is preserved and shown instead
• spawned runs set AGY_CLI_DISABLE_AUTO_UPDATE=true (unless you already set it yourself) so agy's background self-updater cannot swap the binary or stall on network mid-job
• Agy parses GEMINI.md / AGENTS.md rule files at the workspace root on startup, so any rule file in your repository also steers delegated plugin runs

Moving The Work Over To Agy

Delegated tasks and any stop-gate run can be resumed directly in a terminal with agy --conversation <id>, using the conversation ID shown by /agy:result or /agy:status.

This way you can review the Agy work or continue the work there.

FAQ

Do I need a separate Agy account for this plugin?

If you are already signed into Agy on this machine, that account works immediately here too. This plugin uses your local Agy CLI authentication.

If you have not signed in yet, run agy in a terminal and complete the interactive login. Run /agy:setup afterwards to confirm Agy is ready.

Does the plugin use a separate Agy runtime?

No. This plugin delegates through your local agy binary on the same machine.

That means:

• it uses the same Agy install you would use directly
• it uses the same local authentication state
• it uses the same repository checkout and machine-local environment

Is --write / read-only mode enforced?

No. Agy is always spawned with permissions skipped so it can work non-interactively — --dangerously-skip-permissions overrides the fine-grained allow/ask/deny lists in ~/.gemini/antigravity-cli/settings.json for that run. Read-only review commands prepend a strict do-not-modify contract to the prompt, which Agy follows, but it is an instruction rather than a sandbox. If you want OS-level containment for the commands Agy executes, enable "enableTerminalSandbox": true in Agy's settings — the plugin does not override the sandbox setting. Do not point review commands at a checkout you cannot restore.

Why do background jobs fail with an auth error over SSH?

Agy stores credentials in the OS keyring (Apple Keychain on macOS). In headless or SSH sessions the keychain may be locked, so spawned agy processes cannot read credentials. Unlock it first (security unlock-keychain on macOS) or run the job from a local session.

Where do logs go?

Every run writes a dedicated Agy log file under the plugin's data directory. /agy:status and /agy:result surface the log path for the corresponding job so you can inspect the full run.

License

Apache-2.0. This project is a derivative of OpenAI's codex-plugin-cc; see NOTICE.