❯ the loop
claude-code codex-cli cursor-cli gemini-cli

Gemini CLI / cookbook

Recipes for the parts of Gemini CLI that have no equivalent elsewhere: custom commands that can splice shell output into their own prompt, checkpointing you can rewind, and a plan mode that refuses to touch anything. Hand-written, unlike the cheat sheet — the commands are real, the combinations are editorial.

Cheat sheet Cookbook Changes

Custom commands

Build a command that gathers its own context intermediate

You keep running the same command, pasting its output back in, and then asking the question.

on the sheet: extendconfig

  1. Custom commands can run shell with !{...} and splice the output straight into the prompt. The command collects its own evidence before the model sees it.

    .gemini/commands/pr/review.toml
    description = "Review the current branch against main."
prompt = """
Review this diff like an owner. Prioritize correctness and
regressions over style. Cite every finding as file:line.

Diff:
!{git diff main...HEAD}

Recent commits:
!{git log --oneline main..HEAD}
"""

  2. Directory nesting becomes namespacing, so this one is invoked as /pr:review. Project commands live in .gemini/commands/, personal ones in ~/.gemini/commands/.

    /pr:review

This inverts the usual loop. Instead of you fetching context and pasting it in, the command is the fetch — so it can't be run against stale output, and everyone who types /pr:review gets the same evidence.

Custom commands

Take an argument and use it in both prose and shell intermediate

A command should be parameterized — search for this, fix that — rather than hard-coded.

on the sheet: extend

  1. {{args}} interpolates in the prompt text and inside !{...} blocks. Used in both, it's substituted in both.

    .gemini/commands/find.toml
    description = "Explain every use of a pattern."
prompt = """
Summarize the findings for the pattern `{{args}}`.
Explain what each call site is actually doing.

Search results:
!{grep -rn {{args}} . --include=*.ts}
"""

  2. Invoke it with the argument.

    /find useLegacyAuth

Anything reaching !{...} runs in a shell, so an argument is untrusted input in a command position. Keep injected args inside a single well-understood command like grep, and don't build one that would happily interpolate ; rm -rf . into something more creative.

Custom commands

Undo & approvals

Let it try the risky refactor — you can rewind starter

You want the agent to attempt something ambitious without betting the working tree on it.

on the sheet: sessionconfig

  1. Enable checkpointing in settings.json. The --checkpointing flag was removed in 0.11.0 — settings is the only way in now.

    ~/.gemini/settings.json
    {
  "checkpointing": {
    "enabled": true
  }
}

  2. Before any file-modifying tool runs, the CLI snapshots the project and the conversation. Undo both with /restore.

    /restore

/restore rewinds the conversation as well as the files — which is what makes it more than git checkout .. You don't end up with a clean tree and an agent still convinced it already made the change.

Checkpointing

Get the plan before anything gets written starter

The change is big enough that you want to argue with the approach before it exists in files.

on the sheet: approvalflags

  1. Plan mode reads and analyzes but won't modify. It's a read-only approval mode, not a promise.

    gemini --approval-mode plan -p "Analyze telemetry and suggest improvements"

  2. Leave plan mode in plain language once you like the plan.

    exit plan mode

The four approval modes are default, auto_edit, yolo, and plan. Reversing them into a workflow — plan to decide, auto_edit to grind through the mechanical part — is more useful than picking one and living with it.

Plan mode

Headless & CI

Run it in a script starter

You want Gemini in a pipeline and need a parseable answer out the other end.

on the sheet: headlessflags

  1. -p runs headless; --output-format json makes it machine-readable.

    gemini -p "Does this repo have a CI workflow? Answer yes or no." \
  --output-format json | jq -r '.response'

  2. Bound what it can reach when the run is unattended.

    gemini -p "Summarize the open TODOs." \
  --approval-mode plan \
  --allowed-tools "read_file,glob,search_file_content"

Pairing --approval-mode plan with an allowlist in CI gives you an agent that can analyze and report but structurally cannot commit — the safe default for anything that runs without a human watching.

Headless mode