Skip to main content
How-To Guides Last updated: 16 November 2026

Use Antigravity CLI

Nathan Schram
By Founder, Little Bear Apps

Antigravity CLI (agy) is Google’s successor to Gemini CLI. From v0.36.1 Untether runs it as its own antigravity engine: send a task from Telegram, watch the progress, and resume the conversation later from chat or a terminal.

It suits you if you want Google’s Gemini models (and the Claude and GPT models some Antigravity plans include) next to your other engines. You choose what the agent may do with a permission mode: by default (Workspace) it edits files in the project and runs no commands. Plan first gives you a plan to approve before anything changes, and Ask me sends an Approve / Deny card to Telegram before each shell command or other risky tool.

Antigravity CLI is a separate engine from the deprecated Gemini CLI (gemini): it has its own engine id, sign-in, flags and sessions, and a Gemini CLI setup doesn’t carry over.

At a glance

Antigravity in Untether
Progress, resume line, /continue, voice notes, model and effortYes
Permission modesWorkspace (default), Plan first, Ask me, Full access. Full access applies only when you choose it (in /config, [antigravity] permission_mode or a cron’s own setting)
Approval buttons (Ask me), question buttons, /steerYes, with Untether’s agy plugin installed on the host
/usageagy’s quota groups and AI credits, at no token cost
/compactYes: agy’s own compaction of the chat’s conversation (agy 1.3.5 or newer). No other agy slash command is passed through
CostTokens only, no dollar figure, so [cost_budget] never trips
Live sessionsNo: each message is its own agy run

Before you start

You need:

  • agy 1.3.1 or newer on the machine that runs Untether (tested on 1.4.10). An older agy is refused before anything starts. agy updates itself; agy update forces it.
  • agy signed in on that machine. Untether never signs in for you.
  • A project for the chat. Antigravity edits files where it runs, so Untether won’t run it in a chat with no project bound.
  • Optional: Untether’s agy plugin, for approval buttons (Ask me), question buttons and /steer. Install it on the host with untether agy-gate install once agy is signed in; see Telegram questions and steer.

Install agy

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

The installer puts agy in ~/.local/bin. Untether looks for agy on the PATH it runs with, then at ~/.local/bin/agy, so a systemd or launchd service whose PATH leaves that folder out still finds it. For an agy installed anywhere else, set [antigravity] cmd to its path (see Configuration). The startup message’s “installed engines” line shows whether it was found; if it lists antigravity under not installed, see Antigravity shows as not installed.

Sign in

Google’s terms and Google account sign-ins

Google’s Antigravity terms don’t allow third-party tools to use a Google account sign-in, and Google may suspend the account. Untether runs Google’s own agy binary and never reads your Google credentials, but it is still third-party software driving the CLI.

We recommend a Gemini API key or a Gemini Enterprise sign-in. If you use a Google account sign-in anyway, you accept that risk for that account. Read the full note in Switch engines first. This isn’t legal advice.

Pick one sign-in route:

RouteWhat to set
Gemini API key (recommended)"modelProvider": "gemini" in ~/.gemini/antigravity-cli/settings.json and GEMINI_API_KEY in Untether’s environment. You need both. Google bills this per token
Gemini Enterprise / Google Cloud (recommended)AGY_ADC_AUTH=true, GOOGLE_CLOUD_QUOTA_PROJECT and GOOGLE_CLOUD_LOCATION in Untether’s environment, with Application Default Credentials on the host
Google accountRun agy once in a terminal on the host and finish the sign-in. Chats on this route get a one-time notice about Google’s terms on their first Antigravity answer

“Untether’s environment” means the service’s, not your shell’s: on a systemd install put the variables in ~/.untether/.env (see Systemd service). The steps for each route are in Switch engines, and the detail (keyrings, environment allowlist, proxies) is in the runner reference.

Select the engine

/antigravity list the TODO comments in this repo
/agent set antigravity
  • /antigravity <prompt> uses Antigravity for one message.
  • /agent set antigravity makes it the default for the chat (or the topic, inside a forum topic).
  • A project can default to it with default_engine = "antigravity"; see Projects.

If the chat has no project, bind one first with /ctx set <project>. Antigravity never runs in the home directory, / or Untether’s own directory.

Your first run

Send a task. The progress message is edited in place while agy works:

Untether

working · antigravity · 9s · step 2

✓ Read README.md
✓ Edit docs/notes.md

When agy finishes, the final message carries the answer, a footer and the resume line:

Untether

done · antigravity · 21s · step 3

Added a “Getting started” section to docs/notes.md.

🏷 dir: my-project | workspace
🔢 21.4s · 16.8k/1.0k

↩️ agy --conversation 6f1c2a9e-…

  • The footer shows the project and the permission mode (plus the model and effort once you set them), and this run’s duration and tokens. Antigravity reports tokens, not dollars, so there is no cost figure.
  • The resume line is what you copy into a terminal to carry on there.
  • To continue in Telegram, just send another message in chat mode, or reply to the message. /continue picks up the most recent conversation run from this project’s own directory, including one you started in a terminal there. It never picks up a conversation from a parent or child folder: if this folder has none, Untether says so and starts nothing. See Cross-environment resume.

agy sends one answer per run. If it started a background command or a timer, it holds the answer until that finishes (up to 30 minutes) and the progress message shows ⏳ Antigravity is waiting for 1 background task …. That isn’t a stall.

Background work. Commands still running in the background, timers and subagents are listed in a ⏳ background (N) block in the progress message, one row each with its elapsed time, and /ping counts them. In practice the rows appear in Full access, because Workspace has no shell, timer or subagent tool. A command that agy starts as a daemon (a dev server, say) can keep running after the answer; Untether doesn’t reliably stop it, so check for it and stop it yourself when you’re done. Details: Background tasks and subagents.

An answer held for background work. Nothing of the held answer shows until the background work has finished, so the block ends with agy sends its answer when this work finishes (up to 30 min). If you /cancel during that wait, agy doesn’t hand over the answer it was holding; the cancelled message says so. The conversation keeps it, though: send a message such as “repeat your last answer” to see it.

After /cancel. The output of a turn you cancelled can appear at the start of agy’s next reply in the same conversation. That is how agy behaves (seen on agy 1.3.3), not something Untether adds; send /new if you want a clean start.

Permission modes

Pick the chat’s mode in /config → Permission mode (or /planmode on / off for Plan first). Workspace, Plan first and Full access decide up front what agy may do; Ask me asks you in Telegram while the run works, through Untether’s own agy plugin. A chat that hasn’t picked a mode runs in Workspace (or the [antigravity] permission_mode default): Untether never passes agy’s --dangerously-skip-permissions unless you chose Full access, or Ask me with its plugin ready.

ModeWhat Antigravity can do
Workspace (default)Read, create and edit files in the project. No shell, web, MCP or subagent tools
Full accessEverything: every tool is approved, including shell commands, network access and files outside the project
Plan firstRead the project and write a plan, changing nothing. You get ✅ Approve Plan / ❌ Deny / 💬 Let’s discuss; Approve carries the plan out in Workspace mode. Also /planmode on / off (how it works)
Ask meRead and edit files inside the project on its own; ask you in Telegram, with the command or a diff, before shell commands, web, MCP, subagents, timers and files outside the project. Needs Untether’s agy plugin on the host (more below)

After switching to Full access or Ask me, send /new

agy keeps a conversation on the tools it started with. A conversation that began in Workspace (or Plan first) keeps its no-shell tools after you switch the chat to Full access or Ask me, even though the footer says full access / ask me — so in Ask me it has no shell to ask you about.

Send /new, then your message. The new mode applies from the next new conversation. The /config toast says the same: Permission mode: ask me — send /new if you're switching from Workspace or Plan first (not from Full access).

Switching back to Workspace needs /new too. A conversation that began in Full access keeps its shell tool after you switch to Workspace. When it reaches for the shell, Workspace blocks it and the turn ends on a ⚠️ notice that says to send /new (or pick Full access again). The same goes for Ask me → Workspace and for either → Plan first. The toasts say so: Permission mode: workspace — send /new if you're switching from Full access or Ask me (not from Plan first) (and the same for plan first), and Clear override says Permission mode: cleared — send /new if this switched between Workspace / Plan first and Ask me / Full access. Moving between Workspace and Plan first, or between Ask me and Full access, needs no /new: each pair uses the same tools.

To set a default for every Antigravity chat, use permission_mode under [antigravity] (see Configuration). A chat’s own /config choice wins over it.

Ask me

Ask me (#980) is Antigravity’s equivalent of Claude Code’s approval buttons. agy runs with all its tools, and Untether’s agy plugin holds each tool call until Untether answers:

  • Runs on its own: reading, listing and searching files inside the project; creating and editing files there (and agy’s own notes for the conversation).
  • Asks you first: reading files outside the project, shell commands, web fetches and searches, MCP tools, browser actions, subagents, timers, files outside the project, and protected files inside it at any depth (.agents/, .git/, .claude/, .codex/, .opencode/, .vscode/, .github/workflows/, .husky/, .env files, .envrc, keys, CLAUDE.md, AGENTS.md and similar files other tools run or read as instructions). A nested checkout (a folder with its own .git, such as a submodule) and Untether’s own @branch worktrees in .worktrees/ count as outside the project. So does any tool agy adds that Untether doesn’t know yet, and a search whose text starts with -.

The card shows what would run: $ git status with its folder for a shell command (and a warning when it would start a daemon that keeps running after the turn), the lines added and removed for an edit, each subagent’s task for a subagent, and every argument of any other tool in full — the tool’s own first (a web page’s address), with ⚠️ on anything agy’s tool doesn’t have, on a value hidden because its name looks like a secret, and on anything too long to show whole. agy’s own one-line description comes last as agy says: …. Tap ✅ Approve or ❌ Deny; for a shell command, ✅ Always allow this command here lets that exact command (in that folder) run without asking for the rest of the conversation. A Deny, or no answer within 15 minutes, blocks the tool and agy is told not to retry it; the row reads blocked: denied in Telegram. A subagent’s own tool calls ask too, labelled with the subagent’s role.

/config → Diff preview works here as it does for Claude Code (#1090), and only matters in Ask me: on makes edits inside the project ask too, with the diff; off leaves the diff off the cards (an edit card still names the file, and commands always show). Left unset, in-project edits run on their own and the cards that do appear show the diff.

Ask me needs Untether’s agy plugin on the host. Until it is installed, the button reads 🔒 Ask me — set up and opens the plugin’s status page. Untether checks the plugin before every Ask me run and refuses the run (nothing starts) when:

  • the plugin isn’t installed, is disabled (agy plugin disable), was edited, or agy doesn’t load it for the project;
  • the project contains Untether’s own code or config (for example a checkout of Untether itself, or the folder holding untether.toml), which agy could edit to switch approvals off;
  • agy loads hooks, plugins, agents or MCP servers there that Untether doesn’t manage (in the project’s .agents/ folder or your own ~/.gemini/config/). They run their own commands without asking, so Ask me can’t promise to ask. An empty mcp_config.json is fine: Untether asks agy (agy mcp list) whether any server is configured.

Workspace and Full access still work in those projects. To shorten the wait for an answer, set approval_timeout_s under [antigravity] (60 s or more, never longer than the plugin’s own wait).

What Workspace can and can’t do

Workspace runs use a no-shell agent that Untether manages. Its tools are file tools, plus ask_question.

In Workspace
Read, search, create and edit files in the projectYes
Run a shell command (tests, git, a build)No. Antigravity says in plain words that this needs Full access; nothing runs
Delete or rename a fileNo. A “rename” is a copy: the new file is written and the original stays
Web fetches, MCP tools, subagentsNo
Files outside the projectBlocked by agy, with a ⚠️ notice
Ask you a questionYes, as buttons with Untether’s agy plugin; without it the question is skipped and agy carries on

When agy blocks something, the progress message shows a ⚠️ Blocked row, the turn stops there, and the reply ends with how to allow it:

Untether

⚠️ Antigravity was blocked from using a file outside the project — headless runs can’t ask for approval, so it stopped there. To allow it: /config → Permission mode → Full access, then /new.

Workspace is not a sandbox

Workspace limits the tools the model has. It doesn’t stop a run writing a file that something else executes later, and it doesn’t stop agy’s own hooks, plugins or project MCP servers (see Project config Untether warns about). Details: Security.

The managed agent file. Untether keeps the no-shell agent at ~/.gemini/config/agents/untether-workspace/agent.md and rewrites it if it changes, so don’t edit it. It does nothing for your own interactive agy unless you pick that agent there.

Projects with their own agy agents or plugins. If the project has an agents, agents.json, plugins or plugins.json entry under .agents/, Untether doesn’t use its agent there, and Workspace runs on agy’s default agent. That agent has a shell tool which agy then blocks, so a shell attempt ends the turn with a ⚠️ Antigravity was blocked from using a shell command… notice. See Troubleshooting.

More detail on modes, allow rules and agy’s own settings: Antigravity CLI — Permission mode.

Telegram questions and steer

With Untether’s agy plugin installed on the host, an Antigravity run can:

  • Ask you a question. When agy calls its ask_question tool, you get the same question card as Claude Code: option buttons, or Other (type reply), or just reply with text. agy carries on with your answer, and the progress row becomes ❓ answered: …. With no answer within 15 minutes, agy is told to use its best judgement. Turn it off per chat with /config → Ask mode.
  • Take a message while it works. With /config → Follow-up set to steer (or /steer <text>), a message you send during a run goes into that run before agy’s next step, and the progress message shows ↪️ steer received: …. If the run ends before agy takes another step, you get ⚠️ The session ended before this message ran — please send it again.

It works in every permission mode; in Workspace, Plan first and Full access nothing about what agy may do changes. Ask me needs it: the plugin is what holds each tool call for your approval. Without the plugin, Antigravity works as before: questions are skipped (agy carries on with its own default), follow-ups queue, and Ask me is refused.

Install it on the host (not from Telegram — it is shared by every agy on that machine):

untether agy-gate install          # via agy's own `agy plugin install`
untether agy-gate status           # what's installed
untether agy-gate status --project ~/my-project   # does agy load it there? (agy -p /hooks, no model turn)
untether agy-gate uninstall

Useful options: install --dry-run prints the files and where they would go without writing anything; install --wait-s <seconds> sets how long a question or approval waits for an answer (900 by default); status --canary also sends one trivial agy turn (about 13k tokens) to check the hooks really reach Untether; --agy <path> points any of them at a particular agy binary (otherwise [antigravity] cmd, then agy on PATH). status exits with status 1 when the plugin isn’t ready.

Install writes only ~/.gemini/config/plugins/untether-gate/ (plugin.json, hooks.json and Untether’s .untether-managed record). Its hooks start with a check for a marker that only Untether-started agy runs carry, so your own agy sessions never run any Untether code. Install and uninstall refuse to touch a plugin folder that Untether didn’t install or that was edited since (--force overrides). No restart is needed: Untether checks the plugin before each run (cached for an hour per project). /config → Permission mode → 🔐 Telegram approvals shows the same status, read-only, with a Re-check button.

Scheduled runs never show a question: cron and webhook runs answer it themselves (“nobody can answer questions… proceed with reasonable defaults”).

If the plugin folder was changed after install, attended runs show a ⚠️ row and run without questions or steer, and scheduled runs are held, because its hooks run their own commands in every agy session on the host. Run untether agy-gate status, then untether agy-gate install --force if you didn’t change it.

After upgrading Untether, run untether agy-gate install again whenever the new version changes the plugin’s files. If you installed the plugin with a 0.36.1 pre-release (rc1 to rc3), this applies to you: the plugin changed in 0.36.1 (its hooks now block a tool themselves when Untether’s Python can’t start). Until you do, untether agy-gate status says plugin version 1 from an earlier Untether, Ask me is refused (“the plugin is from another Untether version — run untether agy-gate install on the host to update it”), attended runs show ⚠️ Untether's agy plugin (untether-gate) is from another Untether version … and run without questions or steer, and scheduled agy runs are held.

Models and effort

  • Model. /model set <id> sets the chat’s model and /model clear goes back to agy’s default. Run agy models on the host for the list of ids (it lists each one with its level as a suffix). An id that ends in its effort (gemini-3.8-flash-medium) fixes the level, and Untether passes no --effort with it. The same id without the suffix (gemini-3.8-flash) lets you pick the level in /config → Effort; with none picked, agy 1.3.4 and newer use the model’s default level (agy 1.3.1 to 1.3.3 refuse to start, and the run stops with That model needs an effort level).
  • Effort. /config → Effort offers Low, Medium and High, narrowed to what the chat’s model accepts. A Gemini Pro id, for example, offers Low and High only, and a fixed-effort model shows no level buttons.

If a saved level isn’t one the model accepts, the run drops it and shows ⚠️ Effort <level> isn't available for <model>, so agy used its default. See Antigravity effort.

Context use. With a model set for the chat, the first line of a progress message and answer can end with ~3% ctx: the tokens the model last read, as a share of the context window Google publishes for that model. It is an estimate. agy doesn’t report a window, and it compacts a conversation on its own schedule without saying so, so a low figure doesn’t mean compaction is far off (/compact compacts on demand). With no model set (agy’s default), or a model Untether has no published figure for, no percentage is shown. Details: Context use.

Compact the conversation

Send /compact to have agy summarise the chat’s conversation and free up its context window. Untether passes it to agy as agy’s own command (it is the only agy slash command that gets through; anything else starting with / still reaches the model as text) and answers 🗜️ Context compacted (manual) when agy reports the compaction. agy doesn’t say how much smaller the context got, so there is no token figure: the ~N% ctx on your next message shows the drop. /compact <message> compacts and then answers the message, under a 🗜️ Context compacted. line.

  • In a new chat, or after /new, there is nothing to compact: Untether replies Nothing to compact: this chat has no Antigravity conversation yet. and starts nothing.
  • Sent while a run is working, /compact waits its turn like any follow-up and runs when that run ends. It is never steered into the running turn, even with /steer mode on.
  • It runs in the chat’s permission mode. Compaction runs no tools, so it asks for no approvals.

Usage and quota

Send /usage in an Antigravity chat to see agy’s quota groups (for example a 5-hour and a weekly limit per model group, each with a bar, the percentage used and the reset time), your remaining AI credits, then the last session’s token totals. Checking costs no tokens.

  • Footers show tokens for the run; there is no dollar cost.
  • A quota line can follow an answer. Turn it on in /config → Cost & usage → Subscription usage to see ⚡ Gemini Models 5h: 12% | wk: 3% after each run; with it off, a line appears only once a limit reaches 70 %. The line is taken from your last /usage, for up to 15 minutes, so it never slows an answer down. Send /usage again for current numbers.
  • /stats auth shows which sign-in route agy is set to use, for up to an hour after an Antigravity run (nothing straight after a restart). It doesn’t start agy or test the sign-in.
  • [cost_budget] limits count dollars, so they never trip for Antigravity.
  • When a quota is used up, the run ends with This Antigravity quota is used up. /usage shows when each group resets, and Untether doesn’t retry. Running out of AI credits ends it with Antigravity's AI credits balance is too low to continue.

Sample output: Cost budgets → Antigravity.

Scheduled runs

Cron and webhook runs work with Antigravity, with these rules that differ from chat:

  • They never inherit Full access or Ask me. A cron gets either only from its own permission_mode ("full" or "ask"). A webhook run never gets either: webhooks have no permission_mode of their own. A chat’s (or untether.toml’s) Full access or Ask me runs a scheduled run as Workspace. A cron with permission_mode = "ask" has nobody to tap Approve: reads and in-project edits run, everything that would ask is denied at once, and the answer ends with a 🔒 unattended … nobody to approve footer. A scheduled run in Plan first (the chat’s mode or the cron’s own) posts the plan and changes nothing, with a 🔒 unattended … denied plan approval footer; set permission_mode = "workspace" on a cron that should make the change.
  • They never show a question card. Cron and webhook runs answer agy’s questions themselves and carry on with reasonable defaults.
  • They are held when the project’s agy config changed since someone last ran Antigravity in that chat (next section). The next message someone sends in the chat runs with the changed config and shows what changed in a ⚠️ row; the schedule runs again after that. An /at or /loop run doesn’t release it. Check the files the message lists first if you didn’t change them. When the change is to Untether’s own agy plugin, the message says so, and only reinstalling it on the host (untether agy-gate install --force) releases the hold.
  • A Workspace run is held while agy’s own tool-permission setting can’t be read. Untether checks it with agy -p /config before the run; if that fails or returns no value, the scheduled run replies Untether couldn't read agy's tool-permission setting before this run … and nothing starts. Nothing needs changing: the next fire checks again. A run you start from the chat goes ahead with a ⚠️ row instead, as long as agy reports the setting when it starts.
[[triggers.crons]]
id = "nightly-notes"
schedule = "0 2 * * *"
chat_id = -1001234567890
project = "myapp"          # Antigravity needs a project
engine = "antigravity"
permission_mode = "full"   # only if this cron needs shell commands
prompt = "Update docs/notes.md from today's commits."

See Schedule tasks and Webhooks and cron.

Project config Untether warns about

agy runs its own hooks, plugins, custom agents and .agents/mcp_config.json MCP servers in every mode, Workspace included, and without a tool call. Untether can’t stop them, so it tells you about them:

  • First run in a project that has such config: a ⚠️ row says the project has agy hooks, plugins or MCP servers that Untether doesn’t manage. Review them if you didn’t add them.
  • A run changed that config (or files other engines act on, such as .claude/, .mcp.json or .github/workflows/): a ⚠️ row after the run asks you to review it before sending another message. Claude Code’s worktrees in .claude/worktrees/ aren’t part of this check: each one is its own checkout.
  • Scheduled runs are held while the config differs from what a run someone started from the chat last showed, or while Untether can’t finish the check. A changed config is released by the next message a person sends in the chat; a check that can’t finish (too many files, or a config file Untether can’t read with certainty) holds them until it succeeds.

This is a tripwire with known limits, not isolation. The limits are listed in the runner reference.

Not supported yet

  • Ask me in a project with agy hooks, plugins, agents or MCP servers that Untether doesn’t manage: Ask me is refused there, and there is no “trust this config” option yet. Workspace and Full access still work.
  • Approval buttons, question buttons and /steer without Untether’s agy plugin on the host.
  • Live sessions: each message is its own agy run (a steer goes into the run that is in flight), so there is no status message after the answer and no 🔔 Background task finished follow-up.
  • Claude Code’s extras: the Pause & Outline Plan button, Loop mode and a notice when the conversation is compacted automatically (agy doesn’t report that; /compact is confirmed).
  • agy’s other slash commands: only /compact is passed through (see Compact the conversation); any other /-leading message reaches the model as text.
  • agy’s own Auto mode (--mode auto, agy 1.3.5): none of the permission modes uses it. Workspace never runs shell commands, and Auto runs the ones it judges safe.
  • Images as image input: a Telegram photo reaches agy as a saved file path.
  • Subagent detail: each subagent gets a row in the ⏳ background block, but its own steps, output and token use aren’t shown, and a subagent that failed looks the same as one that finished.
  • /export after a restart: the export comes from Untether’s own memory of the session, so it is empty once Untether restarts and never includes turns run in a terminal.

The full comparison with other engines is in the engine compatibility matrix.

If something goes wrong

Everything else is under Troubleshooting → Antigravity CLI, and each message is listed in the error reference.

Configuration

All four keys are optional.

untether config

untether config set antigravity.model "gemini-3.8-flash-medium"
untether config set antigravity.permission_mode "workspace"

toml

[antigravity]
model = "gemini-3.8-flash-medium"  # passed to agy as the model; ids from `agy models`
cmd = "~/.local/bin/agy"           # path to agy (default: agy on PATH, then ~/.local/bin/agy)
permission_mode = "workspace"      # workspace (default) | ask | plan | full
approval_timeout_s = 900           # Ask me: how long a card waits (60–3000 s)

permission_mode = "full" makes Full access the default for every Antigravity chat that hasn’t picked a mode. Chats with an existing Workspace conversation still need /new. There is no untether.toml key for the effort level: set it per chat in /config → Effort, or use a model id that names it. Sign-in is configured in agy and the service environment, not here. Full key reference: Config reference.

Was this helpful?

Related Articles