Hybrid Mode

Hybrid Mode: Claude Gemini Collaboration

Overview

Hybrid Mode lets Claude (the lead) consult Gemini CLI as an independent expert peer. Claude frames a question, hands Gemini the relevant context, and Gemini returns a focused critique or validation. Claude then weighs that counsel, states whether it agrees, and proceeds. Gemini is an advisor, not the decider: Claude remains the lead architect and owns the final call.

This formalizes the manual "ask Gemini for an architectural review / decision" workflow into a single, reliable, repeatable tool.

When to use

Reach for Hybrid Mode when an independent second opinion materially de-risks a decision:

• Architectural review, before committing to a design, get a critique of the

approach, its tradeoffs, and alternatives.

• Plan validation, hand Gemini a proposed implementation plan and ask it to

find gaps, hidden coupling, or sequencing problems.

• Code review, ask Gemini to review a diff or file for correctness,

security, and maintainability issues Claude may have anchored past.

• Decision arbitration, when torn between two approaches, present both and

ask Gemini for a verdict with reasoning.

• High-stakes / irreversible actions, cross-check before a migration,

cutover, schema change, or production deploy.

• The user explicitly asks for Gemini's input, a "hybrid" review, or a

"second opinion."

When NOT to use

• Trivial, low-risk, or easily reversible changes, the round-trip cost is not

worth it.

• Questions Claude can answer with full confidence from the code in front of it.
• As a way to offload work Claude should do, Gemini advises; Claude still does

the engineering and owns correctness.

• Anything requiring Gemini to make edits, this skill runs Gemini read-only by

design. Claude makes all changes.

How it works

  Claude                      consult_gemini.sh                Gemini CLI
  ------                      -----------------                ----------
  1. frame question  ──────>  build prompt on stdin  ──────>  read-only (plan)
  2. pick context dirs        gemini -o json --skip-trust      reasons over
                              --approval-mode plan             provided context
  3. invoke wrapper           --include-directories           │
                                      │                            ▼
  6. read .response   stderr/log

Claude does the thinking on both ends: it writes the prompt, and it interprets the answer. The script is plumbing that makes the Gemini round-trip clean and reliable (stdin for large prompts, read-only safety, JSON parsing, timeouts, diagnostics).

The workflow Claude follows

Step 1, Decide it is worth a consult

Confirm the decision is non-trivial and an independent view adds value (see "When to use"). If not, just proceed without Gemini.

Step 2, Construct a well-formed prompt

This is the most important step. The quality of Gemini's counsel is bounded by the quality of the prompt. A good Hybrid Mode prompt has five parts:

1. Role + framing — tell Gemini it is an independent senior reviewer in a

hybrid collaboration and that Claude wants its honest, independent judgment (not validation-seeking agreement).

1. Context — the relevant facts: what the system is, what is being built or

changed, and any constraints. Reference files by absolute path; the wrapper makes them readable via --context.

1. What Claude proposes — Claude's current plan or position, stated plainly

so Gemini can agree or push back on something concrete.

1. The specific question — one sharp question, not a vague "thoughts?".
2. Output contract — how to answer. Always ask Gemini to **lead with a

verdict** (e.g. VERDICT: AGREE / DISAGREE / NEEDS-CHANGES) and to be concise. Cap the length when you only need a focused take.

Use assets/prompt_template.md as the scaffold. Write the prompt to a temp file (e.g. /tmp/hybrid_.txt) so it is easy to pass and to log.

Avoid leading the witness: do not phrase the prompt so the only natural answer is "yes, Claude is right." The whole value is independent judgment.

Step 3, Launch Gemini via the wrapper

Run the script, passing the prompt and the directories Gemini needs to read.

scripts/consult_gemini.sh \
  --prompt-file /tmp/hybrid_.txt \
  --context /path/to/your/project/src \
  --timeout 600

Or pipe the prompt on stdin:

echo "$PROMPT" | scripts/consult_gemini.sh --context /path/to/your/project

For a long consult that should not block, run it in the background and collect the result when it finishes:

scripts/consult_gemini.sh --prompt-file /tmp/hybrid_arch.txt \
  --context /path/to/your/project/src > /tmp/hybrid_arch.out 2> /tmp/hybrid_arch.err

(If your agent runtime supports background execution, run the wrapper there rather than polling in a sleep loop. The response lands on stdout, diagnostics on stderr.)

Step 4, Read and weigh Gemini's response

Gemini's answer arrives on stdout. Read it critically:

• Does the verdict and reasoning hold up against what Claude knows?
• Did Gemini surface something Claude missed? Adopt it.
• Did Gemini misunderstand the context? That signals the prompt needed more

detail, refine and re-consult if the point is material.

• Disagreement is a feature. If Gemini disagrees, engage with the reasoning;

do not reflexively defer, and do not reflexively dismiss.

Step 5, State the synthesis and proceed

Tell the user, briefly: what Claude asked Gemini, what Gemini said (verdict + key point), and Claude's resulting decision, including where Claude diverges from Gemini and why. Then act. Claude owns the outcome.

Script reference: consult_gemini.sh

Launches Gemini CLI headlessly, read-only by default, and returns only Gemini's response on stdout.

| Flag | Default | Description | |------|---------|-------------| | --prompt-file PATH | (stdin) | Read the prompt from a file instead of stdin. | | --context DIR | (none) | Add a directory to Gemini's readable workspace. Repeatable. Pass repo roots holding files under review. | | --model NAME | CLI default | Override the Gemini model. | | --mode MODE | plan | Approval mode. plan = read-only (recommended). Other values (auto_edit, yolo, default) allow side effects; avoid for reviews. | | --timeout SECONDS | 600 | Hard wall-clock cap. | | --format FORMAT | text | text = just the response; json = full envelope incl. stats. | | --log PATH | temp file | Sidecar diagnostics log (prompt size, banners, raw JSON, latency, tokens). |

Exit codes: 0 success; 2 bad usage / empty prompt; 3 missing gemini/jq; 4 timeout; 5 ran but no usable response (auth, quota, model error). On non-zero exit, read the sidecar log path printed to stderr.

Design choices baked in:

• Prompt is delivered on stdin so large reviews (code, diffs) never hit

argv limits.

• --skip-trust is set because headless Gemini refuses untrusted workspaces;

read-only plan mode keeps this safe.

• Output is parsed from -o json via jq '.response', the only clean way to

separate Gemini's answer from its banners and stats footer.

• Diagnostics (model, latency, tokens, session) go to stderr + log, never

stdout, so the captured response stays clean.

Prompt templates

See assets/prompt_template.md for ready-to-fill scaffolds for the common consult types (architectural review, plan validation, code review, decision arbitration). See references/prompting_guide.md for the principles behind writing prompts that elicit genuinely useful, independent counsel.

Examples

Architectural review

cat > /tmp/hybrid_cache.txt  /tmp/hybrid_migration.out 2> /tmp/hybrid_migration.err
# collect /tmp/hybrid_migration.out when done

Troubleshooting

| Symptom | Likely cause | Resolution | |---------|--------------|------------| | Exit 3, "gemini not found" | Gemini CLI not on PATH | Ensure gemini is installed and on PATH (which gemini). | | Exit 4, timeout | Prompt too large or Gemini slow | Raise --timeout; trim context; ask a narrower question. | | Exit 5, empty response | Auth/quota/model error | Read the sidecar log; verify Gemini auth (gemini -p "hi" --skip-trust); check quota. | | Gemini misunderstands context | Prompt lacked detail or wrong --context | Add the right repo root via --context; reference files by absolute path; restate constraints. | | Gemini just agrees with everything | Prompt led the witness | Reframe neutrally; ask it to argue the strongest case against the proposal. | | Response references files it could not read | File outside provided context | Add the containing dir with --context. |

Scope & limitations

In scope:

• Read-only consultation: review, critique, validation, arbitration.
• Passing code/diffs/plans as context for Gemini to reason over.
• Single-turn consults framed by Claude.

Out of scope:

• Letting Gemini edit files or run side-effecting tools (read-only by design;

Claude makes all changes).

• Multi-turn back-and-forth sessions with Gemini (each consult is one shot;

Claude can issue follow-up consults but should re-state context).

• Treating Gemini's verdict as binding, Claude is the lead and owns the call.

Caveats:

• Gemini's counsel is only as good as the prompt and context it receives.
• Independent does not mean correct; weigh Gemini's view against the code and

Claude's own judgment.

• Do not send secrets or credentials in prompts or context dirs.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [manceps](https://github.com/manceps)
- **Source:** [manceps/skills](https://github.com/manceps/skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.