Gemini CLI Agentic Systems

Build headless automation with Google's Gemini CLI.

Compatibility: Gemini CLI 1.x. Features may differ in future versions.

Quick Start

# Basic headless invocation
gemini -p "Refactor auth.js to use async/await" --approval-mode auto_edit

# Pipe input for context
git diff --staged | gemini -p "Generate semantic commit message"

# JSON output for scripts
gemini -p "List TODOs in src/" --output-format json --include-directories src

Headless Checklist

Before any automation task:

- [ ] Set --approval-mode (auto_edit or yolo)
- [ ] Enable smartEdit in .gemini/settings.json
- [ ] Scope file access with --include-directories
- [ ] Choose output format (json for parsing)
- [ ] Add --resume for multi-step workflows

Approval Mode Decision

| Mode | Command | File Ops | Shell Cmds | Use When | |------|---------|----------|------------|----------| | default | (none) | ❌ Prompts | ❌ Prompts | Interactive only | | auto_edit | --approval-mode auto_edit | ✅ Auto | ❌ Prompts | Code refactoring | | yolo | --approval-mode yolo | ✅ Auto | ✅ Auto | Sandboxed CI/CD |

Rule: Never use yolo outside containers or ephemeral environments.

Least Privilege Pattern

Restrict capabilities with --allowed-tools:

# Documentation agent: read + write only, no shell
gemini -p "Update README from source" \
  --approval-mode yolo \
  --allowed-tools "ReadFile,WriteFile"

# Analysis agent: read only
gemini -p "Find security issues in src/" \
  --approval-mode auto_edit \
  --allowed-tools "ReadFile"

Tool Selection

| Task | Tool | Rationale | |------|------|-----------| | Create new file | WriteFile | No existing content | | Rewrite small file (<50 lines) | WriteFile | Simpler than surgical edit | | Modify existing code | Edit | Preserves unrelated content | | Fix specific function | Edit | Surgical precision |

Edit Tool Reliability

The Edit tool uses exact string matching. Common failure:

Error: 0 occurrences found for old_string

Cause: Model hallucinated whitespace, tabs, or characters.

Fix: Enable smartEdit (fuzzy matching):

// .gemini/settings.json
{
  "useSmartEdit": true
}

See tools.md for detailed patterns.

File Access Model

Gemini uses explicit consent—agent sees only referenced files.

Expanding Visibility

# Single directory
--include-directories src

# Multiple directories
--include-directories src --include-directories lib

# Current directory (careful with token budget)
--include-all-files

Token budget warning: Including thousands of files degrades reasoning. Be selective.

See permission-model.md for security details.

Context Configuration

GEMINI.md (Agent Instructions)

Create ./GEMINI.md in project root:

# Project Context

You are a Senior Engineer working on this Node.js API.

## Constraints
- Use TypeScript strict mode
- Never modify test fixtures
- Log all file changes to session_log.md

## Style
- 2 spaces indentation
- Single quotes for strings

Import external docs with @file:

@./docs/api-schema.md
@./docs/coding-standards.md

settings.json Hierarchy

Precedence (lowest → highest):
1. Defaults
2. ~/.gemini/settings.json (user)
3. .gemini/settings.json (project)
4. Environment variables
5. Command-line flags

See context-hierarchy.md for full reference.

Session Persistence

Headless sessions are ephemeral by default. For multi-step workflows:

# First invocation
gemini -p "Analyze codebase structure" --output-format json > analysis.json

# Resume with previous context
gemini -p "Now refactor based on analysis" --resume latest

# Resume specific session
gemini -p "Continue refactoring" --resume abc123-uuid

Output Formats

| Format | Flag | Use Case | |--------|------|----------| | text | (default) | Human reading | | json | --output-format json | Script parsing | | stream-json | --output-format stream-json | Real-time dashboards |

Parsing JSON Output

# Extract final answer
gemini -p "List files" --output-format json | jq '.response'

# Check if tool was called
gemini -p "Edit file" --output-format json | jq '.tool_calls'

MCP Integration

Extend agent to external services (GitHub, Postgres, Slack).

// .gemini/settings.json
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    }
  }
}

See mcp-integration.md for server configs.

Debugging

# Verbose output showing Client ↔ Core traffic
gemini -p "Edit file" --debug

# Check what model proposed
gemini -p "Edit file" --debug 2>&1 | grep "old_string"

Session Logging Pattern

Instruct agent via GEMINI.md:

## Logging
After every action, append timestamped summary to session_log.md

Common Mistakes

| Mistake | Symptom | Fix | |---------|---------|-----| | No approval mode | Script hangs forever | Add --approval-mode auto_edit | | smartEdit disabled | Edit fails repeatedly | Enable in .gemini/settings.json | | yolo on host machine | Security risk | Use containers only | | No --include-directories | Agent can't find files | Scope visibility explicitly | | Interactive shell commands | Script hangs on prompts | Use non-interactive flags (-y) |

Common Patterns

Git Commit Agent

git diff --staged | gemini -p "Generate semantic commit message. Output only the message, no explanation."
# Output: feat(auth): add JWT refresh token rotation

Linter Auto-Fix

npm run lint 2>&1 | gemini -p "Fix these lint errors" \
  --approval-mode auto_edit \
  --include-directories src
# Agent reads errors, edits files, outputs: "Fixed 3 files: auth.js, utils.js, api.js"

Test Generator

gemini -p "Generate Jest tests for src/utils.js" \
  --approval-mode auto_edit \
  --include-directories src

When Not to Use This Skill

• Interactive chat with Gemini (use default mode)
• Non-Gemini LLM CLIs (different flag syntax)
• Gemini API direct integration (this is CLI-specific)
• Web-based Gemini interfaces

Reference Files

• flags.md — Complete flag reference
• permission-model.md — Consent model + approval modes
• context-hierarchy.md — GEMINI.md + settings.json
• tools.md — ReadFile, Edit, WriteFile, RunShell
• mcp-integration.md — External service integration

Assets

• GEMINI-template.md — Starter context file
• settings-template.json — Minimal config with smartEdit
• headless-wrapper.sh — Shell script template

Scripts

• validate-setup.sh — Verify configuration before deployment