Antigravity CLI: a practical guide to Google’s agy

Antigravity CLI is Google’s coding agent for the terminal. You install it with one script, start it with agy inside a project, sign in with your Google account and describe the task. It reads your files, proposes edits and commands, and in its default mode asks before it changes anything.

If you used Gemini CLI on a personal account, this is where you ended up. Google’s developer blog post of May 19, 2026 announced that Gemini CLI would stop serving Google AI Pro and Ultra subscribers and free users of Gemini Code Assist for individuals on June 18, 2026. This guide covers install, sign-in, project instructions, models and effort, modes and permissions, MCP, key commands, the migration from Gemini CLI and the limits Google states. Everything here comes from Google’s Antigravity documentation as of November 2026.

What Antigravity CLI is and who it’s for

Antigravity CLI is the terminal client of Google Antigravity, Google’s agent-first development platform. According to Google it is written in Go and shares its agent harness with the Antigravity 2.0 desktop app, so improvements to the agent land in both. It keeps the building blocks Gemini CLI users know: agent skills, hooks, subagents and extensions, which are now called plugins.

It’s for you if you:

• used Gemini CLI with a personal Google account, Google AI Pro or Ultra;
• want a coding agent in the terminal that runs Gemini models (and, depending on your plan, others);
• already use Antigravity on the desktop and want the same agent over SSH or in scripts.

Teams with a Gemini Code Assist Standard or Enterprise license, or a paid Gemini API key, can stay on Gemini CLI. Our Gemini CLI guide covers that path. Google is open about the gap: the blog post says there won’t be 1:1 feature parity right away.

Install

On macOS and Linux the binary lands in ~/.local/bin/agy; on Windows in AppData\Local\agy\bin. Check it:

agy --version

Sign in

Move into a project and start it:

cd my-project
agy

The first run asks for a color scheme, a rendering mode (Alt-Screen or Inline) and whether you trust the folder. Then it opens the browser so you can sign in with your Google account. Personal accounts on the Free, Pro and Ultra plans work; business accounts sign in through Gemini Enterprise. The token is stored in your OS keyring (Keychain, Secret Service or Windows Credential Manager), so later launches skip the browser.

Other options:

• Over SSH: agy prints a URL. Open it on your own machine, sign in and paste the code back into the terminal.
• Gemini API key: set "modelProvider": "gemini" in ~/.gemini/antigravity-cli/settings.json and export GEMINI_API_KEY. The key alone does nothing without that setting.
• Google Cloud credentials: run gcloud auth application-default login and set AGY_ADC_AUTH=true.

/logout clears the saved sign-in.

Your first task

Explain how the payment module is structured, then add input validation
to the refund endpoint and run the tests.

A few shortcuts from day one: @ suggests file paths, ! at the start of a prompt runs a shell command, and ? shows help with the slash commands. For scripts, agy -p "summarize README.md" runs one prompt headless and prints the answer; add --output-format json when another program reads it. agy -i "prompt" starts the interactive UI with a first prompt.

Project instructions: AGENTS.md or GEMINI.md

Antigravity reads AGENTS.md or GEMINI.md in the folder where you start agy and in its parents up to the repo root. Both are always active and need no frontmatter. Global rules go in ~/.gemini/AGENTS.md or ~/.gemini/GEMINI.md. Rules add up rather than replace each other.

# Project: billing-service

## Commands
- Install: npm ci
- Test: npm test (run before you say a task is done)

## Don't
- Don't edit files in src/generated.

For finer control, put Markdown files in .agents/rules/. Each needs frontmatter with a trigger: always_on, model_decision, glob (applies when the agent touches matching files) or manual. A missing or invalid trigger means the rule is silently dropped, and the CLI doesn’t support manual rules because it has no rule mentions. Keep files short: each is cut off after 24,000 bytes, and global plus always_on rules share a 20,000-token budget.

If Codex or another agent already reads your AGENTS.md, Antigravity picks up the same file. CLAUDE.md vs AGENTS.md explains how to share one set of rules with Claude Code.

Models and effort

Pick a model per run with --model (agy models lists them) or in a session with /model. Google’s models page lists Gemini models such as Gemini 3.8 Flash and Gemini 3.1 Pro next to Claude and GPT-OSS models; which ones you see depends on your plan.

Effort sets how hard the model thinks. /effort opens a gauge and saves your choice as the default; --effort low applies to one run only. The levels are low, medium, high, xhigh and max, but most models offer only low to high, and models with a fixed budget ignore it.

Modes and permissions

Start with --mode=accept-edits (or auto, plan), cycle with Shift+Tab, or set "agentMode" in ~/.gemini/antigravity-cli/settings.json. auto needs the sandbox and a personal account (v1.3.5+ on macOS and Linux, v1.4.4+ on Windows); business accounts don’t get it. --sandbox runs a session in the terminal sandbox.

Fine-grained rules live in the same settings file as allow, ask and deny lists, for example command(git) or mcp(sql/execute_mutation). Deny beats ask, ask beats allow. /permissions edits them in the UI. --dangerously-skip-permissions approves everything; use it only in a throwaway environment. AI coding agent security explains why.

MCP servers

MCP servers live in their own file: ~/.gemini/config/mcp_config.json for every project, .agents/mcp_config.json for one workspace.

{
  "mcpServers": {
    "local-db": { "command": "node", "args": ["/path/to/server.js"] },
    "docs": { "serverUrl": "https://api.example.com/mcp/", "headers": { "Authorization": "Bearer TOKEN" } }
  }
}

Remote servers must use Streamable HTTP; the old HTTP+SSE transport and httpUrl aren’t supported. /mcp opens a manager with status, reload and logs. Tools you haven’t allowed run in Ask mode.

Commands worth knowing

From the shell, agy -c continues the latest conversation in this folder and --conversation <id> resumes a specific one. --add-dir adds another folder to the workspace.

Moving from Gemini CLI

The first time you run agy on a machine with Gemini CLI config, a checklist asks what to migrate: extensions, global configuration, session tokens and display settings. What carries over and what doesn’t, per Google’s migration guide:

• Unchanged: GEMINI.md and AGENTS.md in the project, ~/.gemini/GEMINI.md, and global skills in ~/.gemini/skills/.
• Converted: extensions become plugins with agy plugin import gemini, which turns their commands into skills.
• Move by hand: workspace skills from .gemini/skills/ to .agents/skills/; MCP servers out of ~/.gemini/settings.json into mcp_config.json, with url or httpUrl renamed to serverUrl.
• Not guaranteed: some custom themes and visual overlays.
• Flags: --approval-mode is gone; use --mode. There is no yolo mode.

Limits and pricing

Google’s plans page includes the CLI in every plan and describes quotas without numbers: Ultra has the highest quota, refreshed every five hours; Pro has a high quota refreshed every five hours until a weekly limit; other plans get a quota refreshed weekly. Limits follow how much work the agent does. On Pro and Ultra, AI credits can cover usage past the quota at Gemini Enterprise consumption pricing, and an overage setting lets you turn that off. /usage and /credits show where you stand.

Running it next to Claude Code and Codex

Antigravity is often one of several agents. A few habits keep that sane:

• One shared rules file. Antigravity and Codex both read AGENTS.md; Claude Code reads CLAUDE.md, which can point to it.
• One worktree per agent. Give each agent its own git worktree so they don’t edit the same files.
• Same MCP servers everywhere. Each tool keeps its own config file, so the same server has to be added three times.

We build AgentVera, a desktop app for macOS, Windows and Linux that runs Antigravity CLI next to Claude Code, Codex, Gemini CLI and other agents, each in a real terminal with your own install and sign-in. For Antigravity specifically (details):

• Workspace: Antigravity is one tile in a grid of agents per project and returns to its conversation after a relaunch.
• Permissions: Ask, Auto (--mode=accept-edits) or Full access (--dangerously-skip-permissions) per agent.
• Model and effort: set a model and low, medium or high effort when you create the agent.
• Instructions: agy has no flag for extra instructions, so keep rules in AGENTS.md or GEMINI.md.
• MCP manager: servers you set up once are added to Antigravity at launch, next to your own mcp_config.json.
• Worktrees: create one from the Git panel and start Antigravity in it, with Claude Code in another.

The grid, worktrees, code review and the MCP manager are on the free plan. For how Google’s agents compare with Anthropic’s, read Gemini CLI vs Claude Code, or download AgentVera.

Wrapping up

Install with the script, run agy, sign in with Google, and keep your existing AGENTS.md or GEMINI.md. Move MCP servers to mcp_config.json, import extensions with agy plugin import gemini, start in default or accept-edits mode, and check /usage before long sessions.