claude-gemini-subagent

A Claude Code skill that teaches Claude to delegate expensive work — web search, large reads, long writes, bulk analysis — to Google's Gemini CLI as a worker subagent.

Claude stays the orchestrator: planning, deciding, and verifying. Gemini runs in its own context window, burns its own tokens, and returns a short answer. You get the combined intelligence of both models while keeping Claude's context lean.

Why Gemini? Gemini CLI gives you a local agent with its own tool use, code execution, and web access — all running in its own context. Delegating heavy work to Gemini means Claude's context stays focused on orchestration while Gemini handles the grunt work in parallel.

Features

• Adaptive approval mode — defaults to --approval-mode auto_edit (workspace-write), automatically escalates to full access when the task needs network or cross-workspace access. No approval prompts — Claude announces the choice in one line and proceeds.
• Thin-forwarder contract — Gemini's stdout is the authoritative return. No Claude-side freelancing, no phantom-answer drift.
• Smart stderr logging — captures Gemini's thinking stream to /tmp/gemini-<rand>.log instead of /dev/null, so the happy path stays clean but failures are fully debuggable.
• Reasoning effort by task class — audits and security reviews get high, normal edits use the default. No extra config.
• Resume-first pattern — follow-ups reuse Gemini's prior session state via gemini --resume latest, avoiding redundant context re-loading.
• Parallel batch dispatch — independent subtasks fire in parallel via Claude Code's background task system.
• Background lifecycle — long runs go background (run_in_background: true), poll with TaskOutput, cancel with TaskStop.
• Structured outcome classification — every result is classified as success / partial / error and handled accordingly. No silent retries.
• Multi-modal personas — 5 pre-written persona templates (reviewer, debugger, auditor, researcher, refactorer), each with its own sandbox/effort defaults and explicit return-format contract. Drop-in your own in the same format.
• Zero-dep helper scripts — scripts/doctor.sh for health checks, scripts/gemini-dispatch.sh for direct CLI use, scripts/sync-skill.sh for maintainers.

Prerequisites

1. Claude Code (CLI, desktop app, or IDE extension)
2. Gemini CLI — Google's gemini command-line agent. Install via npm:

   npm install -g @anthropic-ai/gemini-cli
   gemini auth    # first-time auth with Google account

3. A bash-compatible shell:
   • macOS, Linux: native
   • Windows: git-bash (comes with Git for Windows) or WSL

That's it. No Node dependencies for the skill itself, no config files, no MCP servers.

Install

Pick one:

Option A — Manual skill copy (works anywhere, 10 seconds)

git clone https://github.com/dwgx/claude-gemini-subagent.git
cp -r claude-gemini-subagent/skills/gemini-subagent ~/.claude/skills/

That's it. Claude Code auto-discovers skills under ~/.claude/skills/.

Option B — As a Claude Code plugin

If your Claude Code supports marketplace plugins:

/plugin install https://github.com/dwgx/claude-gemini-subagent

Or add this repo as a marketplace and install normally.

Option C — One-liner (curl)

mkdir -p ~/.claude/skills/gemini-subagent && \
curl -fsSL https://raw.githubusercontent.com/dwgx/claude-gemini-subagent/main/skills/gemini-subagent/SKILL.md \
  -o ~/.claude/skills/gemini-subagent/SKILL.md

Detailed platform-specific instructions in INSTALL.md.

Usage

Once installed, just talk to Claude normally. The skill self-triggers on phrases like:

• "丟給 gemini 查一下 bun 最新版本"
• "丟給 gemini 掃一下這個 repo 裡的 TODO"
• "delegate this audit to gemini"
• "gemini 幫我分析一下這個長 log"
• "I'm stuck — ask gemini for a fresh pass"

Claude will announce the dispatch in one line (including which approval mode it picked and why), run gemini, and summarize the result. You never see the raw stdout unless you ask.

Using a persona

Tell Claude to use a specific persona for more structured output:

用 gemini 的 auditor persona 審計 src/api/auth/

Dispatch gemini in debugger mode — test_payment.py::test_refund is failing

See personas/ for all available modes, or write your own (it's just markdown with a {{TASK}} placeholder).

Direct CLI dispatch (no Claude needed)

./scripts/gemini-dispatch.sh --persona researcher \
  "What's the current stable version of Bun as of today?"

See examples/sample-dispatches.md for 8 real dispatch patterns you can copy.

Health check

./scripts/doctor.sh

Validates every moving part — Gemini CLI presence and version, flag support, shell environment, skill install location. Run this first if anything seems off.

Design philosophy

Five principles, stolen from the best parts of five other projects:

1. Thin forwarder — one call in, stdout out. No freelancing.
2. Adaptive escalation (our own) — default low-privilege, escalate automatically, announce the choice. No prompts.
3. Stderr to temp log, not /dev/null — filename=$(openssl rand -hex 4); gemini ... 2>>"/tmp/gemini-${filename}.log". Clean happy path, full debug on failure.
4. Structured outcome classification — success / partial / error, each with a handling rule.
5. Resume-first — follow-ups reuse session state via gemini --resume latest, never paying to reload context.

What it is NOT

• Not a replacement for Read/Edit on small, known targets. Direct tools are cheaper for tiny ops. This skill only earns its keep when the alternative would cost >3k Claude tokens.
• Not a way to offload thinking. Claude still owns planning, decisions, and judgment. Gemini is a worker, not a co-pilot.
• Not a silent fallback. Every dispatch is announced so you can course-correct.
• Not a queue system. For heavy async lifecycle (multiple long jobs, status polling), use dedicated task runner tools — they complement this skill.

Troubleshooting

Symptom	Likely cause	Fix
gemini: command not found	Gemini CLI not installed or not on PATH	npm install -g @anthropic-ai/gemini-cli, then restart your terminal
operation not permitted / approval mode denial	Task needs higher approval mode	Skill should auto-escalate; if it didn't, check the task description matched an escalation trigger
network unreachable	Approval mode restricting network	Escalate to full access (skill does this automatically for network tasks)
Skill doesn't trigger when expected	Description phrasing didn't match	Say "丟給 gemini" or "delegate to gemini" explicitly; phrasing matters for skill triggering

Still stuck? Open an issue.

Credits

This skill builds on the design patterns established by the Claude-Codex subagent ecosystem and adapts them for the Gemini CLI:

• Thin-forwarder contract pattern
• Structured outcome classification
• Resume-first follow-up pattern
• File-based persona registry
• Stderr temp-log pattern for debugging

License

MIT — see LICENSE. LICENSE).