Guides for Gemini CLI

Gemini CLI is Google's open-source coding agent for the terminal. You give it a task in plain language and it reads files, runs commands, edits code, and asks for approval according to your settings. It keeps the conversation, the files it was told to read, and the rules from your context files in one context window (the fixed amount of text the model can keep in view at once), which is why the same symptom can come from three different places.

Status, 27 October 2026. These guides now apply to paid tier, API key, Vertex AI and enterprise users. Unpaid-tier and Google One users were moved to Antigravity CLI on 18 June 2026. Gemini CLI has not been optimized for Gemini 4 Argon either, and the Gemini CLI documentation points anyone who wants that model to Antigravity.

Most of the confusing failures come down to one question: did the CLI load the thing, put it in the prompt, follow it, or remember it? Each page here starts from the check that fits its problem: /memory list for what loaded, /policies list for what is allowed, /hooks panel for whether a hook is enabled, and the session picker for a session that seems gone.

Run gemini --version before you use a page. This set was checked against v0.65.0, the stable release on 20 October 2026.

Checked against Gemini CLI's documentation on 27 October 2026.

Instructions#

Does Gemini CLI read AGENTS.md? — No, not by default: GEMINI.md is the built-in name. Adding AGENTS.md to context.fileName does not replace it, so a repository with both files sends both. The page covers the load order for the global file, private project memory, workspace files, extension files, and just-in-time files, plus the checks that prove what reached the model.

Being in the prompt is not the same as being followed. The Claude Code page on a loaded but ignored CLAUDE.md separates those two failures; for Gemini, the permissions guide and the hooks guide cover the rules that must actually hold.

Sessions, context and undo#

Where did my Gemini CLI session go? — Sessions are stored per project under ~/.gemini/tmp/<project-id>/chats/, so the resume picker is narrower than the disk. Finding a session from another folder, how retention deletes old ones, and getting past "Invalid session identifier".

What rewind and restore put back — Rewinding the conversation and reverting file edits with /rewind, and the shadow-Git checkpoints that /restore uses. Why a checkpoint is not a Git backup, and which changes it never saw.

Context compaction — What a long session loses when older turns are replaced by a summary, and how to make the goal, the decisions, and the next action survive. The page covers the general mechanism and the other major agents; the Gemini load order is in the AGENTS.md page.

Permissions, models and tools#

Why Gemini CLI keeps asking for permission — The approval mode, the session-scoped "Allow" choice, the saved policy, and folder trust are four different controls. What "Allow for this session" stores for a shell command (a command prefix, not the exact command), for an edit (a rule for that file), and for an MCP tool (that tool), how long it lasts, and which higher rule can still ask.

Why your Gemini CLI hook doesn't fire — Where hooks load, which events exist, and how to tell "not loaded" from "loaded but the command failed". /hooks panel tells you whether the hook loaded and is enabled; a line the hook writes to a log tells you whether it ran. The settings layer is the usual cause of a hook that never loaded.

Gemini CLI says MCP is connected — A server can be configured, connected, and still contribute no usable tools. The page walks the pipeline from mcpServers config to the tool list, including settings scope, filters, renamed tools, and expired tokens.

Why Gemini CLI switches models mid-session — Auto routing is a policy, not a fixed model. Why a quota or capacity failure can move the session to a smaller model, how to pin one, and what pinning gives up.

Skills and subagents#

Why your Gemini CLI skill or subagent never activates — Discovery paths, the description that triggers a skill, what a subagent inherits, and why "installed" is not "activated".

Memory and files#

What memory shows in Gemini CLI — /memory displays the context-file chain, not a separate memory database. Where saved facts are written, what the private project memory is, and how to inspect or delete a memory.

Why Gemini CLI can't read a gitignored file — The read tool respects .gitignore by default, and .geminiignore does not override that in every path. The check, the setting, and the cases where the file is refused anyway.

Persistent memory for Claude Code and Codex is the cross-tool comparison: instruction files, vendor memory, MCP memory servers, and self-hosted options. It is the right starting point when the question is not "why did this file not load" but "which mechanism should remember this at all".

Hand off work between Claude Code and Codex is the written baton for work that moves between tools or sessions: what to write, where to put it, and how to check it arrived.

Other agents#

The Claude Code guides cover nested CLAUDE.md files, auto memory, subagents, sessions, permissions, and hooks. The Codex guides cover the AGENTS.md chain and its size limit, config.toml, sessions, approvals, hooks, and undo. The OpenCode guides cover the V1 and V2 lines, instructions, sessions, permissions, undo, and plugins. The GitHub Copilot CLI guides cover instructions, skills, custom agents, sessions, permissions, and hooks. Qwen Code, a fork of Gemini CLI that now differs in its default instruction files, storage and permission model, has its own guides. The Cursor guides cover AGENTS.md and rules loading, chat history, permissions, hooks and MCP.

The concepts page on instruction files, skills and memory compares what each agent reads and what it remembers.

Where to start#

If Gemini CLI is ignoring a rule, start with AGENTS.md to check whether the file loaded. If it keeps asking for the same approval, start with permissions. If the work disappeared, start with sessions. If a memory is not where you expected, start with what memory shows. The order is deliberate: what the agent was told, what it was allowed to do, and what it carried forward.