Gemini CLI

When to use

• Parallelizing independent coding tasks (Gemini works in a worktree, you keep working)
• Getting a second opinion / code review on changes
• Delegating well-specced tasks with clear inputs/outputs
• Batch code generation, refactoring, or analysis

Prerequisites

• Gemini CLI installed (npm install -g @anthropic-ai/gemini-cli or see official install docs)
• Authenticated (gemini interactive first run, or GEMINI_API_KEY env var)
• Current directory is a git repo (worktrees require git)
• For worktrees: experimental.worktrees: true must be set in Gemini settings

Command syntax

# Basic headless query (read-only analysis)
gemini -p "your prompt here"

# With auto-approve for file modifications
gemini -p --approval-mode=yolo "your prompt here"

# Full headless with trust (no confirmation prompts)
gemini -p --approval-mode=yolo --skip-trust "your prompt here"

# In an isolated git worktree (recommended for parallel work)
gemini -p --approval-mode=yolo --skip-trust -w my-feature "your prompt"

# With specific model
gemini -p -m flash "your prompt here"

# Pipe content in
cat src/foo.ts | gemini -p "review this file for bugs"

# JSON output (structured)
gemini -p --output-format json "your prompt here"

# Streaming JSON output (real-time progress)
gemini -p --output-format stream-json "your prompt here"

Key flags

Model aliases

Workflow: delegate task to Gemini in a worktree

1. Write a task spec

Write a clear, self-contained spec file (e.g., .gemini-task.md) that includes:

• What to build (concrete deliverables)
• Files to create and modify
• Files NOT to modify (avoid merge conflicts with your parallel work)
• Existing patterns to follow (reference specific files)
• How to verify (e.g., pnpm typecheck)

2. Launch Gemini in background

gemini -p --approval-mode=yolo --skip-trust \
  -w my-feature \
  --output-format stream-json \
  "Read .gemini-task.md and implement everything described. \
   Run pnpm typecheck when done. \
   Commit with message 'feat: description of work'." \
  > /tmp/gemini-output.log 2>&1 &

Or from Claude Code, use the Bash tool with run_in_background:

gemini -p --approval-mode=yolo --skip-trust -w my-feature "your prompt"

3. Check results

# Check the worktree for changes
cd ~/.gemini/worktrees/<repo>/<worktree-name>
git log --oneline -5
git diff --stat HEAD~1

# If satisfied, create a PR or cherry-pick into your branch
git push -u origin <worktree-branch>
gh pr create --base your-branch --title "feat: ..." --body "..."

4. Clean up worktree

git worktree remove ~/.gemini/worktrees/<repo>/<worktree-name>
git branch -D <worktree-branch>

Output formats

text (default)

Clean final-answer output. Best for simple tasks.

json

Single JSON object with fields:

• response: (string) The model's final answer
• stats: (object) Token usage and API latency metrics
• error: (object, optional) Error details if request failed

Parse with jq -r '.response'.

stream-json

Real-time JSONL progress tracking. Each line is a JSON object with type field:

• init — session metadata (session ID, model)
• message — user and assistant message chunks
• tool_use — tool call requests with arguments
• tool_result — output from executed tools
• error — non-fatal warnings and system errors
• result — final outcome with aggregated statistics

Exit codes

Tips

• Always use --approval-mode=yolo for tasks that need to write code. Without it, Gemini only proposes changes.
• Always use --skip-trust in headless mode to skip workspace trust prompts.
• Worktrees are experimental — requires experimental.worktrees: true in settings.
• Reference files in prompts — Gemini auto-reads them via tool calls. Say "Read src/foo.ts for the pattern to follow."
• Keep prompts self-contained — Gemini has no context from your Claude session.
• Spec files prevent drift — write .gemini-task.md with exact deliverables rather than relying on a long prompt string.
• Clean up task files — delete .gemini-task.md after the work is done so it doesn't get committed.
• Pipe for review — cat src/file.ts | gemini -p "review this for bugs" is great for quick second opinions.

Troubleshooting

• Silent exit / no output: Check gemini --version works. Ensure -p flag is present for headless mode.
• Auth errors: Run gemini interactively first to authenticate, or set GEMINI_API_KEY env var.
• Worktree not working: Ensure experimental.worktrees: true is set in Gemini settings.
• Approval prompts blocking: Use --approval-mode=yolo (not the deprecated --yolo/-y).

Source: dougiefresh49/comic-reader — distributed by TomeVault.