Gemini CLI Skill
Headless wrapper for Google Gemini CLI. Sends prompts via stdin to gemini -p "" --yolo. Free tier available — no API key required (Google OAuth only).
When to Use
- Get a Google Gemini perspective on any question
- Free-tier AI consultation (no API key costs)
- Code review from Gemini's model
- Brainstorming and analysis tasks
- Cross-validation of Claude's own responses
- Large files or codebases that benefit from Gemini's context window
- Sandbox execution (run/test code via Gemini)
Response Times
Gemini CLI runs as a subprocess and includes model startup time:
- Simple Q&A / news query: ~2 minutes
- Codebase or large-file review: ~5–10 minutes
Set expectations with the user before running long tasks.
Usage
Ask a question
node .claude/skills/omega-gemini-cli/scripts/ask-gemini.mjs "What is the best caching strategy for a Node.js API?"Specify model (short or long flag)
node .claude/skills/omega-gemini-cli/scripts/ask-gemini.mjs "Explain async/await" --model gemini-2.5-flash
node .claude/skills/omega-gemini-cli/scripts/ask-gemini.mjs "Explain async/await" -m gemini-2.5-flashJSON output
node .claude/skills/omega-gemini-cli/scripts/ask-gemini.mjs "List 5 design patterns" --json
# Returns: {"response":"..."} on success, {"error":"...","raw":"..."} on parse failureCode sandbox (short or long flag)
node .claude/skills/omega-gemini-cli/scripts/ask-gemini.mjs "Write and run a fibonacci function" --sandbox
node .claude/skills/omega-gemini-cli/scripts/ask-gemini.mjs "Write and run a fibonacci function" -sStdin usage
echo "Explain recursion" | node .claude/skills/omega-gemini-cli/scripts/ask-gemini.mjsFile review (embed content in prompt)
node .claude/skills/omega-gemini-cli/scripts/ask-gemini.mjs "Review this code: $(cat src/auth.ts)"Availability Check
node .claude/skills/omega-gemini-cli/scripts/verify-setup.mjs
# Exit 0 = available (Node 18+ and Gemini CLI found)
# Exit 1 = not installed or too oldScripts
| Script | Purpose |
|---|---|
ask-gemini.mjs | Core headless wrapper — sends prompt via stdin |
parse-args.mjs | Argument parser (--model/-m, --json, --sandbox/-s) |
verify-setup.mjs | Availability check (Node 18+, Gemini CLI via PATH or npx) |
format-output.mjs | Output normalization (JSON envelope handling) |
Flags
| Flag | Short | Description |
|---|---|---|
--model MODEL | -m | Gemini model (e.g., gemini-2.5-flash, gemini-2.5-pro) |
--json | Machine-readable JSON output: {"response":"..."} envelope | |
--sandbox | -s | Code execution sandbox mode |
Models (2026)
| Model ID | Notes |
|---|---|
gemini-3-pro-preview | Latest (2026), highest capability |
gemini-3-flash-preview | Latest (2026), faster |
gemini-2.5-pro | Stable, high capability |
gemini-2.5-flash | Recommended: lower quota/latency |
gemini-2.5-flash-lite | Lightest, fastest, lowest quota usage |
Exit Codes
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Error (CLI failure, auth issue, JSON parse failure with --json) |
| 9009 | Windows: command not found (falls back to npx automatically) |
Slash Commands (when installed in a project with.claude/commands/)
| Command | Purpose |
|---|---|
/analyze | Run headless script with user's prompt (and any @ file refs) |
/sandbox | Run with --sandbox; execute or test code |
/omega-gemini | Alias: run headless for analysis, sandbox, or brainstorm as appropriate |
/brainstorm | Brainstorm mode (build prompt with challenge + optional methodology) |
/omega-gemini-setup | Verify Node and Gemini CLI; guide user to install and auth. No MCP. |
Anti-Patterns & Iron Laws
- ALWAYS use verify-setup.mjs before first use
- NEVER pass prompt as positional arg to raw gemini CLI — use ask-gemini.mjs wrapper
- ALWAYS validate model parameter (wrapper validates via regex
^[a-zA-Z0-9._-]+$on Windows) - NEVER assume gemini is on PATH — wrapper handles npx
@google/gemini-clifallback automatically - ALWAYS handle exit code 1 and 9009 gracefully
- ALWAYS set user expectations about response time before running (2–10 minutes typical)
Integration Notes
- Auth: One-time Google OAuth via
geminiinteractive session (rungeminionce to sign in) - Rate limits: Governed by Gemini API quotas (generous for personal use on free tier)
- Platform: Full cross-platform; Windows uses
shell: truewith model validation; non-Windows uses array args (no shell) - npx fallback: On PATH miss, automatically retries with
npx -y @google/gemini-cli - No timeout flag: Unlike other omega wrappers, gemini wrapper has no --timeout-ms
- Stdin delivery: Prompt always sent via stdin to avoid shell argument length limits (8191-char cmd.exe limit on Windows, ARG_MAX on Linux/macOS)
- JSON envelope:
--jsonwraps output as{"response":"..."}on success or{"error":"...","raw":"..."}on failure
Requirements
- Node.js 18+ to run the scripts
- Google Gemini CLI (
npm install -g @google/gemini-cli) with one-time Google sign-in
Memory Protocol
Before work: Read .claude/context/memory/learnings.md After work: Append findings to learnings or issues as needed.
*Note: Use pnpm search:code to discover references to this skill codebase-wide.*