---
name: antigravity-cli
description: Operate the Antigravity CLI `agy` from Codex as a subagent-style helper. Use when Codex needs to install, verify, debug, or drive Antigravity CLI; run `agy --print` one-shot prompts for independent analysis; manage plugins, auth, permissions, sandbox settings, conversations, logs, or interactive `agy` sessions.
---

# Antigravity CLI

Use this skill to operate the Antigravity CLI, invoked as `agy`, from Codex. Treat `agy` as a separate agent process: give it a bounded prompt, run it in the target workspace, capture its output, and reconcile the result yourself before acting on it.

## Operating Model

Keep two Antigravity surfaces distinct:

1. Shell wrapper commands: `agy help`, `agy install`, `agy plugin`, `agy update`, `agy changelog`, `agy --print`.
2. In-session slash commands: `/config`, `/permissions`, `/skills`, `/agents`, `/resume`, `/fork`, `/new`, `/logout`, and similar commands inside the TUI only.

`agy help` shows the shell wrapper surface. It does not document every in-session slash command.

## Prerequisites

Verify the binary before relying on the skill:

```bash
command -v agy
agy --version
```

Antigravity manages its own authentication through its local app state, OS keyring, and browser sign-in flow. Do not ask the user for API keys unless a specific `agy` error says they are required.

## Subagent One-Shots

Prefer non-interactive one-shots when asking Antigravity for an independent pass:

```bash
agy --print "Review this repository for the highest-risk bug. Return file paths and concise reasoning."
agy --print-timeout 10m --print "Summarize the architecture and list open questions."
agy --add-dir /path/to/extra/context --print "Compare the workspace with the added context and report mismatches."
```

Run from the target repository or pass an explicit `workdir` to Codex's terminal tool. Keep prompts bounded and concrete. Ask `agy` for evidence such as paths, commands, or excerpts, then verify important claims yourself before editing files or reporting findings.

Good subagent prompts:

```text
Review only the diff in this repo. Return bugs or regressions with file:line references. Do not rewrite code.
```

```text
Inspect the current workspace and propose one minimal implementation plan for the failing test. Do not edit files.
```

Avoid open-ended delegation such as "fix everything". Codex remains responsible for final decisions, edits, and validation.

## Interactive Sessions

Use an interactive PTY only when slash commands, login flows, conversation resume, or multi-turn behavior are required.

Start a session through Codex's terminal tool with `tty=true`:

```bash
agy
```

For long-running or inspectable sessions, use `tmux` so output can be captured after interruptions:

```bash
tmux new -As agy-codex
agy
```

Inside the TUI, use slash commands only after the session is running:

- Conversation control: `/resume`, `/switch`, `/rewind`, `/undo`, `/rename <name>`, `/clear`, `/fork`, `/reset`, `/new`
- Settings and tools: `/config`, `/settings`, `/permissions`, `/model`, `/keybindings`, `/statusline`, `/tasks`, `/skills`, `/mcp`, `/open <path>`, `/usage`, `/logout`, `/agents`
- Prompt helpers: `@` path autocomplete, `!` terminal command, `?` help, double `Esc` to clear input when not streaming

## Core Commands

Wrapper commands:

```bash
agy changelog
agy help
agy install
agy plugin --help
agy plugin list
agy update
agy --version
```

Useful flags:

- `--add-dir`
- `--continue` / `-c`
- `--conversation`
- `--dangerously-skip-permissions`
- `--log-file`
- `--model`
- `--new-project`
- `--print` / `-p`
- `--print-timeout`
- `--project`
- `--prompt`
- `--prompt-interactive` / `-i`
- `--sandbox`

Plugin subcommands from `agy plugin --help`:

- `list`
- `import [source]`
- `install <target>`
- `uninstall <name>`
- `enable <name>`
- `disable <name>`
- `validate [path]`
- `link <mp> <target>`
- `help`

Install flags from `agy install --help`:

- `--dir`
- `--skip-aliases`
- `--skip-path`

## Files and State

Inspect these with Codex file-reading commands such as `sed`, `rg`, `find`, or direct shell reads. Avoid editing Antigravity state files unless the user explicitly asks or the file format and intended change are clear.

- App data: `~/.gemini/antigravity-cli/`
- Settings: `~/.gemini/antigravity-cli/settings.json`
- Keybindings: `~/.gemini/antigravity-cli/keybindings.json`
- Logs: `~/.gemini/antigravity-cli/log/cli-*.log`
- Conversations: `~/.gemini/antigravity-cli/conversations/`
- Brain artifacts: `~/.gemini/antigravity-cli/brain/`
- History: `~/.gemini/antigravity-cli/history.jsonl`
- Plugin staging: `~/.gemini/antigravity-cli/plugins/<plugin_name>/`

Common settings keys:

- `allowNonWorkspaceAccess`
- `colorScheme`
- `permissions.allow`
- `trustedWorkspaces`
- `enableTerminalSandbox`

Permission modes:

- `request-review`
- `always-proceed`
- `strict`
- `proceed-in-sandbox`

Launch-time flags such as `--sandbox` and `--dangerously-skip-permissions` can override persistent settings for the current session.

## Authentication

Antigravity tries the OS secure keyring first. If no saved session exists, it falls back to browser-based Google sign-in. On a local desktop it may open the default browser; over SSH it may print an authorization URL and expect a code pasted back into the terminal. Use `/logout` inside an interactive session to remove saved credentials.

## Troubleshooting

Check the basics first:

```bash
command -v agy
agy --version
agy help
agy plugin list
```

Then inspect recent logs:

```bash
ls -t ~/.gemini/antigravity-cli/log/cli-*.log | head
sed -n '1,220p' "$(ls -t ~/.gemini/antigravity-cli/log/cli-*.log | head -n 1)"
```

Important pitfalls:

- `agy --version` is the safe version check. `agy version` can enter interactive behavior and fail without a real TTY.
- `agy plugin list` returning no plugins can be a valid empty state.
- `~/.gemini/antigravity-cli/bin/agentapi` is a wrapper to `agy agentapi`.
- On WSL, token storage may be file-based; auth problems can be local file or session-state issues.
- Workspace identity can depend on the launch directory and the `.antigravitycli` project marker.

## Verification Checklist

After creating or changing Antigravity setup, run the smallest applicable checks:

```bash
command -v agy
agy --version
agy help
agy plugin list
test -f ~/.gemini/antigravity-cli/settings.json && sed -n '1,220p' ~/.gemini/antigravity-cli/settings.json
```

For subagent usage, run a harmless smoke test from a scratch or target workspace:

```bash
agy --print "Reply with one sentence confirming the current working directory and no file edits."
```