# Use Antigravity CLI with crystl

> Install Google's Antigravity CLI (agy), sign in, launch it in a crystl shard, and see what crystl can and cannot do with it, including why its approvals stay in its own terminal.

Antigravity CLI is Google's terminal coding agent and the successor to Gemini CLI. Its binary is called **`agy`**, not `antigravity`, which is worth knowing before you go looking for it.

crystl reads its conversations, reports its turn ends, and resumes it. The one thing it does not do is intercept its approvals. That is covered below and it is the difference most worth understanding before you leave one running.

## 1. Install Antigravity CLI

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

The installer drops the binary at `~/.local/bin/agy` and adds that directory to your shell profile's `PATH`. Pass `--skip-path` if you would rather do the `PATH` part yourself.

## 2. Sign in

```bash
agy
```

It looks for a saved session in your Apple Keychain first, and opens a browser to sign in if it does not find one.

You can use a Gemini API key instead: set `modelProvider` to `gemini` in `~/.gemini/antigravity-cli/settings.json` and export `GEMINI_API_KEY`.

## 3. Check it runs on its own

```bash
agy --version
```

If your shell says `agy: command not found` after installing, the `PATH` line went into a profile your shell does not read. Add it to `~/.zshrc` and open a new terminal.

## 4. Launch it in crystl

Type it in a shard:

```bash
agy
```

or spawn one:

```bash
crystl shard create --gem myapp --agent antigravity --prompt "audit the error handling"
```

crystl passes an opening task with `-i`, which is the flag `agy` takes for an initial message.

## What crystl can do with it

- **Turn ends are reported.** `crystl shards` shows `✓ declared done` or `❓ asked a question` rather than a flat `idle`, and [vigil](/docs/vigil/) and `crystl wait done` read that signal.
- **Conversations are readable and resumable.** Transcripts land in [history search](/docs/conversation-history/) and the chat dock, and resuming runs `agy --conversation <id>`.

## What it does not do

**Approvals stay in Antigravity's own terminal.** crystl does not intercept them, whatever your [auto-approval mode](/docs/approval-modes/) says. Answer them in the shard. This is the one to plan around: a mode you set expecting unattended work does not apply to this agent, and an `agy` shard left alone can sit waiting on its own prompt.

**Session ids arrive late.** crystl reads Antigravity's conversation id from its transcript when a shard closes, rather than from a hook at session start. Everything still works; the id just is not known as early as it is for Claude Code and Codex.

## Settings

The **antigravity** tab under settings, **agents** enables it and shows whether crystl's hook entries are installed.

Read the scope note on that page before enabling it. Antigravity's hook config is **global to your machine**, not per project, so crystl's entries are written once and apply to every `agy` session. crystl's hook exits immediately when a session is not a crystl shard, so other sessions are unaffected in practice, but the file is still installed globally.

## Model sizes

Antigravity takes a model with `--model`. Run `agy models` to list the slugs it accepts, and paste a slug rather than a display label. The default crystl uses is `gemini-3.1-pro-high`.

```bash
crystl agent profile set --agent antigravity --small gemini-3.5-flash-high --standard gemini-3.1-pro-low --large gemini-3.1-pro-high
```

There is no `gemini-3.1-pro-medium`. Pro ships high and low only, which trips people up when filling in three sizes. See [model sizes](/docs/model-sizes/).

## Troubleshooting

**`agy: command not found` in a shard.** The installer writes its `PATH` line under bash conventions. macOS uses zsh, so add `~/.local/bin` to `~/.zshrc` and open a new shard.

**A shard is quiet and nothing is waiting in crystl.** Look in the terminal itself. Its approvals never leave it.

## Other agent setup

- [Use Claude Code with crystl](/docs/agent-claude-code/)
- [Use Codex with crystl](/docs/agent-codex/)
- [Use Kimi Code with crystl](/docs/agent-kimi/)
- [Open models](/docs/open-models/) to run any of them on your own hardware

---
Source: https://crystl.dev/docs/agent-antigravity/