| name | gemini-integration |
| description | Use Gemini CLI for long-context codebase exploration, architecture review, refactor impact analysis, documentation synthesis, or structured data analysis when the host should hand off a large cross-file problem instead of solving it file-by-file. |
| allowed-tools | Bash, Glob, Read |
Gemini CLI Integration
Gemini CLI is the large-context handoff in this repository. Use it when the
task is about the shape of a system, a broad slice of a repo, or a mixed text
dataset that should be synthesized in one pass.
When to Use Gemini
Ideal Cases
| Scenario | Why Gemini Fits |
|---|
| Whole-codebase architecture | Broad cross-file synthesis |
| Cross-file security review | Traces flows across modules |
| Refactor impact analysis | Finds dependencies and callers |
| Codebase orientation | Produces a high-level map quickly |
| Documentation generation | Synthesizes behavior from many files |
| Structured data review | Reads JSON, YAML, TOML, CSV, Markdown, and code together |
Not Ideal
| Scenario | Why |
|---|
| Quick single-file edits | The handoff adds latency you do not need |
| Tight interactive debugging | Better handled directly by the host model |
| Narrow tasks with no cross-file context | Gemini adds little value |
Host Entry Points
Claude Code
Use the slash command:
/cc-gemini-plugin:gemini <task>
/cc-gemini-plugin:gemini --dirs src,docs <task>
/cc-gemini-plugin:gemini --files "schemas/**/*.json" <task>
Claude can also spawn gemini-agent when the task obviously benefits from a
large-context pass.
Codex
- Mention the skill explicitly with
$gemini-integration.
- Or ask Codex to use the Gemini integration for a large analysis task.
Codex reads this skill definition directly when the repository is installed as a
user-level skill.
Shared Runtime Contract
Always prefer the shared bridge script over hand-written gemini commands:
node scripts/gemini-bridge.js [options] <task>
The bridge owns:
- argument parsing
- directory and file ingestion
- structured prompt assembly
- Gemini CLI invocation
Use:
--dirs <path,...> for broad module trees--files <glob,...> for targeted globs and mixed data formats--model <name> only when the caller explicitly wants a model override--format json only when structured output is required--print-command when you need to inspect the resolved Gemini command
Good Patterns
Architecture
node scripts/gemini-bridge.js --dirs src,docs \
"Explain the architecture and cite the key files."
Refactor impact
node scripts/gemini-bridge.js --dirs src \
"Analyze the impact of refactoring the auth module. Include affected files and migration steps."
Structured data
node scripts/gemini-bridge.js --files "schemas/**/*.json,data/**/*.csv" \
"Summarize the data contracts and identify breaking changes."
Troubleshooting
| Issue | Solution |
|---|
| Authentication error | Run gemini auth |
| Gemini missing on PATH | Install @google/gemini-cli or brew install gemini-cli |
| Rate limiting | Retry with a narrower task or smaller context set |
| Token pressure | Reduce the number of inlined files |
