gemini-cli-runtime

name	gemini-cli-runtime
description	Internal helper contract for calling the gemini-companion runtime from Claude Code
user-invocable	false

Gemini Companion Runtime Contract

Invocation

node "${CLAUDE_PLUGIN_ROOT}/scripts/gemini-companion.mjs" task [flags] -- <prompt>

Everything after -- (or the first non-flag positional) is the task text sent to Gemini.

Flags

Flag	Type	Default	Description
--write	boolean	false	Enable Gemini to make file changes (sets --approval-mode auto_edit)
--model <name>	string	auto-gemini-3	Model override — see model reference below
--thinking-budget <n>	integer	(unset)	Thinking token budget for the model
--approval-mode <mode>	string	default	One of: default, auto_edit, yolo, plan
--resume-last	boolean	false	Resume the most recent task thread in this repository
--background	boolean	false	Run as a detached background job
--wait	boolean	true	Run in the foreground (default)
--cwd <path>	string	$CLAUDE_PROJECT_DIR	Working directory override
--json	boolean	false	Emit structured JSON instead of rendered markdown

Model Reference

The default model is auto-gemini-3, which routes to the best available Gemini 3.x model.

Auto-routing aliases (recommended)

Alias	Routes to
auto-gemini-3	Gemini 3.1 or 3 (best available) — default
auto-gemini-2.5	Gemini 2.5 (stable, production)
pro	gemini-3.1-pro-preview (highest capability)
flash	gemini-3-flash-preview (speed-optimised)
flash-lite	gemini-3.1-flash-lite-preview (fastest)

Concrete model IDs (pin to specific preview)

Model ID	Generation
gemini-3.1-pro-preview	Gemini 3.1
gemini-3.1-flash-lite-preview	Gemini 3.1
gemini-3-pro-preview	Gemini 3
gemini-3-flash-preview	Gemini 3
gemini-2.5-pro	Gemini 2.5
gemini-2.5-flash	Gemini 2.5
gemini-2.5-flash-lite	Gemini 2.5

Unlisted model IDs are forwarded as-is to Gemini CLI.

Safety Rules

• Exactly one Bash call per rescue invocation.
• Never chain additional tool calls after the companion returns.
• Never inspect, modify, or second-guess Gemini's output.
• If the companion exits non-zero, return nothing — do not fabricate a response.
• Do not include --thinking-budget, --model, --resume-last, --background, or --wait in the task text itself. They are runtime controls.

Output

• stdout: Rendered markdown (default) or JSON (--json).
• stderr: Progress updates during execution.
• Exit code 0 = success, non-zero = failure.

Job Health Labels

/gemini:status reports a conservative Health label for each active job. Interpret each label as follows when deciding what to do next:

Label	Interpretation	Recommend to the user
active	Gemini emitted progress recently.	Wait for completion; do not cancel.
quiet	Heartbeat is recent but no new progress.	Re-check /gemini:status shortly.
possibly_stalled	No recent heartbeat or progress.	Re-check /gemini:status, fetch /gemini:result, or retry if the job does not recover.
rate_limited	Explicit quota or 429-class diagnostic.	Wait, switch models (--model flash / --model auto-gemini-2.5), or cancel with /gemini:cancel.
auth_required	Explicit auth/credential diagnostic.	Point the user to /gemini:setup to re-authenticate before retrying.
broker_unhealthy	The ACP broker reported busy/disconnected.	Re-check status shortly; a restart may be needed if it persists.
worker_missing	Worker PID is no longer alive.	Fetch /gemini:result; retry if the output is incomplete.
failed	Worker or Gemini ended with an error.	Fetch /gemini:result for the diagnostic and retry only after understanding it.
completed	Gemini finished successfully.	Fetch /gemini:result and present output; do not retry.
cancelled	Job was cancelled by user or system.	Fetch /gemini:result for final diagnostics; consider retrying if needed.

Never claim a job is dead or useless based on quiet or possibly_stalled alone. Those labels mean "check again", not "give up".