claude-gemini-subagent

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?"