# google-antigravity/antigravity-cli architecture

> Architecture diagram of the GitHub repository google-antigravity/antigravity-cli, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/google-antigravity/antigravity-cli
- Repository: https://github.com/google-antigravity/antigravity-cli

## Overview

#### Purpose and Repository Shape
This repository is a public landing/documentation surface for Antigravity CLI, a terminal-based interface to Antigravity’s shared agent engine. It contains no CLI implementation, package manifest, build system, or runtime source; the product binary is installed remotely and invoked as `agy`. Primary user entry point: `README.md`.

#### Product Entry and Installation Boundary
Users install platform-specific scripts fetched from `antigravity.google`, then launch the externally supplied executable with `agy`. This repository documents, rather than owns, installation and execution:
- `README.md`

The installation scripts, executable distribution, updates, and core application lifecycle are external to this tree.

#### CLI Agent Runtime
The documented CLI runs as a low-overhead terminal/TUI agent for local and remote SSH workflows. Its advertised capabilities—codebase understanding, permissioned edits, command execution, multi-step reasoning, tool calling, and persistent history—belong to the shared Antigravity core agent engine, which is not present here:
- `README.md`

The key control boundary is user permission: the agent may edit files and execute commands only with user authorization.

#### Authentication and Session Flow
At startup or when authentication is needed, the installed CLI uses the system keyring for credentials. If no active session exists, it uses Google Sign-In: browser launch locally, or an authorization URL for SSH sessions. `/logout` clears saved credentials. Enterprise access additionally depends on GCP-project onboarding:
- `README.md`

Keyring storage, OAuth/sign-in implementation, SSH detection, and GCP integration are external services/runtime concerns.

#### Cross-Product Integration
Antigravity CLI and the Antigravity 2.0 GUI share an agent engine and synchronize preferences and permissions. CLI sessions can be exported to the GUI, establishing an interoperability boundary between terminal interaction and GUI-based continuation:
- `README.md`

#### Shell Customization Examples
The only executable artifacts in this repository are user-facing shell examples for integrating CLI state into terminal chrome:
- `examples/statusline/statusline.sh`
- `examples/title/title.sh`

Each example is documented alongside screenshots and is intended as optional shell-level presentation integration, not core CLI runtime behavior:
- `examples/statusline/README.md`
- `examples/title/README.md`

#### External Services and Governance
Material external dependencies are Antigravity’s hosted installer/distribution endpoints, Google authentication, system keyring facilities, optional GCP enterprise configuration, and Antigravity/Google data-governance services. Product, privacy, and risk disclosures are centralized in:
- `README.md`
- `CHANGELOG.md`

Main entry points: [`README.md`](https://github.com/google-antigravity/antigravity-cli/blob/main/README.md) (Product guide), [`examples/statusline/README.md`](https://github.com/google-antigravity/antigravity-cli/blob/main/examples/statusline/README.md) (Statusline guide), [`examples/title/README.md`](https://github.com/google-antigravity/antigravity-cli/blob/main/examples/title/README.md) (Title guide), [`CHANGELOG.md`](https://github.com/google-antigravity/antigravity-cli/blob/main/CHANGELOG.md) (Change log)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_repo["Repository surface"]
  node_readme["Product guide<br/>documentation<br/>[README.md]"]
  node_changelog["Change log<br/>documentation<br/>[CHANGELOG.md]"]
  node_statusline_docs["Statusline guide<br/>example docs<br/>[README.md]"]
  node_statusline_script["Statusline script<br/>shell example<br/>[statusline.sh]"]
  node_title_docs["Title guide<br/>example docs<br/>[README.md]"]
  node_title_script["Title script<br/>shell example<br/>[title.sh]"]
end

subgraph group_runtime["External CLI platform"]
  node_agy["agy executable<br/>external CLI"]
  node_agent_engine{{"Shared agent engine<br/>agent runtime"}}
  node_permission_gate(("User authorization<br/>control boundary"))
end

subgraph group_integrations["External services"]
  node_hosted_installer["Hosted installer<br/>distribution service"]
  node_keyring["System keyring<br/>credential storage"]
  node_google_signin["Google Sign-In<br/>authentication service"]
  node_gui["Antigravity 2.0 GUI<br/>GUI client"]
  node_gcp["GCP enterprise onboarding<br/>enterprise service"]
  node_governance["Google data governance<br/>governance service"]
end

node_readme -->|"documents installation"| node_hosted_installer
node_hosted_installer -->|"installs"| node_agy
node_readme -->|"documents invocation"| node_agy
node_agy -->|"uses"| node_agent_engine
node_agent_engine -->|"requests edit and command approval"| node_permission_gate
node_agy -->|"loads saved session"| node_keyring
node_agy -->|"authenticates when needed"| node_google_signin
node_agy -.->|"uses for enterprise access"| node_gcp
node_agent_engine -->|"shares engine, preferences, and permissions"| node_gui
node_agy -->|"exports sessions"| node_gui
node_readme -->|"links example"| node_statusline_docs
node_statusline_docs -->|"documents"| node_statusline_script
node_readme -->|"links example"| node_title_docs
node_title_docs -->|"documents"| node_title_script
node_readme -.->|"centralizes disclosures"| node_governance
node_changelog -.->|"records disclosures"| node_governance

click node_readme "https://github.com/google-antigravity/antigravity-cli/blob/main/README.md"
click node_changelog "https://github.com/google-antigravity/antigravity-cli/blob/main/CHANGELOG.md"
click node_statusline_docs "https://github.com/google-antigravity/antigravity-cli/blob/main/examples/statusline/README.md"
click node_statusline_script "https://github.com/google-antigravity/antigravity-cli/blob/main/examples/statusline/statusline.sh"
click node_title_docs "https://github.com/google-antigravity/antigravity-cli/blob/main/examples/title/README.md"
click node_title_script "https://github.com/google-antigravity/antigravity-cli/blob/main/examples/title/title.sh"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_readme,node_changelog,node_statusline_docs,node_statusline_script,node_title_docs,node_title_script toneBlue
class node_agy,node_agent_engine,node_permission_gate toneAmber
class node_hosted_installer,node_keyring,node_google_signin,node_gui,node_gcp,node_governance toneMint
```

## Components

### Repository surface

Documentation and optional shell presentation examples.

- [Product guide](https://github.com/google-antigravity/antigravity-cli/blob/main/README.md): documentation · Primary installation, usage, authentication, and governance entry point. · `README.md`
- [Change log](https://github.com/google-antigravity/antigravity-cli/blob/main/CHANGELOG.md): documentation · Product change and disclosure record. · `CHANGELOG.md`
- [Statusline guide](https://github.com/google-antigravity/antigravity-cli/blob/main/examples/statusline/README.md): example docs · `examples/statusline/README.md`
- [Statusline script](https://github.com/google-antigravity/antigravity-cli/blob/main/examples/statusline/statusline.sh): shell example · Optional terminal-chrome integration. · `examples/statusline/statusline.sh`
- [Title guide](https://github.com/google-antigravity/antigravity-cli/blob/main/examples/title/README.md): example docs · `examples/title/README.md`
- [Title script](https://github.com/google-antigravity/antigravity-cli/blob/main/examples/title/title.sh): shell example · Optional terminal-title integration. · `examples/title/title.sh`

### External CLI platform

Installed and operated outside this repository.

- **agy executable**: external CLI · Remotely installed terminal/TUI client.
- **Shared agent engine**: agent runtime · Provides reasoning, tools, edits, commands, and history.
- **User authorization**: control boundary · Gates file edits and command execution.

### External services

- **Hosted installer**: distribution service · Supplies platform-specific installation scripts.
- **System keyring**: credential storage
- **Google Sign-In**: authentication service · Uses browser login locally or an authorization URL over SSH.
- **Antigravity 2.0 GUI**: GUI client · Continues exported CLI sessions.
- **GCP enterprise onboarding**: enterprise service · Required for enterprise access.
- **Google data governance**: governance service

## Connections

- Product guide → Hosted installer: documents installation
- Hosted installer → agy executable: installs
- Product guide → agy executable: documents invocation
- agy executable → Shared agent engine: uses
- Shared agent engine → User authorization: requests edit and command approval
- agy executable → System keyring: loads saved session
- agy executable → Google Sign-In: authenticates when needed
- agy executable → GCP enterprise onboarding: uses for enterprise access
- Shared agent engine → Antigravity 2.0 GUI: shares engine, preferences, and permissions
- agy executable → Antigravity 2.0 GUI: exports sessions
- Product guide → Statusline guide: links example
- Statusline guide → Statusline script: documents
- Product guide → Title guide: links example
- Title guide → Title script: documents
- Product guide → Google data governance: centralizes disclosures
- Change log → Google data governance: records disclosures