> ## Documentation Index
> Fetch the complete documentation index at: https://lab.pollack.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Antigravity Reference

> Complete configuration reference for the Google Antigravity agent provider

## Overview

The Antigravity agent wraps the [Google Antigravity CLI](https://antigravity.google) via `AntigravityAgentModel`. The binary is `agy`. Configure it through Spring properties under `agent-client.antigravity.*`.

```yaml theme={null}
agent-client:
  antigravity:
    model: gemini-3.1-pro-high
    timeout: PT15M
```

## Configuration Properties

Prefix: `agent-client.antigravity`

| Property | Type | Default | Description |
| - | - | - | - |
| `mode` | `AgentClientMode` | — | Controls default permissiveness. Inherits from `agent-client.mode` if not set (default: `LOOSE`). |
| `model` | `String` | `gemini-3.1-pro-high` | Model slug (`--model`). List them with `agy models`. |
| `effort` | `String` | — | Reasoning effort (`--effort`): `low`, `medium`, `high`. **Ignored when the model slug already encodes it** — see below. |
| `timeout` | `Duration` | `15m` | Timeout. Also drives `--print-timeout`. |
| `dangerously-skip-permissions` | `Boolean` | — | `--dangerously-skip-permissions`. When not explicitly set, derived from mode. |
| `execution-mode` | `ExecutionMode` | — | `--mode`: `accept-edits` or `plan` |
| `sandbox` | `boolean` | `false` | `--sandbox` — terminal restrictions |
| `executable-path` | `String` | — | Path to `agy` (auto-discovered if not set) |

## Effort is encoded in the model slug

Antigravity names effort twice: in `--effort` and in slugs like `gemini-3.1-pro-high`. Passing both is a **hard error**:

```
invalid model selection (--model "gemini-3.1-pro-high" --effort "low"):
  --model gemini-3.1-pro-high conflicts with --effort=low
```

The run fails immediately with `"status": "ERROR"` and no output. So when the slug ends in `-low`, `-medium` or `-high`, the provider drops the flag and the slug wins. Portable `getEffort()` therefore behaves here exactly as it does for every other provider, and a caller does not need to know that this one CLI names effort twice.

## dangerouslySkipPermissions and Mode Interaction

| `dangerously-skip-permissions` | `mode` | Effective Value |
| - | - | - |
| explicit | any | as set |
| unset | `STRICT` | `false` |
| unset | `LOOSE` | `true` |

<Warning>
  Declining to auto-approve does not do what the flag name suggests. Antigravity's headless default is not to stop on an unapprovable tool call — it is to **refuse that call and carry on**. A `STRICT` unattended run is therefore not safer, it is quietly partial. It remains the default only because a caller that has not thought about permissions should not be handed unrestricted execution, and because the provider reports the refusals rather than swallowing them.
</Warning>

## Detecting a refused run

The provider scans both the envelope's `error` field and stderr for refusal notices, and surfaces the result:

| Field | Notes |
| - | - |
| `softDenied` | `true` when at least one tool call was refused |
| `permissionNotices` | The refusal messages, verbatim |

The documentation says these notices go to stderr. agy 1.1.13 puts some of them in the envelope's `error` field with stderr empty, and others on stderr with `status: CANCELED`. Both channels are read.

## The status field is not the verdict

In agy 1.1.13, `status` behaves like a sticky execution-error indicator, not a verdict on the completed task. A tool call that fails can leave the terminal envelope at `"status":"ERROR"` even after later tool calls complete and the agent produces a valid review. Conversely, a refused tool call has been observed with `"status":"SUCCESS"` and no response. Trusting the field discards good recovered work; ignoring it hides real failures.

`isSuccessful()` therefore requires all of the following:

* the process exited with code 0
* the run produced a non-empty response
* no tool call was refused
* the stream contains no tool error left unrecovered by a later completed tool call

An `ERROR` envelope without stream evidence is treated conservatively as unrecovered. The CLI's own account remains available as `status`, `reportedSuccessful` and `error`; `softDenied` and `unrecoveredError` expose the two independent reasons the derived result can reject it.

## Portable Option Mapping

| Portable option | Antigravity flag |
| - | - |
| `getModel()` | `--model` |
| `getEffort()` | `--effort`, **dropped when the model slug encodes effort** |
| `getJsonSchema()` | `--json-schema` (serialized inline) |
| `isAutoApprove()` | `--dangerously-skip-permissions` |
| `getTimeout()` | process timeout **and** `--print-timeout` |
| `getWorkingDirectory()` | `--add-dir` **and** the process working directory — see below |
| `getSystemInstructions()` | prepended to the goal (no system-prompt flag exists) |
| `getMaxTurns()` | not supported |

<Note>
  `--print-timeout` defaults to five minutes, well short of a real task, so it is always set from the caller's timeout. Left alone, a truncated run would be indistinguishable from the agent finishing early.
</Note>

## The working directory must be declared, not just set

There is no `--cwd`, but setting the process working directory is **not sufficient**. With no
active workspace, `agy` diverts every write to a shared scratch directory under
`~/.gemini/antigravity-cli/` and still reports success. The CLI says so plainly in its own
output — *"I placed it in your scratch directory … since there wasn't an active workspace"* —
and artifacts from earlier runs accumulate there, so work leaks between runs.

Reads resolve against the process working directory, which is why a narrow check looks fine
while writes are going somewhere else entirely.

The provider therefore declares the working directory with `--add-dir` as well as setting the
process cwd. Both are required.

<Warning>
  This was found by running the provider parity TCK, not by reading the CLI's documentation. A
  run that writes to the wrong place and reports success is the failure mode this provider is
  most exposed to — see also soft denial below.
</Warning>

## Result Metadata

`getProviderFields()` carries `inputTokens`, `outputTokens`, `thinkingTokens`, `cacheReadTokens`, `totalTokens`, `numTurns`, `status`, `reportedSuccessful`, `error`, `softDenied`, `unrecoveredError`, `permissionNotices`, `exitCode` and `structured`. `getSessionId()` carries the conversation id, which `AntigravityClient.resume(conversationId, ...)` accepts via `--conversation`.

## Availability

Since **0.28.0**.

## Installation

Install from [antigravity.google](https://antigravity.google) — the npm distribution is discontinued — and authenticate once interactively. Discovery checks `ANTIGRAVITY_CLI_PATH`, then `which agy`, then `~/.local/bin/agy`.

Support files live under `~/.gemini/antigravity-cli`, shared with the Gemini CLI, so that directory existing proves nothing about `agy` being installed.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.