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--waitin 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".