Skip to content
Google Antigravity Docs
Remote Control
NewGemini 4 Argon available in Google AntigravityLearn more

Get started

Section titled “Get started”

Welcome to Google Antigravity! Follow the instructions in this guide to get started on your preferred surface.

Choose your surface

Section titled “Choose your surface”

Download and install

Section titled “Download and install”

  1. Download the Google Antigravity installer for your operating system (or view all builds at antigravity.google/download):

    macOSmacOS 12 (Monterey) or later (Apple Silicon or 64-bit Intel)

    Open the downloaded Antigravity.dmg disk image and drag Antigravity into your Applications folder. If you are upgrading an existing installation, select Replace when prompted instead of Keep Both.

    WindowsWindows 10 (64-bit) or Windows 11

    Run the downloaded .exe installer and follow the guided setup wizard.

    Linuxglibc >= 2.28, glibcxx >= 3.4.25 (Ubuntu 20+, Debian 10+, Fedora 36+, RHEL 8+)

    Extract the archive with tar -xzf Antigravity.tar.gz and launch ./Antigravity.

    GooglebookGooglebook OS (pre-installed on Googlebooks; update or reinstall via Google Play)

    Google Antigravity comes pre-installed on Googlebooks. Open Google Play to install updates or reinstall the application.

  2. Launch Google Antigravity from your applications launcher or menu.

  1. Install the Antigravity CLI (agy) binary using the automated installer for your operating system:

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

    Default binary location: ~/.local/bin/agy

  2. Open a terminal window and verify the installation:

    agy --version

  3. Complete the interactive terminal configuration on initial launch:

    • Color scheme: Select your visual preference (Dark, Solarized Dark, Solarized Light, or terminal default).
    • Rendering mode: Choose Alt-Screen mode (full-screen buffer) or Inline mode (sequential output in terminal history).
    • Workspace trust: Confirm that you trust the repository directory before the agent begins file indexing.

  1. Install the official Google Antigravity extension for your preferred editor, or download the standalone Antigravity IDE:

    Requirements: Visual Studio Code 1.90 or later on macOS, Linux, or Windows.

    Open the Extensions sidebar (Cmd+Shift+X on macOS or Ctrl+Shift+X on Windows/Linux), search for Google Antigravity, and click Install. See the VS Code extension guide.

  2. Sign in with your personal Google Account or Gemini Enterprise credentials (Enterprise support is available in IDE extensions—GA in VS Code and Visual Studio, and in Preview for JetBrains, Zed, and Xcode) when prompted in the Antigravity panel or settings.

  1. Install the official Antigravity Python package inside a Python 3.10+ virtual environment:

    pip install google-antigravity

    If you use Poetry or uv for package management:

    # Poetry
poetry add google-antigravity

# uv
uv add google-antigravity

  2. Authenticate and configure your environment:

    Configure your API credentials in your environment before initializing the agent harness:

    export GEMINI_API_KEY="your_api_key_here"

Start a project

Section titled “Start a project”

Agents operate within Projects, which define the repository boundaries, file scopes, and security permissions for your workspaces.

  1. Click the New Project icon (folder with a plus sign) in the left sidebar.
  2. Click Add Folder to select one or more local Git repositories or working directories.
  3. Click Create.
  4. Type your instruction in the prompt input (for example: Add unit tests for the authentication handlers) and press Enter.
  5. Choose a Mode in the setup modal to boot up your agent:
    • Local mode: The agent operates directly in your active folders.
    • New worktree mode: The agent operates in an isolated Git worktree.

Navigate to any codebase directory in your terminal and start a session:

  1. Create or navigate to a project directory and launch the TUI:

    mkdir agy-demo && cd agy-demo
agy

  2. Enter your first task prompt and press Enter:

    Write a simple python script to fetch web page text

    The agent indexes the workspace, develops an implementation plan, and displays proposed changes for your review.

  3. Open the Artifact Review screen to inspect the proposed code:

    Press Ctrl + R when notified to review generated artifacts:

    • Navigate to the newly created main.py using ↑/↓, or press Tab from the main prompt to inspect inline diffs.
    • Press Y to approve the creation of main.py.
    • Press Esc to close the review panel and return to the primary prompt.

  4. Execute a test command with the agent to verify the output:

    Run the python script and show me the output

    Press Y to confirm and execute python3 main.py. Once finished, press Ctrl + D (or type /exit) to close the TUI session.

  1. Open your workspace folder, repository, or solution in your preferred editor.
  2. Open the Antigravity panel or agent view in your IDE (for example, click the Antigravity icon in the VS Code Activity Bar, press Ctrl+, Ctrl+A in Visual Studio, or select Antigravity in JetBrains AI, Zed External Agents, or Xcode Intelligence).
  3. Enter a task prompt in the conversation panel to start an agent session that shares context and customizations with the rest of the Antigravity ecosystem.
  4. Inspect interactive implementation plans, review granular inline diffs, and execute multi-step engineering tasks directly inside your editor.

  1. Create a file named hello_agent.py to instantiate and run an autonomous agent:

    import asyncio
from google.antigravity import Agent, LocalAgentConfig

async def main():
    # Initialize the local agent harness
    config = LocalAgentConfig()
    async with Agent(config) as agent:
        response = await agent.chat("What files are in the current directory and what is their purpose?")
        print(await response.text())

if __name__ == "__main__":
    asyncio.run(main())

  2. Execute the agent script in your terminal:

    python hello_agent.py

  3. Configure declarative tool policies:

    Use LocalAgentConfig and google.antigravity.hooks.policy to define explicit tool execution rules:

    from google.antigravity import LocalAgentConfig
from google.antigravity.hooks.policy import allow, deny

config = LocalAgentConfig(
    policies=[
        deny("*"),
        allow("view_file"),
    ]
)

Shortcuts and commands

Section titled “Shortcuts and commands”
Section titled “Navigation shortcuts”
ActionmacOSWindows / LinuxDescription
Conversation picker⌘KCtrl + KSearch and switch between active agent threads
File search⌘PCtrl + PFuzzy search and navigate files across the workspace
Focus input⌘LCtrl + LJump cursor focus directly into the agent prompt box
New conversation⌘NCtrl + NStart a fresh autonomous agent session
Cycle conversations⌥ Up / DownAlt + Up / DownMove to previous or next conversation in history

Core slash commands

Section titled “Core slash commands”
CommandDescription
/goalRuns the task autonomously until completion without pausing for intermediate input.
/grill-mePrompts the agent to interview you about requirements before beginning implementation.
/scheduleRuns an instruction as a one-time delayed task or recurring cron schedule.
/browserInitiates browser debugging and research actions in Google Chrome.
/pluginManages installed Marketplace plugins or creates and configures custom plugin bundles.

Common CLI commands

Section titled “Common CLI commands”
CommandDescription
agyLaunches the interactive TUI in the current directory.
agy "prompt"Launches a session with an initial prompt.
/agentsSwitches between active background subagents.
/statuslineToggles or configures the terminal status line display.
/usageDisplays current model credit consumption and quota limits.
/exitCloses the TUI and restores your original shell session.

Keyboard shortcuts

Section titled “Keyboard shortcuts”
ShortcutAction
Ctrl + ROpen the Artifact Review screen to inspect plans and diffs
TabInspect file diffs and tool execution details
Ctrl + CInterrupt current agent generation
Ctrl + OExpand or collapse active tool execution pill
Ctrl + DExit the active Antigravity CLI session
EscExit diff inspector or close active overlay

Editor commands and shortcuts

Section titled “Editor commands and shortcuts”
IDEShortcut / CommandAction
VS Code⌘⇧X / Ctrl + Shift + XOpen Extensions sidebar to install or manage Google Antigravity
Visual StudioCtrl+, Ctrl+AOpen the Antigravity tool window
Zed⌘⇧P / Ctrl + Shift + P → agent: open settingsOpen Agent settings to configure External Agents
JetBrainsJetBrains AI > Settings > AgentsInstall or configure the Antigravity agent
Xcode⌘, → IntelligenceManage and authenticate Antigravity in Xcode Settings

Authentication configuration

Section titled “Authentication configuration”
Auth type (auth.type)Account tierDescription
"oauth-personal"Individual Google AccountsAuthenticates personal Free, Pro, and Ultra plans.
"oauth-business"Gemini Enterprise (Preview)Authenticates corporate identity with gcp.project and gcp.location.
"gemini-api-key"Gemini APIAuthenticates using a Gemini API key.
"agent-platform"Agent Platform (Preview)Authenticates with Gemini Enterprise Agent Platform via API key or ADC.

Common SDK methods and configuration

Section titled “Common SDK methods and configuration”
Method / CommandDescription
await agent.chat(prompt)Sends a user prompt to the agent and returns the turn response.
LocalAgentConfig(policies=...)Configures declarative tool execution policies (allow, deny, ask_user).
LocalAgentConfig(system_instructions=...)Customizes the agent persona and system instructions.
export GEMINI_API_KEY="..."Sets Gemini API credentials in the environment.

Additional resources

Section titled “Additional resources”
smart_toyCore
Features guide

Autonomous subagents, visual artifacts, and tool integrations.

securitySecurity
Permissions

Local security boundaries, sandboxing, and execution gates.

tuneConfig
Settings

Configuration options for projects, models, and agent behavior.

psychologyModels
Choose a model

Reasoning effort levels, thinking budgets, and supported frontier models.

tips_and_updatesWorkflow
Best practices

Verification loops, rule files, and session checkpoints.

buildDebug
CLI troubleshooting

Path resolution, keyring authentication, and SSH forwarding.

terminalReference
CLI reference

Catalog of commands, keybindings, and JSON schemas.

keyboardNavigation
Vim editor mode

Modal navigation and keybindings within the terminal user interface.

extensionExtensions
IDE extensions overview

Supported editors, unified authentication, and enterprise licensing across IDEs.

codeVS Code
Visual Studio Code

Install from the VS Code Marketplace and configure your local workspace.

integration_instructionsJetBrains
IntelliJ-based IDEs

Set up the Antigravity agent in IntelliJ IDEA, PyCharm, WebStorm, GoLand, and Rider.

verified_userEnterprise
Enterprise governance

Configure Gemini Enterprise sign-in, IAM policies, and VPC Service Controls.

code_blocksArchitecture
SDK overview

Architectural overview of the Python runtime harness and async session manager.

badgeAgent API
Personas and directives

System prompt configuration and specialized agent personas.

handymanExtensibility
Tools and skills API

Register custom Python tools, shell executors, and skills.

hubMCP
Model Context Protocol

Integrate external MCP servers and resources into SDK pipelines.