agy-staff

Hire Google's Antigravity CLI (agy) as a staffer for Claude Code, OpenAI Codex, and Pi.

Install · Examples · Core design · Upgrade

What & Why

agy-staff lets your senior agents delegate to agy, which ships fast Gemini 3.8 Flash. Five personas: staffer (general-purpose), researcher, reviewer (code and plans/decisions), implementer, and ask — plus a model-facing jobs skill. Claude Code uses /agy:<persona> and Codex uses $agy:<persona>.

If you use Codex you know the feeling: GPT-5.6-Sol is slow even with fast mode on. Claude Code is quicker but still not fast, and Fable quota is scarce enough that you want it orchestrating subagents, not grinding through every survey and review itself. An agy worker gives you a fast lane — second opinions in seconds, research and reviews at Flash speed, scoped implementation handled off to the side while you keep moving. And where speed isn't the point, a second model family looking at the same code buys coverage and robustness your main agent can't give itself.

How

Invoke a persona

Type /agy: in Claude Code and the five personas are right there:

Same plugin in Codex, invoked with $agy:

Install

For humans

Step 1 — install the Antigravity CLI (official docs), then verify with agy --version. Node.js is also required:

curl -fsSL https://antigravity.google/cli/install.sh | bash

Step 2 — install the plugin into your harness:

claude plugin marketplace add keli-wen/agy-staff
claude plugin install agy@agy-staff

codex plugin marketplace add https://github.com/keli-wen/agy-staff
codex plugin add agy@agy-staff

Install: pi install git:github.com/keli-wen/agy-staff. Skills are prefixed as /skill:agy-<persona> (e.g. /skill:agy-ask reply with OK), with /skill:agy-jobs for job management. Update with pi update --extension git:github.com/keli-wen/agy-staff, then run /reload.

Restart Claude Code or Codex afterwards. First run: /agy:ask reply with OK (Claude Code) or $agy:ask reply with OK (Codex). Ask is tool-free and needs no setup.

[!IMPORTANT] There is no mandatory setup step. staffer, researcher, reviewer and implementer run unrestricted by default: agy can inspect the repo, run commands, and edit files. agy-staff keeps that practical with prompts that adapt to the current repo state. For example, when implementer starts in a dirty workspace, the companion tells agy which files already had changes and reminds it not to overwrite or deliver unrelated user work. If the task asks for a commit, push, or PR, agy can do that delivery; otherwise it leaves a working-tree diff for review. These prompt instructions do not provide permission isolation. setup + --restricted is optional hardening for untrusted input — per run (--restricted) or as a per-repo default (setup --restrict review,research). setup dry-runs and asks before writing anything ("set up agy" triggers it); read the permission notes first — the allowlist is prefix-matched, applies machine-wide, and a restricted run can return less than an unrestricted one.

For agents

Paste this into any coding agent:

Read the raw text of https://raw.githubusercontent.com/keli-wen/agy-staff/master/docs/INSTALL_FOR_AGENTS.md (curl it — do not
work from a summary) and follow it to install and verify the agy-staff plugin for the harness you are running in.
Respond in the user's language.

Upgrade

Claude Code and Codex install a copy, so a new version only reaches you when you pull it in yourself:

claude plugin marketplace update agy-staff && claude plugin update agy@agy-staff

codex plugin marketplace upgrade && codex plugin add agy@agy-staff  # then restart Codex

Claude Code and Codex cache per version directory, so an upgrade lands only if the plugin version changed; restart the harness afterwards. If a fix does not show up, see upgrading — it has the force-refresh command.

CUJs

Examples below use Claude Code's /agy:…; in Codex use $agy:….

reviewer is fully prompt-based: you describe the subject and agy gathers the evidence itself (gh pr view, git diff, reading the file) — there is no flag for handing it a diff. It has two flavors, routed by subject: code review (severity-ranked findings) and general review (a multi-angle challenge of a plan, design, or decision).

staffer also covers agy's native tools without a dedicated specialist persona, including image generation (generate_image). A trial on agy v1.1.15 produced a 1024×1024 PNG in about 30 seconds; actual time depends on the task and environment.

Core design

lead adds task orchestration guidance for your current agent. Within lead, delegate substantive work to staffer by default, use specialists when their guidance helps, and reserve ask for testing. The host owns decisions, review, and delivery, using the existing jobs workflow. Invoke /agy:lead in Claude Code, $agy:lead in Codex, or /skill:agy-lead in Pi.

ask answers in the same call. The other personas return a job id and a collection command, such as wait <id> --timeout 10m. Your agent waits using the host's available capabilities, with one independent background wait per job where supported.

The main agent waits for the final result by default. If you explicitly ask about progress, it can use observe to read a snapshot of recent tool activity and response text; it does not query progress for routine updates. Once the task finishes, wait or result delivers the full report. Expiring a wait leaves the worker running.

The timeline below follows a background task from delegation to completion. The host agent can continue other work, check progress when needed, and collect the final report.

Jobs have a separate execution deadline: default 60 minutes, configurable at launch with --timeout up to 120 minutes. Use cancel to stop execution, or explicitly request continue or restart after inspecting the existing work. The host harness controls when your agent receives a background result.

Full reference → docs/REFERENCE.md (flags, permission model, jobs/state, troubleshooting, upgrading). Release notes → docs/releases/.

Community

• LINUX DO — A next-generation Linux community.

Contributing

Contributions are welcome — issues, bug reports and pull requests all help.

A few things worth knowing before you open a PR:

• Run the tests: npm test. The standard suite uses temporary repos and HOME directories with fake agy, plus focused module tests. Keep regression tests offline and independent of personal settings. Real AGY validation is a separate opt-in suite described in tests/README.md.
• Docs come in pairs: README.md / README.zh-CN.md and docs/REFERENCE.md / docs/REFERENCE.zh-CN.md are kept in sync. Change one, change its counterpart.
• Runtime code lives in companion/: the entrypoint handles modes and job commands; separate modules handle streaming execution, observations and state locking. Skills call the companion, and templates/ holds the shared prompts.
• Canonical skills are the source of truth: edit personas in skills/, never in pi-skills/. Run npm run generate:pi to generate Pi entrypoints, and npm run check:pi to verify consistency.

Adding a mode or a flag changes the public surface, so please open an issue first and we can agree on the shape.

License