tomevault-io 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".
Source: sakibsadmanshajib/gemini-plugin-cc — distributed by TomeVault.