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-flash
JSON output
node .claude/skills/omega-gemini-cli/scripts/ask-gemini.mjs "List 5 design patterns" --json
Code 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" -s
Stdin usage
echo "Explain recursion" | node .claude/skills/omega-gemini-cli/scripts/ask-gemini.mjs
File 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
Scripts
| 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-cli fallback 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
gemini interactive session (run gemini once to sign in)
- Rate limits: Governed by Gemini API quotas (generous for personal use on free tier)
- Platform: Full cross-platform; Windows uses
shell: true with 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:
--json wraps 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.
