Skip to main content
Reference Last updated: 16 November 2026

Antigravity CLI stream-json cheatsheet

Nathan Schram
By Founder, Little Bear Apps

agy --output-format stream-json writes one JSON object per line to stdout. Every line has an event field: init, step_update, result or command_result. The examples below are real lines from agy 1.3.1, 1.3.2 and 1.3.3, with paths and ids shortened and the tool list cut.

Things that differ from what you might expect

  • There is no error event. Failures arrive as a result with status: "ERROR", or as a non-zero exit with text on stderr.
  • init is not always first, or present at all. An early failure (signed out, bad model) sends only a result with an empty conversation_id.
  • result.usage, num_turns and duration_seconds are totals for the whole conversation, including earlier resumed runs.

Input

Untether starts agy with --input-format stream-json and writes one line to stdin, then closes it:

{"event":"user","message":{"content":"your prompt"}}

agy runs one turn per line. With stdin left open it answers each line with its own result and then waits, idle, for the next; closing stdin ends it with exit code 0 (agy 1.3.5; the seam for live sessions, #977). A /compact line, sent without --disable-slash-commands, compacts the conversation: a system_message step and a checkpoint step, then a SUCCESS result with an empty response and no new tokens. Nothing in the stream says how much smaller the context got (agy 1.3.5). Untether passes that flag (and escapes a leading / in Plan first) on every run except a /compact one (#1114):

{"event":"user","message":{"content":"/compact"}}
{"event":"step_update","step_update":{"conversation_id":"153b…","step_index":2,"state":"DONE","step_type":"user_input"}}
{"event":"step_update","step_update":{"conversation_id":"153b…","step_index":3,"state":"DONE","step_type":"system_message","duration_seconds":0.000237673}}
{"event":"step_update","step_update":{"conversation_id":"153b…","step_index":4,"state":"DONE","step_type":"checkpoint","duration_seconds":6.39104973}}
{"event":"result","result":{"conversation_id":"153b…","status":"SUCCESS","response":"","duration_seconds":18.26,"num_turns":2,"usage":{"input_tokens":7803,"output_tokens":27,"thinking_tokens":26,"cache_read_tokens":0,"total_tokens":7830}}}

init

{"event":"init","conversation_id":"90ca6744-e8d4-46d4-b5fc-64a30ae2fa6d","init":{"cwd":"/work/proj","tools":["ask_question","run_command","view_file","…"],"permission_mode":"request-review"}}
  • conversation_id is the resume id (a UUID).
  • init.permission_mode is the policy agy is running under: request-review (default), strict, proceed-in-sandbox or always-proceed (what --dangerously-skip-permissions reports).
  • init.model is present from agy 1.3.2, only when --model was passed: it echoes the flag (for example gemini-3.8-flash-low). With no --model, no line of the stream names the model.
  • init.tools is a long list of tool names; don’t rely on its contents.
  • init.json_schema echoes a --json-schema argument (Untether doesn’t pass one).

step_update

One step is a numbered unit of work. state is ACTIVE, DONE or ERROR. step_type is user_input, agent_response, tool, subagent, system_message, checkpoint, finish or unknown.

Your message:

{"event":"step_update","step_update":{"conversation_id":"90ca…","step_index":0,"state":"DONE","step_type":"user_input"}}

Answer text, streamed as deltas and then closed with per-step usage:

{"event":"step_update","step_update":{"conversation_id":"90ca…","step_index":1,"state":"ACTIVE","step_type":"agent_response","text_delta":"OK"}}
{"event":"step_update","step_update":{"conversation_id":"90ca…","step_index":1,"state":"DONE","step_type":"agent_response","text_delta":"\n","duration_seconds":2.23,"usage":{"input_tokens":13051,"output_tokens":1,"thinking_tokens":0,"cache_read_tokens":0,"total_tokens":13052}}}

A tool call, started and finished:

{"event":"step_update","step_update":{"conversation_id":"a46e…","step_index":2,"state":"ACTIVE","step_type":"tool","tool_name":"view_file","tool_info":{"name":"view_file","parameters":{"AbsolutePath":"/work/proj/notes.txt"}}}}
{"event":"step_update","step_update":{"conversation_id":"a46e…","step_index":2,"state":"DONE","step_type":"tool","tool_name":"view_file","duration_seconds":0.97,"tool_info":{"name":"view_file","parameters":{"AbsolutePath":"/work/proj/notes.txt"},"output":"2 lines, 20 bytes"}}}

tool_info carries name, parameters, and on completion output or error ({"type": …, "message": …}).

Tool names seen: run_command, view_file, write_to_file, replace_file_content, multi_replace_file_content, sed_file, list_dir, find_by_name, grep_search, search_web, read_url_content, call_mcp_tool, browser_*, invoke_subagent, ask_question, schedule, manage_task, finish.

A blocked tool looks like a finished one

When agy’s permission policy blocks a tool (the headless default blocks shell, web and MCP calls), the step still ends DONE, with no output and no error:

{"event":"step_update","step_update":{"conversation_id":"a46e…","step_index":4,"state":"ACTIVE","step_type":"tool","tool_name":"run_command","tool_info":{"name":"run_command","parameters":{"CommandLine":"echo probe-shell"}}}}
{"event":"step_update","step_update":{"conversation_id":"a46e…","step_index":4,"state":"DONE","step_type":"tool","tool_name":"run_command","duration_seconds":0.05,"tool_info":{"name":"run_command","parameters":{"CommandLine":"echo probe-shell"}}}}

Only the result says it was blocked, in denied_actions. agy 1.3.x ends the turn at the first blocked tool, and writes a jetski: no output produced — a tool required the "command" permission … line to stderr.

A tool refused by a hook is different: its step ends ERROR with tool_info.error:

{"event":"step_update","step_update":{"conversation_id":"cb98…","step_index":11,"state":"ERROR","step_type":"tool","tool_name":"run_command","duration_seconds":0.38,"tool_info":{"name":"run_command","parameters":{"CommandLine":"echo denyme"},"error":{"type":"TOOL_ERROR","message":"tool call denied by pre-tool hook: …"}}}}

Subagents

{"event":"step_update","step_update":{"conversation_id":"4054…","step_index":2,"state":"ACTIVE","step_type":"subagent","tool_name":"invoke_subagent","subagent_info":{"subagents":[{"type_name":"research","role":"Secret Reader","initial_prompt":"Read notes.txt and reply with the secret word only."}]}}}

The DONE line adds each subagent’s own conversation_id and a log_uri. The subagent’s steps are not in the parent stream.

That is agy 1.3.1. On 1.3.3 the spawn is a tool step while ACTIVE and becomes a subagent step only at DONE, about 0.3 s later, while the subagents are still working:

{"event":"step_update","step_update":{"conversation_id":"0000…","step_index":2,"state":"ACTIVE","step_type":"tool","tool_name":"invoke_subagent","tool_info":{"name":"invoke_subagent","parameters":{"Subagents":[{"Model":"inherit","Prompt":"Read notes.txt …","Role":"Alpha","TypeName":"research","Workspace":"inherit"},{"Model":"inherit","Prompt":"Read hello.py …","Role":"Beta","TypeName":"research","Workspace":"inherit"}]}}}}
{"event":"step_update","step_update":{"conversation_id":"0000…","step_index":2,"state":"DONE","step_type":"subagent","tool_name":"invoke_subagent","duration_seconds":0.27,"subagent_info":{"subagents":[{"type_name":"research","role":"Alpha","initial_prompt":"…","conversation_id":"…","log_uri":"file://…/transcript.jsonl","workspace_uris":["file:///work/proj"]},{"type_name":"research","role":"Beta","initial_prompt":"…","conversation_id":"…"}]}}}

Each subagent finishing is one system_message step in the parent stream, with nothing to say which one (still so on 1.3.5; the sender is only in agy’s transcript file):

{"event":"step_update","step_update":{"conversation_id":"0000…","step_index":4,"state":"DONE","step_type":"system_message","duration_seconds":0.0004}}

Background commands, timers and daemons

  • A background run_command stays ACTIVE until the command ends, and agy prints nothing else meanwhile (it holds the model’s reply). Its parameters carry only CommandLine; WaitMsBeforeAsync and IsDaemon are not in the stream.
  • A schedule step (parameters: DurationSeconds, Prompt) stays ACTIVE for the timer’s whole life.
  • When either finishes, its DONE line is followed by the held reply and a system_message step. agy prints steps in order, so everything that happened while the step was open (replies, a subagent’s system_message) comes in one burst after its DONE, and the timer’s own notice can come after a subagent’s (1.3.5).
  • A timer the model gives TimerCondition (any, or a sender id) ends at the first matching message. The stream drops TimerCondition from the parameters, but the DONE output names the sender, and that message (the next system_message) is the timer’s only notice (#1086, agy 1.3.5):
{"event":"step_update","step_update":{"step_index":3,"state":"DONE","step_type":"tool","tool_name":"schedule","duration_seconds":7.84,"tool_info":{"name":"schedule","parameters":{"DurationSeconds":60,"Prompt":"Check on the subagents' progress"},"output":"Timer cancelled early: its early-termination condition (any) was met by a message from 0000…0003."}}}

A timer that runs its course ends with "output":"Finished waiting 30 seconds.".

  • manage_subagents takes Action list, kill (with ConversationIds) or kill_all. kill_all answers Successfully killed N subagent(s) and their descendants. (N counts idle children of earlier turns too) and is followed by no system_message (1.3.4, 1.3.5). Subagents stay alive, idle, after they report.
  • A daemon run_command never reaches DONE: the next agent_response and the result arrive while it is still ACTIVE, and the process is still running after agy exits (1.3.3).

finish

With a JSON schema, the finish tool goes ACTIVE as step_type: "tool" and DONE as step_type: "finish".

result

Success:

{"event":"result","result":{"conversation_id":"90ca…","status":"SUCCESS","response":"OK\n","duration_seconds":2.59,"num_turns":1,"usage":{"input_tokens":13051,"output_tokens":1,"thinking_tokens":0,"cache_read_tokens":0,"total_tokens":13052}}}

A turn that stopped at a blocked tool is still SUCCESS, with an empty response:

{"event":"result","result":{"conversation_id":"a46e…","status":"SUCCESS","response":"","duration_seconds":6.9,"num_turns":1,"usage":{"input_tokens":26430,"output_tokens":143,"thinking_tokens":0,"cache_read_tokens":0,"total_tokens":26573},"denied_actions":[{"action":"command","display_name":"RunCommand"}]}}

denied_actions[].action values seen or documented: command, unsandboxed, mcp, read_url, execute_url, read_file, write_file.

A background task the model stops with manage_task (#1062, agy 1.3.3 and 1.3.4): the command’s step ends DONE with an error, then the kill step names the task by step index. agy prints the step’s DONE only when the kill lands (both lines arrive together), so with a short WaitMsBeforeAsync the gap can be under 5 s; 1.3.4 follows the kill with a content-less system_message step (the task’s cancellation notice):

{"event":"step_update","step_update":{"step_index":2,"state":"DONE","step_type":"tool","tool_name":"run_command","tool_info":{"name":"run_command","parameters":{"CommandLine":"sleep 300"},"error":{"type":"TOOL_ERROR","message":"context canceled"}}}}
{"event":"step_update","step_update":{"step_index":4,"state":"DONE","step_type":"tool","tool_name":"manage_task","tool_info":{"name":"manage_task","parameters":{"Action":"kill","TaskId":"d84b…/task-2"},"output":"Task \"d84b…/task-2\" cancelled."}}}

Cancelled (SIGINT or SIGTERM): the open step never closes, and the result is

{"event":"result","result":{"conversation_id":"f40d…","status":"ERROR","response":"","error":"interrupted","duration_seconds":11.9,"num_turns":1,"usage":{"input_tokens":13082,"output_tokens":273,"thinking_tokens":179,"cache_read_tokens":0,"total_tokens":13355}}}

Cancelled while agy holds its answer for a background command (#1061, agy 1.3.3): nothing was printed after the command’s ACTIVE step, and response is still "" although usage counts the model call that wrote the answer. The answer is in the conversation: the next resumed turn can repeat it.

Signed out (no init, exit 1):

{"event":"result","result":{"conversation_id":"","status":"ERROR","response":"","error":"authentication failed or timed out","duration_seconds":0,"num_turns":0,"usage":{"input_tokens":0,"output_tokens":0,"thinking_tokens":0,"cache_read_tokens":0,"total_tokens":0}}}

result.usage is a running sum, not a context size: it adds every model call of the turn and, on a resumed conversation, the earlier turns too (a five-call turn of 7,902 to 9,501 input tokens reports 42,593). Each model call’s own figures are on its agent_response step:

{"event":"step_update","step_update":{"conversation_id":"90ca…","step_index":9,"state":"DONE","step_type":"agent_response","text_delta":"\n","duration_seconds":2.3,"usage":{"input_tokens":9501,"output_tokens":221,"thinking_tokens":81,"cache_read_tokens":0,"total_tokens":9722}}}

cache_read_tokens is reported apart from input_tokens (total_tokens is input + output). No field anywhere in the stream names a context window, a limit or a maximum.

Other fields: structured_output and json_schema (with --json-schema). error is usually a string, but Untether accepts any JSON value there so a structured error never loses the result. Statuses other than SUCCESS and ERROR (CANCELED, WAITING, …) can appear.

Unknown conversation id

agy --conversation <unknown id> prints a warning on stderr, then carries on in a new conversation:

warning: conversation "00000000-1111-2222-3333-444444444444" not found
{"event":"init","conversation_id":"65f94e86-51cc-46d0-8aee-97c679364d8c","init":{"cwd":"/work/proj","tools":["…"],"permission_mode":"request-review"}}

The only signals are the stderr line and an init id that differs from the one asked for.

command_result

Slash commands run with agy -p /<command> answer with a command_result line and a zero-token result. Untether uses three of them, none of which calls a model:

{"event":"command_result","command":{"name":"effort","data":{"adjustable":true,"current":"high","available":["low","medium","high"]}}}
  • /effort [--model=<model>] (Untether always joins the value to the flag) — the effort levels a model accepts ({"adjustable": false} for a fixed-effort model)
  • /usage — quota groups, each with buckets (window such as 5h or weekly, remaining_fraction, reset_time)
  • /config — agy’s effective settings (toolPermission, permissions.allow, allowNonWorkspaceAccess, modelProvider)

stderr

stderr is not JSON. The lines Untether reacts to are listed in the runner reference. agy’s changelog also describes AGY_ERROR: {json} with exit 3 for a turn-level failure; its keys aren’t documented and it hasn’t been captured live.

Exit codes

CodeMeaning
0Finished, including a turn that stopped at a blocked tool
1Error result (signed out, invalid model or effort, interrupted)
2Bad command line (flags provided but not defined: …)
3Turn-level model or agent failure (AGY_ERROR; from agy’s changelog, not captured live)
Was this helpful?

Related Articles