The DDS Antigravity Onramp Masterclass

Why This Class Exists

Most "first day with a new tool" tutorials underestimate four specific things about Antigravity 2.0. This class is built around them.

The reinforcing pattern: each of these is benign in isolation, but together they form the four-corner trap of a bad first day. Get all four right and the agent feels capable. Miss any and the agent feels broken.

What Is Antigravity 2.0?

Google Antigravity 2.0 is an agent-first standalone desktop IDE that launched on May 27, 2026 at I/O 2026. It was rebuilt from the ground up to direct autonomous AI agents rather than to autocomplete code as you type. The application is free during public preview. Heavy daily use requires a paid tier starting at twenty US dollars per month.

The default reasoning model is Gemini 3.5 Flash. Heavier multi-file work routes to Gemini 3.1 Pro. The bundled Antigravity CLI uses the binary name agy and supersedes Gemini CLI, which retires on June 18, 2026.

The mental model is different from Cursor or VS Code with Copilot. You do not type code and accept completions. You direct work through an Agent Manager interface, the agent produces an Implementation Plan as an Artifact in the Auxiliary Pane, you review the plan, and you click Proceed. The agent then executes. Read the masterclass on the Antigravity 2.0 platform itself for the deep dive. This class is about getting you cleanly to your first prompt.

The v1.x → v2.0 Paradigm Shift

If you have never used Antigravity before, skip to System Requirements. If you are on the v1.x line (versions 1.11.2 through 1.23.2, released November 2025 through April 2026), this section is the spine of your migration.

The DDS install used to produce this masterclass is itself a v1.x install at IDE version 0.26.0, with the v1.x global-config model and three months of accumulated state on disk. The comparison below is grounded in that real evidence, not in theory.

Where Antigravity stores your data

What a 3-month-old v1.x install actually looks like on disk

The DDS install referenced throughout this masterclass has been in use since February 26, 2026 — roughly three months at the time of writing. The footprint:

Total: ~40 GB. File count: 82,286 files across 1,509 directories (excluding browser cache and backup mirror). The largest single file is a 87 MB browser recording at antigravity/brain/<uuid>/recording.webm.

The "dva-academy 2 / 3" gotcha — caught in the wild

The DDS install has three project bindings all pointing at the same folder:

config/projects/7fd5bdba-….json   →  name: "dva-academy"     →  file:///f%3A/dva-academy
config/projects/92ec35d0-….json   →  name: "dva-academy 2"   →  file:///f%3A/dva-academy
config/projects/cc25ef8b-….json   →  name: "dva-academy 3"   →  file:///f%3A/dva-academy

This happens when you reopen the same folder after deleting a project entry, when the folder URI hash changes, or after a v1.x → migration event. The duplicate entries are benign (only the most recently active one drives agent context) but they accumulate. Clean-up: open config/projects/, find the duplicate JSON files, delete all but the most recently modified one. Then restart Antigravity. The project list in the sidebar repopulates from the file system on next launch.

In v2.0 this becomes less common because Projects are explicit named entities created through the Agent Manager UI rather than auto-created on folder open.

System Requirements

Hardware and OS minimums for Antigravity 2.0 across all three supported platforms. Numbers from the official install guide as of May 27, 2026.

Internet required at first launch for OAuth sign-in and agent model initialization. After that, Antigravity can run in a degraded offline mode for local workspace tasks that do not require Gemini API calls. Full agent functionality including model reasoning and browser tasks needs a live connection.

Storage planning: the 2 GB minimum gets you through install. Real-world steady-state usage on heavy projects (DDS reference: ~40 GB after three months) grows substantially with conversation history, browser recordings, and the automatic backup mirror. Plan for at least 50 GB free on your working drive if you intend to use the agent intensively.

The Three Non-Obvious Install Trip-Wires

C:\Program Files\Google Antigravity

These three trip-wires account for the overwhelming majority of "Antigravity won't sign me in" reports in the first hours of use. Get all three right before you ever click the installer.

The 8 Mental Model Shifts

If you are coming from VS Code, Cursor, or Antigravity v1.x, the framework looks similar at first glance — file tree on the left, editor in the middle, panes around it. But the workflow is fundamentally different. These eight shifts are what separate users who feel productive in week one from users who churn within forty-eight hours.

Shift 1 — You direct, you don't type

In Cursor or VS Code with Copilot, you write code and the AI autocompletes alongside you. In Antigravity 2.0, you describe what you want and the agent writes the code. Your job is to compose the right instruction, not to compose the right syntax.

Beginners carry over IDE habits — they type into the prompt box like they would type into an editor, then expect autocompletion. Antigravity does not work that way. Treat the prompt box like you would treat a chat with a senior developer who needs context: be specific about the file, the goal, the constraints, and the success criteria.

// In the prompt box:
function processOrders

In src/orders/processor.js, add a
function processOrders(orders) that
takes an array of order objects,
filters out cancelled orders, sorts
remaining by created_at descending,
and returns the top 10. Match the
existing module's export style.

Shift 2 — Projects, not workspaces

v1.x and most IDEs let you "open a folder" and that folder becomes your workspace. Antigravity 2.0 introduces Projects, which are explicitly created configurations that can contain one folder or multiple folders, each with its own settings.

A frontend repo plus a backend repo can be one Project, with the agent able to see both folder trees as a single context. v1.x users will reach for "open folder" and find it nowhere on the main menu — that command does not exist in 2.0. Create a Project instead, then add folder resources to it.

Project state lives at the Project level: agent persona, default model, registered MCP servers, custom skills, permission grants. Forking a Project ships all of that configuration with the code.

Shift 3 — Plan mode is the default for anything non-trivial

The Agent Manager has two execution modes: Plan and Fast. Plan mode produces an Implementation Plan as an Artifact, you review it in the Auxiliary Pane, then you click Proceed. Fast mode skips the plan and executes immediately.

Plan mode is slower because of the review gate. The review gate is the entire point. If you find yourself defaulting to Fast mode for everything, you have given up the supervision pattern that makes the agent trustworthy.

Shift 4 — The Auxiliary Pane is the review gate

The Auxiliary Pane lives in the top right corner of the Agent Manager. It is togglable. When you run a Plan-mode prompt, the agent produces Artifacts here:

• Implementation Plan — the agent's intended sequence of changes
• Task List — the broken-down sub-tasks the agent will execute
• Code diffs — before/after for each file the agent will modify
• Browser screenshots — when the agent uses the Chrome extension to browse
• Tool execution traces — for MCP tool calls and command runs

The single most common beginner mistake is clicking Proceed without reading the Implementation Plan. The agent's plan is always reviewable before execution. Reviewing it is the difference between supervised autonomy and a destructive surprise.

Shift 5 — AGENTS.md travels with the Project

v1.x stored agent configuration globally in ~/.gemini/config/config.json. v2.0 moves per-Project configuration into a file at the Project root called AGENTS.md. This file defines:

• Agent persona and tone
• Default model for this Project
• Permitted tools (MCP servers, file system scopes, command execution)
• Auto-continue policy (does the agent need approval between steps?)
• Project-specific guardrails (forbidden directories, must-preserve files, code style rules)

Because AGENTS.md lives in the Project itself, the configuration ships with the code when you fork or share the Project. This is what makes Antigravity Projects portable in a way that v1.x workspaces never were.

Shift 6 — Permissions accrete; review them periodically

Every time you let the agent run a new command or access a new URL, the permission gets stored in the global allow-list (v1.x) or in the Project's permission scope (v2.0). Over months of use this list grows substantially.

The DDS install referenced in this masterclass has over fifty entries in userSettings.globalPermissionGrants.allow after three months — covering commands like powershell, git status, npm install, lighthouse, URL access to ddsboston.com and localhost, file reads scoped to specific project paths, and MCP-scoped tool calls like mcp(shopify/get-products).

Review the allow-list every few weeks. Remove entries you no longer need. Pay specific attention to anything containing inlined credentials — credentials in permission entries get persisted to disk in clear text. The fix is to reference environment variables in your MCP commands instead of inlining secrets.

Shift 7 — Conversations are SQLite databases, not chat logs

Antigravity stores each conversation as a SQLite database at conversations/<uuid>.db with the live transaction log in conversations/<uuid>.db-wal. In parallel, a plaintext brain/<uuid>/.system_generated/ tree holds:

• logs/transcript.jsonl — full conversation transcript
• messages/<uuid>.json — individual message records
• tasks/task-NN.log — per-task execution logs
• messages/cursor.json and read.json — UI state pointers

You can query a conversation's SQLite database directly with any SQLite browser — useful for extracting prompts, recovering deleted artifacts, or analyzing your own usage patterns. The plaintext brain tree is easier for grep-based recovery when you remember a phrase but not which conversation.

Shift 8 — The 4 profile trees serve different purposes

v1.x installs end up with up to four sibling directories under ~/.gemini/:

If you need to reclaim disk space without breaking your install, delete antigravity-backup/ first. It is the largest deletable tree (~19 GB on the reference install) and Antigravity recreates it automatically. antigravity-browser-profile/ is the second-largest deletable target (~1.9 GB).

v2.0 consolidates these four trees into a single per-Project tree. Disk usage drops accordingly.

The First Launch Walkthrough

Ten steps from download to your first executed agent task. Each step is one concern. If a step fails, fix it before moving to the next.

1. Create file HELLO.md at Project root with markdown heading and paragraph.
2. Run "git status" to confirm new untracked file.
3. Report success.

# AGENTS.md

## Persona
You are a focused, evidence-based developer working on this Project.
Default to Plan mode for any task touching more than one file.

## Default Model
gemini-3.5-flash

## Auto-Continue
auto_approve: false

## Forbidden Operations
- Do not commit to git without explicit instruction.
- Do not delete files outside this Project's folder tree.
- Do not push to remote without explicit instruction.

## Project Context
[1-2 paragraphs describing what this Project does, who uses it,
and what kind of code lives here]

agy --version          # should print 2.x.x
agy login              # opens Chrome OAuth (same flow as Step 4)
agy run "echo hello"   # smoke test

That is the ten-step onramp. After Step 10, you have a working install with a registered Project, a first prompt executed, the Chrome extension active, AGENTS.md committed, and the CLI ready. Everything from here is iteration.

Authoring AGENTS.md

AGENTS.md is the per-Project configuration file that ships with your code. It controls agent persona, default model, permitted tools, auto-continue policy, and Project-specific guardrails. Living at the Project root means the configuration travels with the code through forks, shares, and git pushes.

The full schema

# AGENTS.md

## Persona
[Describe the agent's voice, tone, and decision-making style. This is
prepended to the system prompt for every agent run in this Project.]

## Default Model
[Model identifier. Common values: gemini-3.5-flash (default for speed),
gemini-3.1-pro (heavier reasoning), gemma-4-27b (local via Ollama).]

## Auto-Continue
auto_approve: false              # require manual approval between sub-tasks
# OR
auto_approve: true               # agent continues without prompting
# Destructive operations always prompt regardless of this setting.

## Permitted Tools
[List of MCP servers and tool scopes the agent may call. Restricts the
agent to a smaller surface than the global allow-list.]
- mcp(shopify/*)                 # all Shopify MCP tools
- mcp(chrome_devtools/*)         # all browser inspection tools
- command(git status)            # specific commands only
- command(npm test)
- read_url(*.ddsboston.com)      # URL access scoped to a domain
- read_file(./src/**)            # file reads scoped to a subdirectory
- write_file(./src/**)           # file writes scoped to a subdirectory

## Forbidden Operations
[Explicit block list. Takes precedence over Permitted Tools when in conflict.]
- Do not commit to git without explicit instruction.
- Do not push to remote without explicit instruction.
- Do not delete files outside this Project's folder tree.
- Do not call MCP servers that handle production data.

## Project Context
[1-3 paragraphs describing what this Project does, what stack it uses,
who uses the resulting code, and any non-obvious constraints. The agent
references this on every task.]

## Style Rules
[Code style preferences, naming conventions, file organization rules.
Optional. Useful for keeping multi-session work consistent.]
- Use TypeScript strict mode.
- Prefer functional components over class components.
- Files in src/components/ use PascalCase. Files elsewhere use kebab-case.
- Inline comments only where the why is not obvious from the what.

## Skills
[Custom skills this Project uses. Skills are .md files at
.antigravity/skills/<skill-name>/SKILL.md within the Project.]
- shopify-dds-mastery
- accessibility-audit-runner

DDS reference example

The AGENTS.md for the DDS Vibe Academy Project, derived from the real configuration in use:

# AGENTS.md — DDS Vibe Academy

## Persona
You are a senior Shopify Liquid developer working on the Design Delight
Studio Atelier 2.1.1 theme. You write evidence-based code, validate before
presenting, and never invent facts, numbers, certifications, or claims.
You default to Plan mode for any multi-file work.

## Default Model
gemini-3.5-flash

## Auto-Continue
auto_approve: false

## Permitted Tools
- mcp(shopify/*)
- mcp(shopify-dev-mcp/*)
- mcp(chrome_devtools/*)
- command(git status)
- command(git diff)
- command(lighthouse)
- command(npx)
- read_url(ddsboston.com/*)
- read_url(cdn.shopify.com/*)
- read_file(./**)
- write_file(./**)

## Forbidden Operations
- Never push directly to the live theme. Always push to a testing theme first.
- Do not commit to git without explicit instruction.
- Do not introduce internal links until they are confirmed live.
- Do not claim brand-level certifications. Use supplier-attributed phrasing only.

## Project Context
This Project develops Shopify Liquid sections and page templates for
ddsboston.com on the Atelier 2.1.1 theme running Shopify Basic. Every
deliverable is audited against an 8-check validation gate (NULL bytes,
JSON-LD parse, schema name length, range step alignment, Liquid balance,
forbidden strings, internal link verification) before push.

## Skills
- shopify-dds-mastery

Registering MCP Servers

MCP (Model Context Protocol) servers extend the agent's capabilities beyond file system access. A typical experienced-user configuration registers six to twelve MCP servers covering browsers, databases, third-party APIs, and custom integrations.

The DDS reference install registers eight MCP servers spanning three categories:

The mcp_config.json structure

MCP servers are registered in ~/.gemini/config/mcp_config.json (v1.x) or ~/.antigravity/mcp_config.json (v2.0). The file is a single JSON object with one mcpServers key whose children are named server registrations:

{
  "mcpServers": {
    "cloudrun": {
      "command": "node",
      "args": [
        "C:\\Users\\<user>\\AppData\\Roaming/npm/node_modules/@google-cloud/cloud-run-mcp/mcp-server.js"
      ]
    },
    "shopify-dev-mcp": {
      "command": "node",
      "args": [
        "C:\\Users\\<user>\\AppData\\Roaming/npm/node_modules/npm/bin/npx-cli.js",
        "-y",
        "@shopify/dev-mcp@latest"
      ]
    }
  }
}

Each registration needs three things: a name (used as the MCP-scoped permission identifier), a command (the binary to execute), and an args array (passed to the binary). Most Google-published MCPs install via npm and run with node pointing at the entry-point JS file.

Adding a new MCP server

Three steps. The agent can do this for you once you ask, but understanding the manual process helps when things go wrong.

1. Install the server package. For Google-published servers: npm install -g @google-cloud/cloud-run-mcp (or whatever the package name is). For third-party servers: follow their install docs.
2. Add the registration to mcp_config.json. Open the file in any editor, add a new key under mcpServers, save.
3. Restart Antigravity. MCP registrations are loaded at app start. Restart picks up the new server.

The credential pattern: use environment variables, not inlined secrets

"shopify": {
  "command": "node",
  "args": [
    "/path/to/shopify-mcp/dist/index.js",
    "--accessToken=shpat_abcd1234...",   // ← TOKEN IN CLEAR TEXT ON DISK
    "--domain=mystore.myshopify.com"
  ]
}

The correct pattern: reference an environment variable in the args array. Most MCP servers support this natively.

"shopify": {
  "command": "node",
  "args": [
    "/path/to/shopify-mcp/dist/index.js",
    "--accessToken=${SHOPIFY_ADMIN_TOKEN}",
    "--domain=mystore.myshopify.com"
  ],
  "env": {
    "SHOPIFY_ADMIN_TOKEN": "${SHOPIFY_ADMIN_TOKEN}"
  }
}

Then set the environment variable in your shell profile (~/.bashrc, ~/.zshrc, or Windows System Environment Variables UI). Antigravity inherits your shell environment at launch and the substitution happens at server-spawn time.

Rotate tokens regularly. If a token ever ends up in your mcp_config.json or in the globalPermissionGrants.allow array, treat it as exposed and rotate immediately.

The May 2026 MCP load bug

The initial v2.0 launch had a known bug where MCP servers failed to load on first start after the upgrade. Symptom: agent reported "no tools available" or specific MCP-scoped permissions denied even when registered.

Workaround until you patch to v2.0.x: after registering a new MCP, do a full quit (not just close) and relaunch Antigravity. The bug was patched within the first week of the launch.

CLI Migration: gemini → agy

Gemini CLI retires on June 18, 2026. The Antigravity CLI under the binary name agy is a superset of Gemini CLI — every command works the same plus new multi-agent and SDK capabilities. Migrate now.

Command mapping

One-time migration steps

# 1. Verify agy is on PATH (installed automatically with v2.0 desktop)
agy --version

# 2. Sign in (uses your existing Google session if browser is logged in)
agy login

# 3. Smoke test
agy run "echo hello from agy"

# 4. (Optional) symlink for muscle memory during transition
ln -s $(which agy) /usr/local/bin/gemini

# 5. Update any shell scripts, CI configs, or aliases that reference `gemini`
grep -r "gemini " ~/.bashrc ~/.zshrc ~/.config/ /etc/ 2>/dev/null

Your Gemini CLI credentials carry forward automatically — Antigravity reads the same OAuth token cache. If agy login succeeds without opening a browser, that means it found an existing token and is reusing it.

The Antigravity SDK

The Antigravity SDK exposes the managed agent as a programmable interface. Available in Python, TypeScript, and Go. Use cases: embedding agent behavior in CI/CD pipelines, scheduled jobs, your own products, or batch operations across many Projects.

Python

pip install antigravity-sdk

from antigravity import Agent, Task

agent = Agent(model="gemini-3.5-flash")

task = Task(
    description="Refactor the authentication module to use JWT",
    workspace="/path/to/project",
    constraints=[
        "Don't modify the public API",
        "Maintain backward compatibility",
        "Add tests for the new JWT flow"
    ],
    auto_approve=False,  # Plan mode equivalent
)

result = agent.execute(task)
print(result.summary)
print(result.files_changed)
print(result.implementation_plan)  # the same Plan Artifact you'd see in the UI

TypeScript

npm install @antigravity/sdk

import { Agent, Task } from "@antigravity/sdk";

const agent = new Agent({ model: "gemini-3.5-flash" });

const task: Task = {
  description: "Add error handling to all async functions in src/api/",
  workspace: "/path/to/project",
  constraints: ["Don't change function signatures"],
  autoApprove: false,
};

const result = await agent.execute(task);
console.log(result.summary);
console.log(result.filesChanged);

Go

go get github.com/google/antigravity-sdk-go

import "github.com/google/antigravity-sdk-go/antigravity"

agent := antigravity.NewAgent(antigravity.AgentConfig{
    Model: "gemini-3.5-flash",
})

task := antigravity.Task{
    Description: "Generate OpenAPI spec from the routes/ directory",
    Workspace:   "/path/to/project",
    AutoApprove: false,
}

result, err := agent.Execute(task)
if err != nil {
    log.Fatal(err)
}
fmt.Println(result.Summary)

The SDK uses the same backend as the desktop Agent Manager. Tasks executed via SDK appear in your conversation history alongside Agent Manager runs. Permissions and AGENTS.md still apply — the SDK does not bypass the security model.

First-Day Prompts Library

Six paste-ready prompts to run in your first session. Each is scoped narrowly enough that the agent will succeed on the first try, broad enough to teach you how the framework responds.

Prompt 1 — Workspace Inventory

Inventory this Project's folder structure. List every file and directory
at depth 1 and 2. For each top-level directory, briefly describe what
it appears to contain based on file names and extensions. Output as a
markdown tree. Do not modify any files. Do not commit anything.

Tests: file system access, read-only behavior, markdown formatting, structured output.

Prompt 2 — Git Health Check

Run "git status", "git log --oneline -10", and "git branch -a" in this
Project. Report a 3-paragraph summary: (1) current branch state and any
uncommitted changes, (2) what the last 10 commits suggest about recent
work, (3) any branches that look stale or abandoned. Do not commit, do
not push, do not delete branches.

Tests: command execution, multi-step planning, narrative synthesis.

Prompt 3 — Dependencies Audit

Find every package manifest in this Project (package.json, requirements.txt,
go.mod, Gemfile, Cargo.toml, etc.). For each manifest, list the direct
dependencies with their declared versions. Identify any dependency that
appears in more than one manifest with different version constraints.
Output as a markdown table. Do not run any install commands.

Tests: file system traversal, conditional logic, conflict detection, table formatting.

Prompt 4 — README First Pass

Read the README.md if one exists. If one does not exist, create a draft
README.md at the Project root with the following sections: Overview,
Installation, Usage, Project Structure (derived from a depth-2 inventory),
and Contributing. Base the Overview and Usage sections on your inspection
of the actual code, not on assumptions. Do not commit. Use Plan mode
and show me the draft before saving.

Tests: conditional behavior, code reading, content generation, Plan-mode review gate.

Prompt 5 — Local Server Smoke Test

Determine how this Project is meant to run locally based on the package
manifest and any scripts directory. Suggest the command to start a dev
server. Do not run it yet — explain what the command does and what port
it would bind to, then ask me to confirm before executing.

Tests: code inference, port-binding reasoning, explicit consent gate before destructive action.

Prompt 6 — The First Refactor

Pick a single file in this Project under 200 lines that contains at least
one function. Read the file. Identify ONE refactoring opportunity (extract
function, rename variable, simplify conditional, etc.). Propose the
refactor as a code diff in Plan mode. Do not apply it until I approve.

Tests: code understanding, judgment about scope, diff generation, Plan-mode discipline.

Common First-Day Mistakes

Seven specific patterns that show up in first-day frustration reports. Each one has a clean fix.

Mistake 1 — Treating the prompt box like an editor

Symptom: you type partial code into the prompt input expecting autocompletion.

Fix: treat the prompt box like a Slack message to a senior developer. Describe the file, the goal, the constraints, and the success criterion. See Mental Shift 1 for the explicit pattern.

Mistake 2 — Clicking Proceed without reading the Implementation Plan

Symptom: the agent executes something different from what you wanted. Files get modified you did not expect. The conversation goes off the rails.

Fix: toggle the Auxiliary Pane open before clicking Start Conversation. Make reading the Implementation Plan your default behavior. If the plan looks wrong, comment in the conversation and let the agent revise — do not just click Proceed and hope.

Mistake 3 — Picking Fast mode for everything

Symptom: you discover bad changes after the fact because there was no review gate.

Fix: default to Plan mode. Use Fast mode only for operations you have repeated successfully many times or for trivial single-line edits where the review gate is more overhead than safety.

Mistake 4 — Opening the same folder under different names

Symptom: your sidebar shows three Projects named "myproject", "myproject 2", "myproject 3" all pointing at the same folder. Confusing for you, confusing for the agent's context tracking.

Fix: open config/projects/ (or ~/.antigravity/projects/ in v2.0), delete all but the most recently modified JSON pointing at that folder, restart Antigravity. The duplicate Project entries are benign on disk but messy in the UI.

Mistake 5 — Inlining API tokens in mcp_config.json args

Symptom: your mcp_config.json has lines like "--accessToken=shpat_abcd1234..." with the real token in clear text.

Fix: replace the inlined value with ${ENV_VAR_NAME} and set the env var in your shell profile. Restart Antigravity for the env var to be picked up. Rotate the previously-exposed token in the issuing service. See the MCP setup section for the full pattern.

Mistake 6 — Skipping the Chrome extension install

Symptom: any task that needs to browse, screenshot, or interact with a web page fails silently or with "browser tool not available."

Fix: when the agent prompts to install the Chrome extension, click Setup immediately. Verify the install at chrome://extensions/. The extension installs into your signed-in Chrome profile, so make sure you are signed into the same Google account used in Antigravity.

Mistake 7 — Not setting up AGENTS.md

Symptom: agent behavior drifts across sessions. You explain the same constraints repeatedly. The agent commits to git or modifies forbidden files because there is no per-Project guardrail.

Fix: create an AGENTS.md at the Project root in your first session. Include at minimum: persona, default model, auto-continue policy, and forbidden operations. See the AGENTS.md authoring section for the full schema.

The Chaotic Launch Week (May 20-27, 2026)

The Antigravity 2.0 release week was unusually rough. Documenting it here so users coming to the platform in late May or early June have context for what they are reading in older guides versus newer ones.

What this means for your reading

Guides dated before May 23 may describe a UI where the IDE entry point is hidden — that UI is no longer current. Guides dated between May 20 and May 27 reference behaviors that have since been patched. Use guides dated May 27 or later (this one included) for current state.

If your install behaves differently from this documentation, check your version: agy --version at the CLI, or Help → About in the Agent Manager. Anything older than v2.0.0 stable means you are still on a preview build. Update to the stable release.

Troubleshooting

Five specific failure modes with the exact diagnosis sequence that resolves each.

Q: I install on Windows and the OAuth sign-in loops forever. What happened?

1. Did you install to a non-default path? ~70% of custom-path installs break OAuth. Uninstall, reboot, reinstall to C:\Program Files\Google Antigravity.
2. Is Chrome your default browser? OAuth redirect requires Chrome specifically. Set it as default in Settings → Apps → Default Apps, then re-launch Antigravity.
3. Are you using a Workspace account? Personal Gmail only during preview. Use a free @gmail.com account.
4. Did your antivirus block the OAuth callback URL? Temporarily disable the antivirus, complete sign-in, then re-enable. Some endpoint protection blocks http://localhost callbacks.

Q: I created a Project but the agent can't see my files. What's wrong?

1. Did the Project add the folder with allowWrite: true? Check config/projects/<uuid>.json — if the resource is a bare folderUri without gitFolder wrapper, the agent has read-only access.
2. Is the folder path actually correct? The Project JSON uses URL encoding (file:///f%3A/dva-academy = F:\dva-academy). Verify by manually navigating to the path.
3. Does the folder contain a .gitignore blocking files? Antigravity respects gitignore by default. Files matching gitignore patterns are excluded from agent context.
4. Restart Antigravity after Project creation. New folder bindings sometimes need a restart to fully load.

Q: My MCP server isn't loading. The agent says the tools aren't available.

1. Is this the May 2026 MCP load bug? Full quit + relaunch Antigravity. The bug was patched in v2.0.x — verify your version.
2. Is the command in the registration actually on PATH? Run the exact command from your terminal — if it errors, fix the path before expecting Antigravity to launch it.
3. Are the args pointing at a file that exists? Most Google MCP packages install under $HOME/AppData/Roaming/npm/node_modules/ on Windows. Verify the entry-point JS file is actually there.
4. Check the agent logs at antigravity/conversations/<active-uuid>.db-wal via a SQLite browser, or brain/<uuid>/.system_generated/logs/transcript.jsonl as plaintext. MCP load errors appear in the transcript.

Q: My Agent Manager says "agent not configured" after the v1 → v2 migration. Now what?

1. Check antigravity/antigravity_state.pbtxt for the migrate_convos_into_projects field. If it reads MIGRATION_STATUS_COMPLETED the migration finished but your Project list needs a refresh.
2. Restart Antigravity. The Project picker should repopulate from the file system.
3. If still empty, manually create a new Project pointing at your existing code folder. Your conversation history persists under antigravity/conversations/ regardless of Project state.
4. For the bug that prevented new-user onboarding completion (patched within the first week of v2.0), update to the latest v2.0.x point release.

Q: My install is consuming way too much disk. How do I reclaim space safely?

1. Quit Antigravity completely.
2. Delete ~/.gemini/antigravity-backup/ entirely. This is the automatic mirror and is safe to delete. The DDS reference install: ~19 GB recovered.
3. Delete ~/.gemini/antigravity-browser-profile/. This is the embedded Chromium profile. Antigravity rebuilds it on first browser use. The DDS reference install: ~1.9 GB recovered.
4. Inside antigravity/brain/<uuid>/ folders, delete any recording.webm files larger than 50 MB if you no longer need those conversation recordings. The DDS install had one 87 MB recording.
5. Do NOT delete antigravity/ or antigravity-ide/ root directories — losing those loses active state.
6. Restart Antigravity. Recovered space should be visible in your disk free indicator.

Architecture Reference: Where Antigravity Stores Your Data

The full v1.x file system layout, grounded in the real DDS install. v2.0 consolidates some of this per-Project but the high-level concepts carry forward.

~/.gemini/
├── antigravity/                          ← active Agent Manager profile (~20 GB)
│   ├── 0.26.0                            (version marker file — name is the version)
│   ├── agyhub_summaries_proto.pb         (607 KB protobuf, conversation summaries)
│   ├── antigravity_state.pbtxt           (onboarding state, model selection, migration flags)
│   ├── installation_id                   (36-byte UUID identifying this install)
│   ├── annotations/                      (per-file annotations from agent runs)
│   ├── bin/                              (helper binaries, language servers)
│   ├── brain/                            (per-conversation working memory)
│   │   └── <conversation-uuid>/
│   │       └── .system_generated/
│   │           ├── logs/transcript.jsonl (full conversation transcript)
│   │           ├── messages/             (per-message JSON records)
│   │           └── tasks/                (per-task execution logs)
│   ├── browser_recordings/               (.webm recordings from browser tasks)
│   ├── context_state/                    (active context window snapshots)
│   ├── conversations/                    (SQLite DBs: <uuid>.db + .db-wal + .db-shm)
│   ├── html_artifacts/                   (HTML preview artifacts)
│   ├── implicit/                         (implicit context derived from workspace)
│   ├── knowledge/                        (Project-specific knowledge base)
│   ├── mcp/                              (MCP-related working files)
│   ├── mcp_config.json → ../config/mcp_config.json  (symlink to active config)
│   ├── playground/                       (experimental space)
│   ├── prompting/                        (prompt templates and saved patterns)
│   ├── scratch/                          (temporary working space)
│   └── skills → ../config/skills        (symlink to active skills tree)
│
├── antigravity-backup/                   ← automatic mirror of active profile (~19 GB)
│   └── (full duplicate of antigravity/)
│
├── antigravity-ide/                      ← IDE-scope profile (~19 GB)
│   ├── (same structure as antigravity/)
│   ├── mcp_config.json                   (IDE-scope MCP registrations, not symlinked)
│   ├── plugins/                          (IDE plugin state)
│   └── skills/                           (IDE-scope skills, not symlinked)
│
├── antigravity-browser-profile/          ← embedded Chromium profile (~1.9 GB)
│   └── (standard Chromium user data dir)
│
├── config/                               ← GLOBAL config (~712 KB)
│   ├── config.json                       (userSettings + globalPermissionGrants.allow[])
│   ├── mcp_config.json                   (active MCP registrations)
│   ├── plugins/
│   ├── projects/                         (per-Project bindings)
│   │   ├── <uuid>.json                 (each project = one JSON file)
│   │   └── ...
│   ├── sidecars/
│   └── skills/                           (installed custom skills)
│       ├── .datacloud_skills_manifest    (skills installation manifest)
│       ├── shopify-dds-mastery/          (custom skill — yours)
│       │   └── SKILL.md
│       └── <google-published skills>/
│
├── tmp/                                  ← scratch artifacts (~72 KB)
├── config.migrated                       (empty file flagging migration ran)
└── GEMINI.md                             (legacy file, may be empty)

What lives where, summarized

Closing Notes for the Next Agent

If you are a fresh Claude Code or Antigravity instance reading this masterclass to bootstrap a new user, here is the compressed playbook:

1. Read the foundation before suggesting any installs. Confirm the user is on a supported OS, has 50 GB of free disk (not just the 2 GB minimum), and has Chrome as default browser. Verify they have a personal Gmail before sign-in.
2. Walk the 10-step First Launch in order. Each step has a known failure mode. Resist the temptation to batch steps. The whole point of the sequence is one concern per step.
3. Get AGENTS.md authored in the first session. Without it, agent behavior drifts across sessions and the user has to repeatedly explain constraints. The minimum-viable AGENTS.md is 8 lines.
4. Teach the Auxiliary Pane review habit before the user has a bad surprise. Demonstrate the review gate by deliberately running a Plan-mode prompt and pointing out where the Implementation Plan appears. Make reading the plan their default.
5. Set up env-var-based MCP credentials from day one. Inlined secrets in mcp_config.json create exposure that is hard to untangle later. The pattern is well-known; use it from the start.
6. Document the install state. Run a config dump like the one this masterclass is built from after the user has six weeks of activity. The dump is the diagnostic baseline if something goes wrong later.
7. Migrate Gemini CLI to Antigravity CLI before June 18, 2026. After that date, scripts referencing gemini as a binary stop working. Update CI configs, shell aliases, and any documentation.

Frequently Asked Questions

Eighteen questions covering what new and migrating users ask most often. The FAQPage JSON-LD schema at the top of this page surfaces these in AI overviews and rich results.