byre/docs/antigravity-protocol.md

# Antigravity CLI protocol

How `internal/antigravity` drives the Antigravity CLI, `agy` (`brew install --cask antigravity-cli`; `agy --version` prints the version, `agy changelog` the release notes, and `agy --help` the flags). The CLI is signed in once, interactively, by running `agy` with no arguments as the user byre runs as; `agy models` lists the models that login offers, and fails with "Please sign in" until then. The CLI updates itself.

## Launch

```
agy --input-format stream-json --output-format stream-json \
  --dangerously-skip-permissions --add-dir <session dir> \
  [--model M] [--conversation ID] --print ""
```

- `--print ""` puts the CLI in print mode; with `--input-format stream-json` it reads one message per line from stdin and runs a turn for each, in one conversation, until stdin closes. A bare `-p` takes the next flag as its prompt, so the empty prompt is passed explicitly.
- `--dangerously-skip-permissions` sets the permission mode to `always-proceed`; without it the mode is `request-review` and tool calls wait for approvals print mode can't give.
- `--conversation ID` resumes a conversation with its history; the model comes from `--model`, not from the conversation.
- Runs in the session's working directory, with `GIT_AUTHOR_*`/`GIT_COMMITTER_*` set to the commit identity and anything in `Options.Env`. Commands the agent runs (`run_command`) inherit the environment.

## The session directory

There is no flag for a system prompt or MCP servers, so byre hands them over as a plugin. Each session has its own directory (`Options.Dir`, `antigravity/<session-id>` under the data directory), passed as `--add-dir`. The CLI treats it as a second workspace and loads the plugin in its `.agents/plugins/byre/`:

- `plugin.json`: `{"name": "byre"}`.
- `rules/AGENTS.md`: byre's guidance (`Options.Guidance`), always on. `rules/notes.md` holds the notes (`Options.Notes`) behind `trigger: always_on` frontmatter. The CLI cuts each rule file at 24,000 bytes, so `Start` refuses guidance or notes longer than that.
- `mcp_config.json`: one entry per server. Each `mcp.Server` in `Options.MCPServers` is a Streamable HTTP `url` on the session's listener (below); each `Options.StdioMCP` entry a `command` and `args`. The CLI namespaces plugin servers as `<plugin>_<server>`, so byre's own server is `byre_byre`.
- `hooks.json`: one flat handler per entry in `Options.Hooks`, keyed by hook event, each a `curl` that posts the hook's stdin to the session's listener and prints the reply. Only flat events (`SessionStart`, `PreInvocation`, `PostInvocation`, `Stop`) fit this shape.

Attached images are written under `images/` in the same directory. The directory is removed when the session ends.

## The session's listener

`Start` listens on `127.0.0.1` on a port the OS picks. Every path starts with a random token made per session (`crypto/rand.Text`), written only into the plugin's `mcp_config.json` and `hooks.json`, so a page in a browser or another local process that can reach the port can't call byre's tools without reading those files; any other path is a 404. It serves:

- `POST /<token>/mcp/<server>`: Streamable HTTP MCP for that `mcp.Server`. A request is answered with its JSON-RPC response as `application/json`; a notification gets `202 Accepted`. There is no SSE stream.
- `POST /<token>/hook/<event>`: runs the `Options.Hooks` function for the event on the posted hook input and answers its output as JSON. A failed hook is logged and answers `{}`.

The CLI loads MCP tool schemas lazily. The model reads a tool's schema from `~/.gemini/antigravity-cli/mcp/<server>/<tool>.json` with `view_file`, then calls it through the built-in `call_mcp_tool` tool with `ServerName`, `ToolName` and `Arguments`.

## Messages

User turn, written to stdin: `{"event":"user","message":{"role":"user","content":[{"type":"text","text":"..."}]}}`. `content` may also be a plain string. Only `text` blocks are accepted: an `image` block fails the line with `stream input content block type "image" is not supported`, so byre saves each image to a file and adds a text block naming its path. With `Options.Reminder` set, every message starts with a text block holding it inside `<system-reminder>` tags. A line without `event` or with `event` other than `user` fails or is ignored; `control_request` is "not supported yet", so there is no control channel.

Stdout, one JSON object per line, each `{"event": E, E: {...}}`:

- `init` arrives at launch, before any input, with `conversation_id`, `model`, `cwd`, the built-in `tools` and `permission_mode`. `Start` waits for it and takes the conversation id from it.
- `step_update`: one step of the conversation, by `step_index`, with `state` (`ACTIVE` while it runs, then `DONE`) and `step_type`:
  - `user_input`: a user message, including one a hook injected.
  - `agent_response`: model output. `text_delta` streams its text across `ACTIVE` updates; the `DONE` update carries `duration_seconds` and `usage` (`input_tokens`, `output_tokens`, `thinking_tokens`, `cache_read_tokens`, `total_tokens`). A response that only calls tools has no text. Thinking is counted but never streamed.
  - `tool`: a tool call, `tool_name` and `tool_info` (`name`, `parameters`, and on `DONE` `output`). A shell command is `run_command` with `CommandLine`.
  - `system_message`: a system note, such as the one after a resume.
- `result` ends a turn: `status` (`SUCCESS` or `ERROR`), `response` (the turn's last text), `error`, `duration_seconds`, `num_turns` and `usage` totals for the whole conversation, earlier processes included.

Lines that aren't a JSON object, don't parse, or carry an `event` outside `init`, `step_update` and `result` go to `Options.OnBadLine`; lines that parse are still delivered as events.

## Interrupts and model switches

SIGINT ends the running turn: the CLI prints `error: interrupted` on stderr, sends a `result` with `status` `ERROR` and `error` `interrupted`, and exits. A tool step cut off this way gets no `DONE` update. `Session.Interrupt` sends SIGINT and starts a new process on the same conversation (`--conversation`) once the old one exits, so the session stays usable.

There is no way to switch the model of a running process, so `Session.SetModel` closes the idle process's stdin, waits for it to exit, and starts a new one with the new `--model` on the same conversation.

A process that exits when byre didn't ask it to ends the session: `Events` closes, and the listener and session directory go away.

## Hooks

Hook input and output are camelCase JSON. byre uses `PreInvocation`, which runs before every model call with `invocationNum` (0 for a turn's first call) and `initialNumSteps`; an output of `{"injectSteps":[{"userMessage":"..."}]}` adds a user message the model reads on that call. The `Stop` hook gets no final message, so byre doesn't use it.

## Forking

The CLI can't fork a conversation at a given point, so Antigravity sessions can't be forked.