gemini-cli/docs/resources/migrating-to-antigravity-cli.md

Migrating to Antigravity CLI

If you’re an existing Gemini CLI user looking to migrate your workflow to Antigravity CLI, you’ve come to the right place. This guide will help you get familiar and up and running quickly in Antigravity CLI.

TL;DR

Antigravity CLI supports the majority of Gemini CLI’s features. While there isn’t 100% feature parity, workflow-defining features like Gemini CLI extensions (Antigravity plugins), Agent Skills, MCP servers, hooks, and subagents are supported in Antigravity CLI.

On the first launch of Antigravity CLI you should see Migration Options where you can choose to migrate your existing Gemini CLI extensions to the equivalent Antigravity Plugins.

Note: Some Gemini CLI extensions can not be migrated 1:1 to Antigravity plugins as some components (e.g. custom themes, etc) may not be supported.

For the majority of users, you can now get started using Antigravity CLI with the workflows you’ve come to love in Gemini CLI. Antigravity CLI loads in the same context files, global Agent Skills, etc, as Gemini CLI does.

If you notice something not working the way it should or how you expect, come back to this guide for specific details below.

Extensions → Antigravity Plugins

Since Gemini CLI launched extensions (a way to extend Gemini CLI by bundling and sharing capabilities), the industry has standardized on the term plugins. Antigravity Plugins are supported in Antigravity CLI.

Users should be prompted on first launch of Antigravity CLI to have their extensions automatically migrated to plugins.

There is also an explicit command that can be run from the terminal to migrate them:

agy plugin import gemini

Running the above agy plugin import command will find each locally installed extension and convert them to an Antigravity plugin:

  [ok]    conductor
          - skills      : skipped (not found)
          - agents      : skipped (not found)
          ✔ commands    : 6 processed (converted to skills)
          - mcpServers  : skipped (not found)
          - hooks       : skipped (not found)
  [ok]    google-workspace
          ✔ skills      : 6 processed
          - agents      : skipped (not found)
          ✔ commands    : 4 processed (converted to skills)
          ✔ mcpServers  : 1 processed
          - hooks       : skipped (not found)

Context Files (Rules)

Antigravity CLI supports the same context files as Gemini CLI. It supports reading both GEMINI.md and AGENTS.md from your workspace and allows you to have a global context file located at ~/.gemini/GEMINI.md.

Agent Skills

Agent Skills work in Antigravity CLI just as they do in Gemini CLI. They can be managed with the same /skills command and are also converted into slash commands allowing them to be manually invoked.

Global skills for Gemini CLI were located in ~/.gemini/skills/ and are shared with Antigravity CLI across all workspaces. No action is needed for global skills, they are picked up automatically.

Workspace specific skills for Antigravity CLI are stored in .agents/skills which means if you have project/workspace skills in a given project within the.gemini/skills folder they will need to be moved from to .agents/skills

	Gemini CLI	Antigravity CLI
Location	Global: ~/.gemini/skills/ Workspace: .gemini/skills/ or .agents/skills/	Global: ~/.gemini/antigravity-cli/skills/ or ~/.gemini/skills Workspace: .agents/skills/
Management	/skills	/skills
Behavior	Skills become slash commands	Skills become slash commands

Note: Antigravity CLI does not currently have an equivalent to the gemini skills commands for managing Agent Skills. You can create your own skills files or use npx skills install.

MCP Servers

Antigravity CLI supports both local and remote MCP servers and provides the same /mcp command to manage MCP servers. The main difference from Gemini CLI is the file location where mcpServers are defined.

Antigravity and Antigravity CLI store MCP server configurations in a distinct mcp_config.json file whereas Gemini CLI stores them inline in your settings.json.

Note: Antigravity CLI uses serverUrl field instead of url (or deprecated httpUrl) for remote MCP servers.

	Gemini CLI	Antigravity CLI
Location	Global: ~/.gemini/settings.json Workspace: .gemini/settings.json	Global: ~/.gemini/antigravity-cli/mcp_config.json Workspace: .agents/mcp_config.json
Management	/mcp	/mcp

Local MCP server example

For local MCP servers, your mcpServers fields should be the same from Gemini CLI’s settings.json as they are in Antigravity’s mcp_config.json.

For example, to configure the Firebase MCP server, put the following in ~/.gemini/antigravity-cli/mcp_config.json to use across all workspaces (global) or in .agents/mcp_config.json for a single workspace.

{
  "mcpServers": {
    "firebase": {
      "command": "npx",
      "args": ["-y", "firebase-tools@latest", "mcp"]
    }
  }
}

Remote MCP server example

For remote MCP servers you can copy your mcpServers field but need to switch url (or deprecated httpUrl) to be serverUrl which is the field Antigravity CLI uses.

For example, here is the Google Developer Knowledge MCP server configuration for your mcp_config.json using the serverUrl field for Antigravity CLI:

{
  "mcpServers": {
    "google-developer-knowledge": {
      "serverUrl": "https://developerknowledge.googleapis.com/mcp",
      "authProviderType": "google_credentials",
      "oauth": {
        "scopes": ["https://www.googleapis.com/auth/cloud-platform"]
      },
      "headers": {
        "X-goog-user-project": "$GOOGLE_CLOUD_PROJECT"
      }
    }
  }
}

Subagents

Subagents in Antigravity CLI serve the same fundamental purpose as in Gemini CLI, acting as specialized expert personas with their own contexts and tailored toolsets.

The most critical difference between Gemini CLI and Antigravity CLI is execution flow:

• Gemini CLI: Subagent delegation is synchronous. When the main agent delegates a task to a subagent, your active conversation is blocked until the subagent completes its work and reports back.
• Antigravity CLI: Subagents are asynchronous by default. The main agent can delegate parallel workloads or run background research without blocking your prompt interface. You can continue conversing with the main agent while subagents work in the background.

Antigravity CLI also has a define_subagent tool. This allows you to spin up specialized assistants dynamically during an active session.

• Example Prompt: "Create a frontend specialist subagent that excels at modern website design and accessibility audits."

Configuring Custom Subagents

Gemini CLI defines subagents using a single Markdown file containing YAML frontmatter. Antigravity CLI uses a directory structure separating metadata manifest (agent.json) from declarative configuration (config.yaml).

agents/
└── frontend-specialist/
    ├── agent.json        # Required marker file (metadata & routing manifest)
    └── config.yaml       # Declarative configuration (prompts, tools, MCP servers)

Feature	Gemini CLI	Antigravity CLI
Global Location	~/.gemini/agents/*.md	~/.gemini/antigravity-cli/agents/*/agent.json
Workspace Location	.gemini/agents/*.md	.agents/agents/*/agent.json
Config Format	Single .md (YAML Frontmatter)	Split: agent.json + config.yaml
Execution Mode	Synchronous (Blocking)	Asynchronous (Non-blocking)
CLI Management	/agents	/agents

Example Migration: frontend-specialist

Below is a complete walkthrough demonstrating how to migrate a custom Gemini CLI subagent to Antigravity CLI.

Gemini CLI

The subagent for Gemini CLI is configured in .gemini/agents/frontend-specialist.md.

---
name: frontend-specialist
description: Frontend specialist in building high-performance, accessible, and
  scalable web applications using modern frameworks and standards.
tools:
  - read_file
  - grep_search
  - glob
  - list_directory
  - web_fetch
  - google_web_search
model: inherit
---

You are a Senior Frontend Specialist Your goal is to...
<instructions>

Antigravity CLI

To migrate this agent, create a new directory named frontend-specialist inside your workspace directory (.agents/agents/frontend-specialist/) or your global directory.

1. Manifest File (agent.json)

This file acts as the discovery marker and registers the agent's metadata.

{
  "name": "frontend-specialist",
  "description": "Frontend specialist in building high-performance, accessible, and scalable web applications.",
  "configPath": {
    "relativePathToConfig": "config.yaml"
  }
}

2. Declarative Config (config.yaml)

This file contains the core instructions and tools available. Notice that Antigravity CLI uses updated tool names (e.g., read_file becomes view_file).

custom_agent:
  system_prompt_sections:
    - title: "Role and Core Principles"
      content: |
        You are a Senior Frontend Specialist Your goal is to...<instructions>
  tool_names:
    - view_file         # Migrated from read_file
    - grep_search       # Identical
    - find_by_name      # Migrated from glob
    - list_dir          # Migrated from list_directory
    - read_url_content  # Migrated from web_fetch
    - search_web        # Migrated from google_web_search

  # Append standard CLI context sections for smooth execution
  system_prompt_config:
    include_sections:
      - user_information
      - messaging
      - artifacts

Notable Tool Mappings During Migration

When migrating your tool lists from Gemini CLI to Antigravity CLI, ensure you update them to match the new tool names:

Gemini CLI Tool	Antigravity CLI Equivalent	Description
read_file	view_file	Reads local file contents.
grep_search	grep_search	Pattern searching within files.
glob	find_by_name	Directory and file discovery by pattern.
list_directory	list_dir	Lists directory structures.
web_fetch	read_url_content	Fetches raw web page content.
google_web_search	search_web	Performs web searches.

Hooks

Hooks in Antigravity CLI serve the same core purpose as in Gemini CLI, allowing you to intercept the agentic loop to customize it to your liking and inject context, block tools, have the agent continue, etc.

Migrating from Gemini CLI involves moving to a standalone configuration file, adopting a simplified event model, and utilizing the interactive /hooks command.

Feature	Gemini CLI	Antigravity CLI
Global Location	~/.gemini/settings.json	~/.gemini/antigravity-cli/hooks.json
Workspace Location	.gemini/settings.json	.agents/hooks.json
Config Format	Embedded in settings.json	Standalone hooks.json
Top-Level Grouping	By Event Type (BeforeTool)	By Hook Name (my-hook-suite)
Timeout Units	Milliseconds (e.g., 5000)	Seconds (e.g., 5)
CLI Management	/hooks	/hooks

Supported Hook Events

Here are the supported hook event types in Antigravity and their Gemini CLI equivalent:

Antigravity CLI Event	Gemini CLI Equivalent	Lifecycle Timing & Behavior
PreToolUse	BeforeTool	Executes before a tool call.
PostToolUse	AfterTool	Executes after a tool call completes.
PreInvocation	BeforeModel	Executes before every model call.
PostInvocation	AfterModel	Executes after every model call .
Stop	AfterAgent	Executes when the agent finishes.

Note: Antigravity CLI currently supports fewer hook types than Gemini CLI.

If you are migrating custom hook scripts, update them to match Antigravity's updated JSON contract:

1. Input Naming: Payloads use camelCase (e.g., toolCall.name, toolCall.args) instead of snake_case.
2. Output Flags (PreToolUse): To block a tool, output {"allowTool": false, "denyReason": "..."} instead of {"decision": "deny", "reason": "..."}.

Interactive Management (/hooks)

Rather than manually authoring JSON files and managing syntax formatting, Antigravity CLI provides a built-in interactive terminal interface to view, create, and manage hooks through the /hooks command.

1. Open the Panel: Type /hooks into your prompt and press Enter.
2. Browse Events: Use the arrow keys to navigate through the available hook events (PreToolUse, PreInvocation, etc.).
3. Create & Edit: Select an event to add a new regex matcher, assign shell commands, and set timeout limits directly within the UI dialog.
4. Toggle State: Press e on any configured hook to instantly toggle it enabled or disabled without losing your configuration data.
5. Save & Apply: Changes made in the dialog are automatically validated and saved back to your hooks.json file.

Migration FAQs

Q: Will AGY CLI work in headless mode?
A: Yes, just run agy -p “Your awesome prompt”

Q: Will my chat history be migrated? How will my user context be preserved? A: No, Gemini CLI chat sessions and history will not be migrated.

Q: Will the policies I installed in Gemini CLI be migrated to AGY CLI?
A: No, Antigravity does not use the same policy engine as Gemini CLI. It uses its own permissions system which lets you set tools and commands as allow|deny|ask in your Antigravity CLI settings.json file.