# Gemini CLI

The Gemini CLI is a terminal agent for breadth analysis, code review, and cross-file structural edits.

## 1. Config Surfaces

- **Project Context:** `GEMINI.md`. The main instruction file in the repository root.
- **Project Settings:** `.gemini/settings.json`. Local configuration for UI, defaults, and model choices.
- **Global Context:** `~/.gemini/`. Global configuration and instructions. **Warning:** Watch out for `~/.gemini/GEMINI.md` accumulating cross-project bleed and duplicates.
- **Hooks & Skills:** `.gemini/hooks/` and `.gemini/skills/`. Project-specific reflexes and automated behaviors.

## 2. Keeping Configs Lean

Gemini CLI reads `GEMINI.md` on startup. Like Claude Code, keep this file under 32 lines. Do not use the global `~/.gemini/GEMINI.md` as a dump for every instruction, as those lines will pollute the context window of every project you open.

## 3. Totem Integration

The `AI_PROMPT_BLOCK` provided by `totem init` is injected into `GEMINI.md`. This ensures Gemini CLI runs the `search_knowledge` MCP tool before making edits. The CLI can also execute `totem review` and hooks to re-index the memory db.

## 4. Common Pitfalls

- **The Global Trap:** `~/.gemini/GEMINI.md` grows to 64+ lines of duplicate instructions and bloats the context window for every project.
- **Dead Files:** A lowercase-named instruction file placed inside `.gemini/` is dead or unrecognized by both Gemini CLI and GCA. The correct filename is `GEMINI.md` at the project root.
- **Secrets Leakage:** Hardcoding PATs inside `.gemini/settings.json`.
