Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
bump: minor
---

### Added

- Google Antigravity (`agy`) support: a provider record, the `antigravity` keys in `<home>/external-agents.yaml`, bundled defaults (every use read-only, council member on), and the agy prerequisite with its daily latest-release check. The `/external-agents:antigravity` skill drives the `external-agents` command for agy the way `/external-agents:codex` does for Codex. Read-only runs use agy's default approval mode through a per-run settings file, so writes and commands are refused and reported as blocked. Writes are opt-in through `antigravity.uses.task.mode: write`, because agy's auto mode, whose limit is agy's sandbox plus agy's own review, has no network isolation. With no `antigravity.model` set, agy's own default model runs. Every agy run passes `--disable-slash-commands`, so a prompt starting with `/` reaches the model as text, and a review warns when the branch changes agy's `.agents/` workspace configuration.
5 changes: 4 additions & 1 deletion plugins/external-agents/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ none of its text or code is copied).
## Status

In progress: `run`, `review`, `status`, `result`, `cancel` and `update` work, and
`/external-agents:codex` drives them.
`/external-agents:codex` and `/external-agents:antigravity` drive them.

## Surface

Expand All @@ -20,6 +20,9 @@ In progress: `run`, `review`, `status`, `result`, `cancel` and `update` work, an
outside this plugin reads its install path or its scripts.
- **`/external-agents:codex`**: hands a task, an investigation or a review to Codex, in the
foreground or background, and reads back, resumes or cancels its jobs.
- **`/external-agents:antigravity`**: the same for Google's Antigravity CLI (`agy`). agy runs
read-only unless you opt in to writes with `antigravity.uses.task.mode: write`, because agy's
write mode has no network isolation.
- No hooks, no agents and no `commands/` folder: nothing runs until you or a council run asks.

claude.ai organization plugin sync skips this plugin, because it ships a top-level `bin/`
Expand Down
9 changes: 9 additions & 0 deletions plugins/external-agents/defaults.json
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,15 @@
},
"council": { "enabled": true }
},
"antigravity": {
"timeout_seconds": 1800,
"uses": {
"task": { "mode": "read-only" },
"investigate": { "mode": "read-only" },
"review": { "mode": "read-only" }
},
"council": { "enabled": true }
},
"breaker": { "cooldown_hours": 24 },
"jobs": { "keep": 50 }
}
25 changes: 25 additions & 0 deletions plugins/external-agents/prerequisites.json
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,31 @@
"install": {
"docs": "https://github.com/openai/codex"
}
},
{
"id": "agy",
"kind": "cli",
"need": "optional",
"for": [
"plugin"
],
"detect": {
"any": [
"agy"
],
"version": {
"args": [
"--version"
],
"pattern": "([0-9]+(?:\\.[0-9]+)+)",
"min": "0",
"latest": "github:google-antigravity/antigravity-cli"
}
},
"degrade": "Without the Antigravity CLI (agy), Antigravity runs are reported unavailable and council's Antigravity member is skipped; other CLIs are unaffected.",
"install": {
"docs": "https://antigravity.google/docs/install"
}
}
]
}
62 changes: 62 additions & 0 deletions plugins/external-agents/providers/antigravity.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
schema: 1
product: antigravity
docs_index: https://antigravity.google/docs/cli
help:
agy: [--help]
models: [models]
binary:
name: agy
candidates:
win32:
- "{LOCALAPPDATA}/agy/bin/agy.exe"
linux:
- "{HOME}/.local/bin/agy"
darwin:
- "{HOME}/.local/bin/agy"
version:
args: [--version]
sources:
standalone: github:google-antigravity/antigravity-cli
unset_model: cli-default
model_flag: --model
effort_flag: --effort
always_args: [--output-format, json, --disable-slash-commands]
prompt:
form: "-p={prompt}"
resume:
args: [--conversation, "{thread}"]
output:
kind: json_envelope
status_field: status
success_value: SUCCESS
message_field: response
thread_field: conversation_id
error_field: error
review:
kind: diff_file
dir_arg: --add-dir
config_paths: [.agents/]
modes:
read-only:
enforcement: approval-denial
settings:
agentMode: ""
allowNonWorkspaceAccess: false
settings_arg: --settings
prompt_preface: "This run is read-only: every shell command, search commands such as grep, find and ls included, and every file write is refused. Read files by path with your file-reading tool."
write:
enforcement: sandbox
args:
run: [--mode, auto]
resume: [--mode, auto]
settings:
allowNonWorkspaceAccess: false
settings_arg: --settings
fallback_warning:
pattern: "--mode auto is not available"
severity: notice
soft_deny:
- kind: json_array_nonempty
field: denied_actions
- kind: stderr_substring
text: "permission that headless mode cannot prompt for"
40 changes: 39 additions & 1 deletion plugins/external-agents/schemas/external-agents.schema.json
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://raw.githubusercontent.com/melodic-software/claude-code-plugins/main/plugins/external-agents/schemas/external-agents.schema.json",
"title": "External-agents team config",
"description": "Schema for a repository's <home>/external-agents.yaml (<home> defaults to docs/conventions): the team layer of the external-agents plugin. A personal <home>/external-agents.local.yaml overrides it per key. Layers: docs/contracts/config-cascade/README.md. Each product is one top-level key holding the same per-product keys; an unset model, effort or profile leaves the CLI's own configuration in charge.",
"description": "Schema for a repository's <home>/external-agents.yaml (<home> defaults to docs/conventions): the team layer of the external-agents plugin. A personal <home>/external-agents.local.yaml overrides it per key. Layers: docs/contracts/config-cascade/README.md. Each product is one top-level key holding its per-product keys; an unset model, effort or profile leaves the CLI's own configuration in charge.",
"type": "object",
"additionalProperties": false,
"required": ["schema"],
Expand Down Expand Up @@ -51,6 +51,44 @@
}
}
},
"antigravity": {
"description": "Settings for the Google Antigravity CLI (agy).",
"type": "object",
"additionalProperties": false,
"properties": {
"model": { "type": "string", "description": "Model slug passed to the CLI, from `agy models`. Unset: no `--model` is passed and agy uses its own default." },
"effort": { "type": "string", "description": "Reasoning effort passed to the CLI. Unset: the CLI's own setting." },
"binary_path": { "type": "string", "description": "Absolute path to the CLI binary, tried before every other location. Read from the personal layer only: a value in the committed team file is ignored, since it picks the executable that runs." },
"timeout_seconds": { "type": "integer", "minimum": 1, "default": 1800, "description": "Seconds before a run is stopped and recorded timed-out." },
"update_hint": { "type": "string", "description": "Text shown beside the daily check's line when the CLI is behind its latest release, such as how your machines update it." },
"uses": {
"type": "object",
"additionalProperties": false,
"properties": {
"task": {
"type": "object",
"additionalProperties": false,
"properties": { "mode": { "type": "string", "enum": ["read-only", "write"], "default": "read-only", "description": "Default and ceiling for task runs. Write is opt-in: agy's write mode has no network isolation (ADR 0119)." } }
},
"investigate": {
"type": "object",
"additionalProperties": false,
"properties": { "mode": { "type": "string", "enum": ["read-only", "write"], "default": "read-only", "description": "Default and ceiling for investigate runs." } }
},
"review": {
"type": "object",
"additionalProperties": false,
"properties": { "mode": { "type": "string", "enum": ["read-only"], "default": "read-only", "description": "Reviews always run read-only." } }
}
}
},
"council": {
"type": "object",
"additionalProperties": false,
"properties": { "enabled": { "type": "boolean", "default": true, "description": "Whether review:council may run this CLI as a member." } }
}
}
},
"breaker": {
"type": "object",
"additionalProperties": false,
Expand Down
110 changes: 110 additions & 0 deletions plugins/external-agents/skills/antigravity/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,110 @@
---
description: "Hands a task, investigation or review to Google's Antigravity CLI (agy, Gemini models) and reads back its jobs. Use when the user asks for Gemini or Antigravity: 'ask Gemini', 'have Gemini do X', 'Gemini second opinion', 'Antigravity review of this branch', 'run this through agy', 'is the Gemini job done', 'cancel the agy run', 'is agy ready', 'update antigravity'. A multi-reviewer panel is /review:council."
argument-hint: "[run <prompt>|review --base <ref>|status [<job>]|result <job>|cancel <job>|update]"
user-invocable: true
disable-model-invocation: false
allowed-tools:
- "Bash(external-agents run antigravity:*)"
- "Bash(external-agents review antigravity:*)"
- "Bash(external-agents status:*)"
- "Bash(external-agents result:*)"
- "Bash(external-agents cancel:*)"
- "Bash(external-agents update antigravity:*)"
shell: bash
metadata:
workflow-stage: implement
summary: Hand tasks, investigations and reviews to the Antigravity CLI and read back its jobs
---

# Antigravity

**Arguments.** `[run <prompt>|review --base <ref>|status [<job>]|result <job>|cancel <job>|update]`.
A bare request that is not one of the other actions is `run`.

This skill drives the plugin's `external-agents` command, which is on the Bash `PATH` while the
plugin is enabled. The command is the only thing that starts agy; never call `agy` yourself, and
never look up the plugin's install path. Delegate only when the user asks for Gemini or
Antigravity.

## Actions

| Action | Command | Read |
|---|---|---|
| `run` (default): a task (may write) or an investigation (read-only) | `external-agents run antigravity --use task\|investigate --prompt-file <file>` | [reference/run.md](reference/run.md) |
| `review`: agy reviews this branch, read-only | `external-agents review antigravity --base <ref> [--brief-file <file>]` | [reference/run.md](reference/run.md#review) |
| `status`, `result`, `cancel` | `external-agents status [<job>]`, `result <job>`, `cancel <job>` | [reference/jobs.md](reference/jobs.md) |
| `update`: readiness, CLI facts, version and routing check | `external-agents update antigravity` | [reference/update.md](reference/update.md) |
| Choosing a model or effort | none: config keys only | [reference/routing.md](reference/routing.md) |

## Reporting a run

- **First reply line:** `Mode: <mode> (<use>)`, taken from the job, never from what was asked: the
`mode:` line of `external-agents status <job>` (the job id is the `job: <id>` line on stderr).
A review is always `Mode: read-only (review)`. When the mode ceiling lowered a write request, say
so and name the config key the notice names.
- Then the command's first stdout line, then agy's final message verbatim. That message is agy's
answer, not yours: relay it, and add your own reading only below it, labeled as yours.
- Exit codes (`scripts/lib/runner.mjs:12`): `0` ok, `1` failed, `2` usage or refused, `3` blocked
by the mode, `4` agy unavailable or skipped. On `1`, `2` or `4`, report the first line and the
CLI's error and stop: never do the task yourself in agy's place. On `4`, point the user to
`external-agents update antigravity`.

## Prompts

Write the prompt with the Write tool to a file in a gitignored scratch folder (this repository's
convention, else the session scratchpad) and pass it with `--prompt-file`; the command keeps its
own copy in the job folder. Name the files and paths agy should read; never paste file contents,
diffs or logs into the prompt. For an investigation, name the paths: a read-only agy run reads
files by path and cannot search or list directories.

## Background runs

Run the same command with the Bash tool's `run_in_background`; you are notified when it exits, so
do not poll. The job id prints only at the end, so while it runs, find it with bare
`external-agents status`. Stop a run with `external-agents cancel <job>`, which stops agy's whole
process tree; stopping the background Bash task alone may leave agy running.

## Next

`/review:council` for a ranked, multi-reviewer review of the same change, with agy as one member.

## Gotchas

- **Write is opt-in.** Every use runs read-only until the user sets
`antigravity.uses.task.mode: write` in `<home>/external-agents.yaml` or `.local.yaml`, because
agy's write mode has no network isolation (next gotchas). A task asked for while the ceiling is
read-only runs read-only; relay the notice naming that key, and never set it yourself.
- **A refused action makes the run `blocked-by-mode`, even with a full answer.** agy keeps going
after a refusal and may still answer well; the command records the run `blocked-by-mode`, exits
`3` and prints the answer. Relay the answer, name the refused actions from the first line, and
never report a task done.
- **A write task's limit is agy's sandbox plus agy's own review.** `--mode auto` keeps commands
in agy's terminal sandbox, but its review lets commands it judges safe and reversible run outside
it ([Terminal sandbox](https://antigravity.google/docs/sandbox/)). Sandboxed commands have no
network by default, but a write task on WSL (agy 1.5.14) reached the internet with and without
`--sandbox`, so treat write mode as having network access. Never ask agy to push, open or
merge pull requests, or run `gh` or `az`; Claude Code stays the only actor for those.
- **Check the work, not the warning.** agy may print `--mode auto is not available ...;
continuing in the default mode` (relayed as a `notice:`) and still run in auto mode, writes
included. Before reporting a task done, check that its files exist; trust neither the notice nor
the exit code alone.
- **On Windows, auto-mode commands cannot write files** (`EPERM`, observed on agy 1.5.14, also
with an added directory), so a build or test that writes output fails there. For those, run
from WSL.
- **Workspace configuration from the branch loads into agy.** agy reads hooks from
`.agents/hooks.json` in the workspace ([Hooks](https://antigravity.google/docs/hooks/)), plus
the user's `~/.gemini/config/hooks.json` and installed agy plugins. The command prints a
`notice:` when a reviewed change touches `.agents/`; relay it before the findings.
- **The breaker refuses runs after an unavailable-class failure** until the time it prints.
`external-agents update antigravity` closes it once agy is ready again; do not retry in a loop.
- **`antigravity.binary_path` is read only from an untracked personal file**
(`<home>/external-agents.local.yaml`, absolute path, file named `agy`, or `agy.exe` on
Windows). Set anywhere else, it is ignored with a `notice: config:` line; relay that notice.
- **Plugin data directory.** Job files, logs, the breaker and the CLI-facts cache live in this
plugin's data directory, which the command works out for itself; never pass or set
`CLAUDE_PLUGIN_DATA`. A `notice:` saying another plugin's `CLAUDE_PLUGIN_DATA` is not used is
expected. A checkout that is not installed refuses to run until `CLAUDE_PLUGIN_DATA` names a
directory starting with `external-agents-` (see the plugin README's Job files section).
- **CLI flags come from the CLI.** When a question turns on what an agy flag or subcommand does,
read the help `update` captured (`agy.txt` in its `cli facts:` folder), not this skill and not
memory.
25 changes: 25 additions & 0 deletions plugins/external-agents/skills/antigravity/reference/jobs.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
# Jobs: status, result, cancel

Every run and review writes one job file when agy starts and updates it when agy ends. Jobs are
grouped per repository (all worktrees of one repository share a group; outside a repository, one
`no-repo` group), and the command lists, reads and cancels only the current directory's group.
The newest `jobs.keep` finished jobs per group are kept. Codex and agy jobs share the group.

```bash
external-agents status # every job in this repository, newest first
external-agents status <job> # one job: status line, then id, use, mode, times, exit code, thread_id, CLI version, paths
external-agents result <job> # status line, then agy's final message
external-agents cancel <job> # stop a running job and its process tree
```

- **`status`** settles stale jobs: a `running` job whose process is gone is rewritten
`failed (process exited)`. Use `status <job>` for the `mode:` the reply's first line needs and
the `thread_id` (agy's conversation id) a resume needs.
- **`result`** exits like the run did (`0`, `1` or `3`), and `1` while the job is still running;
report a running job as running, not as failed.
- **`cancel`** refuses when the job is not running, or when it cannot confirm the recorded pid is
still that job's process; nothing is killed then. A cancelled job is recorded `cancelled`.
- **Paths.** `status <job>` prints `log_path` (agy's JSON result) and `final_message_path`. Read
the final message; open the log only to explain a failure or a refused action, and quote only
the lines that matter. Job files can hold prompts and output: never copy them out of the
plugin's data directory, into a commit, an issue or a pull request.
28 changes: 28 additions & 0 deletions plugins/external-agents/skills/antigravity/reference/routing.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
# Routing: model and effort

This skill holds no model names and no effort defaults. A run passes a model only when the user
names one or `antigravity.model` is set, and an effort only when `antigravity.effort` is set;
otherwise agy's own default model decides, so runs follow whatever agy ships. Which model and effort each agent role in a
multi-agent run uses is `/multi-agent:route`'s config, not this skill's.

agy's model slugs name a thinking level (for example a `-medium` suffix), and agy also takes
`--effort`. Which one wins when both are given is not documented; when the user sets both, say so
and suggest setting only the slug.

When the user asks which Gemini model or effort to use, or `update` prints `routing: due`, read the
sources below and answer from them, citing the section:

- The models this agy version offers: `models.txt` in the `cli facts:` folder from
`external-agents update antigravity`.
- Index of the Antigravity CLI docs, to find a page that moved:
[Get started](https://antigravity.google/docs/cli).
- Which models exist and how to pick one:
[Choose a model § Choose a model](https://antigravity.google/docs/models/#choose-a-model) and
[§ Reasoning model](https://antigravity.google/docs/models/#reasoning-model).
- Thinking levels and effort:
[Choose a model § Select a model](https://antigravity.google/docs/models/#select-a-model) and
[Effort command](https://antigravity.google/docs/cli/commands/effort).

A recommendation goes to the user as a config change for them to make (`antigravity.model`,
`antigravity.effort`), with the section it rests on. On `routing: due`, the check is the one in
[update.md § Routing refresh](update.md#routing-refresh).
Loading
Loading