Google Antigravity Integration Guide

Technology: antigravity · Category: tooling · Last reviewed: 2026-08-23

Source: https://tech-stack.codeamanilabs.org/guide/antigravity

Insight:

Antigravity is an agent-first development platform, not an editor with AI bolted on: the unit of work is an agent you dispatch, watch, and verify through Artifacts (task lists, plans, screenshots, browser recordings) rather than a file you type into. The 2.0 pivot (I/O 2026) made the standalone desktop app the command center and shipped a Go-based agy CLI that drives the same agent harness from a terminal — a natural fit for a Linux/WSL dev box. It is model-agnostic (Gemini 3.x, Claude Sonnet/Opus 4.6, GPT-OSS), so codeAmani can route reasoning agents to Claude per the AI policy while keeping Gemini's generous free quota for the rest. Still public preview and free for individuals, so treat surfaces and quotas as moving targets.

 █████╗ ███╗   ██╗████████╗██╗ ██████╗ ██████╗  █████╗ ██╗   ██╗██╗████████╗██╗   ██╗
██╔══██╗████╗  ██║╚══██╔══╝██║██╔════╝ ██╔══██╗██╔══██╗██║   ██║██║╚══██╔══╝╚██╗ ██╔╝
███████║██╔██╗ ██║   ██║   ██║██║  ███╗██████╔╝███████║██║   ██║██║   ██║    ╚████╔╝
██╔══██║██║╚██╗██║   ██║   ██║██║   ██║██╔══██╗██╔══██║╚██╗ ██╔╝██║   ██║     ╚██╔╝
██║  ██║██║ ╚████║   ██║   ██║╚██████╔╝██║  ██║██║  ██║ ╚████╔╝ ██║   ██║      ██║
╚═╝  ╚═╝╚═╝  ╚═══╝   ╚═╝   ╚═╝ ╚═════╝ ╚═╝  ╚═╝╚═╝  ╚═╝  ╚═══╝  ╚═╝   ╚═╝      ╚═╝

Google Antigravity Integration Guide

Focus: running Antigravity on a Linux / WSL Ubuntu dev box — the standalone desktop app (Antigravity 2.0) as the agent command center, and the agy CLI for driving agents from a terminal. Install, launching and orchestrating agents, the Agent Manager panel, Artifacts, parallel subagents, scheduled tasks (Sidecars), model selection, and headless/CI use. The IDE and Python SDK are covered as secondary pointers. Grounded in antigravity.google/docs; reviewed 2026-08-23.

Overview

Google Antigravity is Google's agentic development platform — "build in the agent-first era." Instead of an editor where you type and an AI suggests, the primitive is an agent you give a goal to; it autonomously plans and executes across the editor, terminal, and browser, and reports back through Artifacts — task lists, implementation plans, screenshots, and browser recordings you review instead of scrolling raw logs. It launched in public preview (Nov 2025) and pivoted at I/O 2026 (2026-05-19) to put multi-agent orchestration front and centre, with a standalone desktop app, a Go-based CLI, and a Python SDK.

The platform is one agent harness exposed through four surfaces. Pick the surface, not a different tool:

It is model-agnostic. The reasoning-model selector currently offers Gemini 3.7 / 3.6 / 3.5 Flash, Gemini 3.1 Pro, Claude Sonnet 4.6 (thinking), Claude Opus 4.6 (thinking), and GPT-OSS-120b, gated by plan (Gemini on every tier; Claude and GPT-OSS excluded on Enterprise). Gemini and Claude/GPT-OSS draw from separate weekly + five-hour quota pools.

flowchart TB
  G["Your goal / prompt"] --> H["Antigravity agent harness"]
  subgraph SURF["Surfaces (same harness)"]
    D["Antigravity 2.0<br/>desktop command center"]
    C["agy CLI<br/>terminal · headless"]
    I["IDE + extensions<br/>editor view"]
    S["SDK<br/>google-antigravity (py)"]
  end
  H --> D
  H --> C
  H --> I
  H --> S
  H --> M["Model selector<br/>Gemini 3.x · Claude 4.6 · GPT-OSS"]
  D --> SUB["Subagents<br/>parallel background tasks"]
  C --> SUB
  SUB --> ART["Artifacts<br/>plans · screenshots<br/>browser recordings"]
  D --> SC["Sidecars<br/>scheduled / recurring tasks"]
  H --> ENV["Editor · Terminal · Chrome"]

See also: cursor/ and vscode/ for the other editor options this repo documents, and google-ai-studio/ / google-cloud/ for the Gemini API and Vertex side that the SDK's vertex=True mode talks to.

Official Documentation

Install — Linux / WSL

Two independent installs: the desktop app (a GUI, so on WSL you need WSLg or run it natively on Linux) and the agy CLI (headless, the right fit for a WSL Ubuntu shell). Most codeAmani work on a Windows-hosted WSL box leans on the CLI; install the desktop app on native Linux or via WSLg.

The agy CLI (primary for a terminal / WSL box)

The install script downloads the agy binary to ~/.local/bin/agy:

# Inside your WSL Ubuntu (or any Linux) shell
curl -fsSL https://antigravity.google/cli/install.sh | bash

# Make sure ~/.local/bin is on PATH (add to ~/.bashrc if missing)
export PATH="$HOME/.local/bin:$PATH"

agy --version          # verify the binary is on PATH
agy                    # first launch runs the one-time setup + sign-in

On Windows PowerShell (only if you also want it outside WSL):

irm https://antigravity.google/cli/install.ps1 | iex

Auth is stored in the OS's native secure keyring — Linux Secret Service / dbus, Apple Keychain, or Windows Credential Manager — so the token never lands in a dotfile. On a headless Linux box with no keyring daemon, expect to complete auth interactively once before headless runs work.

The desktop app (Antigravity 2.0)

Download from https://antigravity.google/download — macOS (Apple Silicon / Intel), Windows 10 64-bit (x64 / ARM64), Linux x64. On Debian / Ubuntu, add Google's signed apt repo and install the antigravity package:

# 1. Add the repo signing key
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://us-central1-apt.pkg.dev/doc/repo-signing-key.gpg \
  | sudo gpg --dearmor --yes -o /etc/apt/keyrings/antigravity-repo-key.gpg

# 2. Register the repository
echo "deb [signed-by=/etc/apt/keyrings/antigravity-repo-key.gpg] https://us-central1-apt.pkg.dev/projects/antigravity-auto-updater-dev/ antigravity-debian main" \
  | sudo tee /etc/apt/sources.list.d/antigravity.list > /dev/null

# 3. Install (rpm-based distros and a source tarball are also offered)
sudo apt update
sudo apt install antigravity

Two very different antigravity names — do not confuse them. sudo apt install antigravity (from Google's apt repo above) installs the desktop app. pip install antigravity is the XKCD joke package that opens a comic in your browser — it is not Google's SDK. The real Python SDK is google-antigravity (see the SDK section). Getting these crossed is the single most common Antigravity footgun.

The desktop app — Antigravity 2.0

Antigravity 2.0 is "your AI agents' central command center." Unlike its predecessor (the in-IDE Agent Manager surface), 2.0 is a standalone application: a unified place to launch, monitor, and orchestrate agents both synchronously and asynchronously. Within it, agents can execute system commands, read/write files, call Skills and MCP servers, manage subagents, drive Chrome, and produce Artifacts / implementation plans.

The core loop

1. Create a Project. Each Project keeps its own isolated context and settings — point it at a repo directory. (Analogous to a workspace; keep the checkout on the Linux filesystem, not /mnt/c, on WSL.)
2. Start an Agent. Type your goal and dispatch. The agent plans, then executes across editor/terminal/browser.
3. Navigate. The Conversation Picker is Ctrl+K (⌘K on macOS). Slash commands drive turns — e.g. /goal runs until the specified task is complete.
4. Review Artifacts, not logs. The agent emits task lists, plan walkthroughs, screenshots, and browser recordings; you verify the deliverable rather than reading raw tool output. Agents can also save useful context and snippets to a knowledge base.

Parallel agents & subagents

The whole point of 2.0 is orchestration: run multiple agents at once, and let a primary agent delegate to parallel subagents for slow builds, multi-file generation, or research sweeps while you keep working. Subagents show up with specialized roles (e.g. "Codebase Researcher", "Database Debugger") and a live checklist of active / completed / killed / failed threads.

Scheduled & recurring tasks — Sidecars

Sidecars are background processes Antigravity manages (auto-launch, auto-restart on crash), used for persistent scripts, scheduled recurring tasks, and reacting to events. They are discovered from sidecar.json files:

// ~/.gemini/config/sidecars/nightly-audit/sidecar.json
{
  "display_name": "Nightly dependency audit",
  "description": "Runs npm audit + gitleaks and files an artifact",
  "command": "python3",
  "args": ["audit.py"],
  "restart_policy": "on-failure"
}

• Global sidecars live under ~/.gemini/config/sidecars/; plugin-scoped ones under ~/.gemini/config/plugins/<pluginName>/sidecars/ (ID becomes <pluginName>/<sidecarName>).
• The sidecar's directory is its working directory and can hold helper scripts.
• Instead of command, a sidecar may use a builtin (currently schedule and agentapi); builtin and command are mutually exclusive.

Model selection

Pick the reasoning model from the dropdown under the prompt box. The choice is sticky per turn — changing it mid-run doesn't take effect until the current turn finishes. Track your remaining weekly / five-hour quota there too (Gemini models and Claude/GPT-OSS models have separate pools).

The agy CLI — driving agents from a terminal

Same harness, keyboard-first, in the terminal — which on a Windows box means inside WSL, so it inherits the Linux toolchain automatically. This is the surface for SSH, tmux, and CI.

Interactive

agy                      # start an interactive session in the current project

Inside a session, subagents and background work are managed with slash commands:

/agents      open the interactive Agent Manager Panel (live checklist of background agents)
/tasks       monitor running background tasks
/usage       show model quotas remaining
/diff        review pending modifications
/permissions manage tool-approval gates
/resume      resume a previous conversation

Navigation ergonomics include "Teleport" jump-to-agent (Alt+J) and "Fast-Path" confirmations. A Vim editor mode is available in settings.

Execution modes

The agent runs in one of a few modes, cycled during a session or pinned via agentMode in settings.json (or a command-line flag):

Headless / CI

Headless (a.k.a. print) mode sends a single prompt and exits — the building block for scripts and pipelines:

# One-shot; answer goes to stdout, everything else (auth/progress/permissions) to stderr
agy -p "In one sentence, what is a git rebase?"

# Capture cleanly — the stdout/stderr split makes this safe
answer=$(agy -p "List three popular version control systems, comma-separated.")

# Machine-readable output for pipelines
agy -p "summarize the diff" --output-format json      # text | json | streaming-json
agy -p "review these changes" --output-format streaming-json | jq .

• -p aliases: --print, --prompt.
• --output-format shapes stdout: text, json, or streaming-json (parse with jq).
• Continue a conversation across invocations, stream prompts from stdin, and check exit codes for error handling — the CLI documents a "run the agent in CI" example end to end.
• Run auth once interactively first. Headless mode reuses the credentials from a prior interactive agy session; a fresh CI box with no keyring will fail until seeded.

MCP, subagents, sandbox

The CLI supports MCP servers, plugins & skills, a sandbox for command execution, and granular permission gates — the same building blocks as the desktop app. The /agents panel delegates slow work to parallel background subagents so the main flow stays responsive.

Deeper subagent semantics — lifecycle state diagrams, inter-agent messaging, and nesting-depth limits — live in the Antigravity 2.0 subagents docs; the CLI page is the terminal-facing subset.

Secondary surfaces (pointers)

Python SDK — google-antigravity

For building custom agents in code. This is the real SDK (not the antigravity XKCD package):

pip install google-antigravity          # requires Python 3.10+

import asyncio
from google.antigravity import Agent, LocalAgentConfig

async def main():
    async with Agent(LocalAgentConfig()) as agent:
        response = await agent.chat("Hello!")
        print(await response.text())

asyncio.run(main())

Agent is an async context manager that handles binary discovery, tool execution, and session lifecycle. It runs against the local harness by default, or Vertex AI with LocalAgentConfig(vertex=True, project="...", location="us-central1") (or the GOOGLE_GENAI_USE_VERTEXAI / GOOGLE_CLOUD_PROJECT / GOOGLE_CLOUD_LOCATION env vars + gcloud auth application-default login). It exposes Personas, Tools & skills, MCP, subagents, structured output, and lifecycle hooks. Runnable examples: github.com/google-antigravity/antigravity-sdk-python under examples/getting_started/. See docs/sdk/overview.

IDE & extensions

The Antigravity IDE (editor view) offers Tab completions, inline commands, a side panel, change review, and Chrome control (with allowlist/denylist and a separate Chrome profile). Extensions bring the harness into VS Code, Visual Studio, JetBrains, and Zed. If your day-to-day editor is already Cursor or VS Code, that route may fit better than switching editors — see cursor/ and vscode/.

codeAmani notes

• Route reasoning agents to Claude; keep Gemini for volume. Antigravity's model optionality maps cleanly onto the house AI policy (CLAUDE.md): put complex reasoning / code-gen agents on Claude Sonnet 4.6 (thinking) (or Opus 4.6 for the hardest turns), and lean on Gemini 3.x Flash — which has the generous free-tier quota — for mechanical or high-throughput work. The model selector is sticky per turn, so choose before you dispatch. Note Claude and GPT-OSS are not available on the Enterprise tier; if you standardize on an Enterprise plan, a Claude-first routing policy won't be selectable there.
• Secrets stay server-side and out of the agent's reach. Antigravity agents run terminal commands, read/write files, and drive Chrome — they can read anything the shell can. Keep live credentials in Hazina and .env.local, never pasted into a prompt or committed. The CLI storing auth in the OS keyring (Secret Service/dbus, Keychain, Credential Manager) is the right pattern; follow it for your own keys too. Run gitleaks before any push, per house policy — an autonomous agent makes an accidental secret commit more likely, not less.
• Parallel agents on a Linux/WSL dev box. The desktop app's multi-agent orchestration and the CLI's /agents subagents both shine when the checkout is on ext4 (~/code, not /mnt/c) — the agents stat and build constantly, and the 9P boundary tax compounds across parallel threads. Prefer the agy CLI inside WSL for the same reason the Cursor guide prefers its CLI there: it sidesteps GUI/WSLg entirely.
• Sidecars are a scheduler you already have. A schedule builtin Sidecar can run a nightly npm audit + gitleaks sweep, or reconcile a staging deploy, and file the result as an Artifact — cheaper than wiring a separate cron/GitHub Action for repo-local chores. They live under ~/.gemini/config/, so they're per-machine, not committed.
• Headless agy for CI, but treat it as pre-authorized. agy -p ... --output-format json | jq slots into a pipeline, but seed auth from an interactive session first (fresh CI runners have no keyring). Use --output-format streaming-json when you want progress, and rely on the stdout/stderr split to keep captured output clean.
• Public preview — pin nothing, re-verify often. Surfaces, model lineup, quotas, and even doc URLs move (this guide already spans the Nov 2025 launch and the I/O 2026 2.0 pivot). Re-check antigravity.google/docs on each review; treat versions here (agy v1.1.17, IDE v2.5.5, SDK 0.1.14) as snapshots.
• Provenance unaffected. Antigravity is a development tool; it ships no artifact of ours. SLSA policy (supply-chain/) attaches to what a codeAmani project publishes, not to the agent that helped write it. Dependency review, secret scanning, and code review still apply to whatever an agent generates — an agent-authored PR gets the same scrutiny as a human one.
• Kenya-targeted projects. Nothing Antigravity-specific, but the mobile-first, low-bandwidth constraints from AFRICAN_MARKET_GUIDE.md are worth stating in the Project's context / a skill so an agent doesn't cheerfully add a heavy dependency to a page a Nairobi user loads on 3G.

Official docs:

• https://antigravity.google/docs/overview
• https://antigravity.google/docs/getting-started
• https://antigravity.google/docs/cli/install
• https://antigravity.google/docs/cli/subagents
• https://antigravity.google/docs/models
• https://antigravity.google/docs/sdk/overview