gemini-integration

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.

install

source · Clone the upstream repo

git clone https://github.com/thepushkarp/cc-gemini-plugin

Claude Code · Install into ~/.claude/skills/

git clone --depth=1 https://github.com/thepushkarp/cc-gemini-plugin ~/.claude/skills/thepushkarp-cc-gemini-plugin-gemini-integration

manifest: SKILL.md

source content

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