/cc-gemini-plugin

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 |