Overview & Architecture

---
title: Overview & Architecture
description: A beginner-friendly introduction to Google Antigravity CLI (agy), architecture, and filesystem locations.
sidebar:
  order: 1
---

Google Antigravity CLI (`agy`) is a high-performance **Terminal User Interface (TUI)** designed for pair-programming with AI models and orchestrating teams of autonomous agents.

If you have used command-line tools before, you know most of them either dump text line-by-line or run complex graphical windows. A **Terminal User Interface (TUI)** lives in the sweet spot: it runs completely inside your terminal (like Konsole, iTerm, or Alacritty) with interactive panels, status lines, and shortcuts, without requiring an external browser or heavy desktop app.

---

## Core Characteristics

* **Binary**: `agy` (compiled native Go executable, fast startup, zero Node.js/Python runtime overhead).
* **Target Audience**: Integrates natively with Google consumer and professional subscriptions (Google One, Gemini Advanced) via OAuth.
* **Open Source vs. CLI**: Unlike `@google/gemini-cli` (an open-source TypeScript tool on npm focused on developer API keys), `agy` is Google's agent platform built for subagents, asynchronous workflows, and persistent multi-turn sessions.

---

## Filesystem Layout

Antigravity keeps all your preferences, session transcripts, and authorization keys organized:

| Path | Purpose |
| :--- | :--- |
| `~/.gemini/antigravity-cli/` | Main application data directory. |
| `~/.gemini/antigravity-cli/settings.json` | Active CLI configuration (statusline, permissions, models). |
| `~/.gemini/antigravity-cli/conversations/` | Stored session history and turn transcripts. |
| `~/.gemini/GEMINI.md` | Default machine-wide global rules. |
| `~/.mcp-auth/` | Stored OAuth credentials for Model Context Protocol servers. |

---

## Daily Workflow Flags

Start or resume CLI sessions with standard flags:

```bash
# Start an interactive session in the current directory
agy

# Continue your most recent conversation
agy -c

# Resume a specific previous conversation by ID
agy --conversation <CONVERSATION_ID>

# Start a session in a specific workspace directory
agy --add-dir /path/to/another/repo

# Non-interactive single prompt execution (pipes / CI scripts)
agy -p "Review this git diff and summarize changes"
```

Google Antigravity CLI (agy) is a high-performance Terminal User Interface (TUI) designed for pair-programming with AI models and orchestrating teams of autonomous agents.

If you have used command-line tools before, you know most of them either dump text line-by-line or run complex graphical windows. A Terminal User Interface (TUI) lives in the sweet spot: it runs completely inside your terminal (like Konsole, iTerm, or Alacritty) with interactive panels, status lines, and shortcuts, without requiring an external browser or heavy desktop app.

Core Characteristics

Binary: agy (compiled native Go executable, fast startup, zero Node.js/Python runtime overhead).
Target Audience: Integrates natively with Google consumer and professional subscriptions (Google One, Gemini Advanced) via OAuth.
Open Source vs. CLI: Unlike @google/gemini-cli (an open-source TypeScript tool on npm focused on developer API keys), agy is Google’s agent platform built for subagents, asynchronous workflows, and persistent multi-turn sessions.

Filesystem Layout

Antigravity keeps all your preferences, session transcripts, and authorization keys organized:

Path	Purpose
`~/.gemini/antigravity-cli/`	Main application data directory.
`~/.gemini/antigravity-cli/settings.json`	Active CLI configuration (statusline, permissions, models).
`~/.gemini/antigravity-cli/conversations/`	Stored session history and turn transcripts.
`~/.gemini/GEMINI.md`	Default machine-wide global rules.
`~/.mcp-auth/`	Stored OAuth credentials for Model Context Protocol servers.

Daily Workflow Flags

Start or resume CLI sessions with standard flags:

# Start an interactive session in the current directory
agy

# Continue your most recent conversation
agy -c

# Resume a specific previous conversation by ID
agy --conversation <CONVERSATION_ID>

# Start a session in a specific workspace directory
agy --add-dir /path/to/another/repo

# Non-interactive single prompt execution (pipes / CI scripts)
agy -p "Review this git diff and summarize changes"