The lay of the land

Citations pinned at gemini-cli@b31b755 (cloned 2026-07-08).

Gemini CLI is Google's terminal coding agent — a TypeScript monorepo shipping as package version 0.51.0-nightly (gemini-cli/package.json:3). The gemini binary resolves to dist/index.js (gemini-cli/packages/cli/package.json:11-13), whose main() lives at gemini-cli/packages/cli/src/gemini.tsx:350. The split that defines the codebase is UI vs harness: the Ink/React terminal app and the non-interactive runner live in packages/cli/src/, while the entire engine lives in packages/core/src/ — the loop in core/, tool definitions in tools/, dispatch in scheduler/, the permission gate in policy/, context in context/, and sub-agents in agents/. Two more organs sit alongside the five here — a hook system (a BeforeTool check runs in the scheduler at gemini-cli/packages/core/src/scheduler/scheduler.ts:609-615) and a skills/ directory — but the personality of Gemini CLI shows up most in one place: its permission gate is not code, it is priority-sorted TOML data.

The loop

The loop is split across two layers. The outer loop lives in the driver. In non-interactive mode it is a literal while (true) (gemini-cli/packages/cli/src/nonInteractiveCli.ts:310-324) that calls geminiClient.sendMessageStream(...), collects every ToolCallRequest event from the stream into a batch, hands the batch to the scheduler, and then feeds the tool results back as the next user message — currentMessages = [{ role: 'user', parts: toolResponseParts }] (gemini-cli/packages/cli/src/nonInteractiveCli.ts:560) — before looping. The interactive Ink UI does the same through React hooks: handleCompletedTools re-submits the responses with { isContinuation: true } (gemini-cli/packages/cli/src/ui/hooks/useGeminiStream.ts:2019-2055).

The inner engine is GeminiClient.sendMessageStream, a recursive async generator (gemini-cli/packages/core/src/core/client.ts:910-917) bounded by MAX_TURNS = 100 (gemini-cli/packages/core/src/core/client.ts:79). It delegates to processTurn (gemini-cli/packages/core/src/core/client.ts:614), which builds a Turn whose run translates raw model chunks into typed Thought / Content / ToolCallRequest events (gemini-cli/packages/core/src/core/turn.ts:257-279). Two loop-control services run inside the engine. A LoopDetectionService inspects every event for runaway repetition (gemini-cli/packages/core/src/core/client.ts:747-763). And the inverse guard: when a turn ends with no pending tool calls, an LLM-based checkNextSpeaker can decide the model should keep going, recursing with a synthetic "Please continue." user message (gemini-cli/packages/core/src/core/client.ts:880-904). That self-continuation is the one loop organ Claude Code has no equivalent for — a model-judged decision to iterate even when nothing asked it to.

Tools and the gate

A tool is a DeclarativeTool carrying name, displayName, description, kind, and a JSON parameterSchema (gemini-cli/packages/core/src/tools/tools.ts:462-478). The load-bearing design is build-then-execute: BaseDeclarativeTool.build(params) validates the model's raw args against the schema and returns a frozen ToolInvocation — a first-class object binding the validated params to getDescription(), shouldConfirmExecute(), and execute() (gemini-cli/packages/core/src/tools/tools.ts:683-694, gemini-cli/packages/core/src/tools/tools.ts:47-107). Tools register in a ToolRegistry (gemini-cli/packages/core/src/tools/tool-registry.ts:271). Dispatch is a dedicated state machine, CoreToolScheduler: schedule(requests, signal) (gemini-cli/packages/core/src/scheduler/scheduler.ts:195-223) turns each request into a Validating call, then _processQueue walks it through $validating → (awaiting_approval) → scheduled → executing → success/error/cancelled$ (gemini-cli/packages/core/src/scheduler/scheduler.ts:428-433). Whether calls run in parallel is decided by the model itself, through a wait_for_previous boolean the harness injects into every tool's schema (gemini-cli/packages/core/src/tools/tools.ts:538-565, honored at gemini-cli/packages/core/src/scheduler/scheduler.ts:552-569).

The gate is where Gemini CLI is most distinctive. Every decision is one of ALLOW | DENY | ASK_USER (gemini-cli/packages/core/src/policy/types.ts:10-14), and the whole engine is a list of rules sorted once by priority (gemini-cli/packages/core/src/policy/policy-engine.ts:209-212), scanned top-down until the first matching rule wins (gemini-cli/packages/core/src/policy/policy-engine.ts:577-632). Rules come from TOML files layered in tiers — Admin > User > Workspace > Extension > Default, encoded as a priority band tier + priority/1000 (gemini-cli/packages/core/src/policy/policies/plan.toml:6-14) — and each rule can be scoped by tool name (wildcards), MCP server, args regex, subagent, interactivity, and approval mode (ruleMatches, gemini-cli/packages/core/src/policy/policy-engine.ts:85-196). The four approval modes DEFAULT | AUTO_EDIT | YOLO | PLAN (gemini-cli/packages/core/src/policy/types.ts:48-53) are ordered by permissiveness (gemini-cli/packages/core/src/policy/types.ts:60-65), but they are not if-branches — they are just a filter column on rules. Read-only tools are allowed at priority 50 (gemini-cli/packages/core/src/policy/policies/read-only.toml:30-56); write and shell tools ask at priority 10 (gemini-cli/packages/core/src/policy/policies/write.toml:47-57); AUTO_EDIT is a priority-15 override that flips write_file/replace to allow (gemini-cli/packages/core/src/policy/policies/write.toml:36-40, gemini-cli/packages/core/src/policy/policies/write.toml:65-69). YOLO is not an if-statement but a rule: toolName = "*" / decision = "allow" / priority = 998 / modes = ["yolo"] (gemini-cli/packages/core/src/policy/policies/yolo.toml:50-56) — and the priority-999 ask_user rule outranks it, so YOLO still asks when the model needs a human decision (gemini-cli/packages/core/src/policy/policies/yolo.toml:33-38). PLAN mode is a priority-40 deny-all with narrower rows stacked above it — an allow for two investigator agents at 50, a sharper write-tool deny at 65 (gemini-cli/packages/core/src/policy/policies/plan.toml:76-81, gemini-cli/packages/core/src/policy/policies/plan.toml:97-103, gemini-cli/packages/core/src/policy/policies/plan.toml:131-136). When no rule matches, the default is ASK_USER interactively and DENY non-interactively (gemini-cli/packages/core/src/policy/policy-engine.ts:253-256).

The scheduler consumes the verdict between validation and execution. After the BeforeTool hook (gemini-cli/packages/core/src/scheduler/scheduler.ts:609-615), checkPolicy asks the engine (gemini-cli/packages/core/src/scheduler/policy.ts:53-72, wired at gemini-cli/packages/core/src/scheduler/scheduler.ts:639-648): DENY becomes an error result without executing (gemini-cli/packages/core/src/scheduler/scheduler.ts:650-666), and ASK_USER enters resolveConfirmation, which flips the call to awaiting_approval and blocks on a message-bus reply (gemini-cli/packages/core/src/scheduler/scheduler.ts:672-686). The best detail: an "always allow" answer is persisted not into a set but by narrowing and writing a new policy rule (updatePolicy, gemini-cli/packages/core/src/scheduler/scheduler.ts:691-700) — restricted to the current approval mode and anything more permissive (gemini-cli/packages/core/src/scheduler/policy.ts:133-145). The ordinary "Allow for this session" click (ProceedAlways, gemini-cli/packages/cli/src/ui/components/messages/ToolConfirmationMessage.tsx:295-297) never sets a persistScope — only the separate save-to-settings outcome, ProceedAlwaysAndSave, does that, and only when the folder isn't a trusted workspace with its own policies dir (gemini-cli/packages/core/src/scheduler/policy.ts:147-157, forwarded unchanged at gemini-cli/packages/core/src/scheduler/policy.ts:216-238). So createPolicyUpdater defaults an unset scope to Workspace, not User (gemini-cli/packages/core/src/policy/config.ts:728-731,770-773) — landing at priority fraction 950 (gemini-cli/packages/core/src/policy/types.ts:370-377) on tier 3 (gemini-cli/packages/core/src/policy/config.ts:83-86), i.e. effective 3.950 — still enough to outrank every default-tier rule next time. Only a saved, untrusted-folder "always allow" climbs to the User tier, 4.950.

Delegation is a real organ that flows through this same gate. AgentTool is published to the model as invoke_agent (gemini-cli/packages/core/src/tools/tool-names.ts:191) with params { agent_name, prompt } (gemini-cli/packages/core/src/agents/agent-tool.ts:43-73); built-in agents are registered in code (gemini-cli/packages/core/src/agents/registry.ts:284-287) and user agents load from Markdown-with-YAML-frontmatter files (gemini-cli/packages/core/src/agents/agentLoader.ts:322-356). LocalAgentExecutor (gemini-cli/packages/core/src/agents/local-executor.ts:120) runs the child in its own while (true) loop (gemini-cli/packages/core/src/agents/local-executor.ts:674-688) with a separate chat and a restricted tool list, and termination is protocol-based — the child must call complete_task or it is an ERROR_NO_COMPLETE_TASK_CALL (gemini-cli/packages/core/src/agents/local-executor.ts:362-371). Sub-agents are allowed by default (invoke_agent is a priority-50 allow in gemini-cli/packages/core/src/policy/policies/agents.toml:1-10), and the engine injects the subagent's name as a virtual tool alias so a policy can target one agent by name (gemini-cli/packages/core/src/policy/policy-engine.ts:562-570).

Context and memory

Every turn opens with a context check inside processTurn. Two systems coexist behind getContextManagementConfig().enabled (gemini-cli/packages/core/src/core/client.ts:643): a newer graph-based ContextManager pipeline and the classic tryCompressChat path. After either, the client computes the remaining budget as tokenLimit(model) - lastPromptTokenCount and refuses to send a request that would overflow, yielding ContextWindowWillOverflow (gemini-cli/packages/core/src/core/client.ts:696-715). Compression proper lives in ChatCompressionService.compress (gemini-cli/packages/core/src/context/chatCompressionService.ts:271-285): it no-ops until history exceeds 50% of the model's token limit (DEFAULT_COMPRESSION_TOKEN_THRESHOLD = 0.5 gemini-cli/packages/core/src/context/chatCompressionService.ts:41), then keeps the most recent ~30% (COMPRESSION_PRESERVE_THRESHOLD = 0.3 gemini-cli/packages/core/src/context/chatCompressionService.ts:47) and sends the older portion to a summarizer LLM that must produce a <state_snapshot> — with an explicit anchor instruction to merge any previous snapshot rather than lose it (gemini-cli/packages/core/src/context/chatCompressionService.ts:353-374).

Durable memory is GEMINI.md (DEFAULT_CONTEXT_FILENAME, gemini-cli/packages/core/src/tools/memoryTool.ts:11-16) — the direct analogue of CLAUDE.md. Discovery traverses upward from the cwd collecting GEMINI.md variants (gemini-cli/packages/core/src/utils/memoryDiscovery.ts:458-470), and the result is a HierarchicalMemory { global, extension, project, userProjectMemory } (gemini-cli/packages/core/src/config/memory.ts:7-13) flattened into labeled sections and passed into the system prompt via getCoreSystemPrompt(config, userMemory, ...) (gemini-cli/packages/core/src/core/prompts.ts:23-35).

对照 Claude Code

Same five organs, but the gate is rehoused from code into data. Each row maps Gemini CLI's mechanism to the Claude Code page that dissects the equivalent:

• The loop → /stories/loop/1/ and /stories/loop/2/. Same "call model → run tools → feed results back as a user message → loop" cycle (gemini-cli/packages/cli/src/nonInteractiveCli.ts:560), with the same MAX_TURNS-style bound and loop detector — plus one extra organ: an LLM checkNextSpeaker that continues the loop even without tool calls (gemini-cli/packages/core/src/core/client.ts:880-904).
• Tool anatomy → /stories/tools/1/. Same name + schema + validate + execute, but Gemini CLI reifies a validated call as a first-class frozen ToolInvocation (gemini-cli/packages/core/src/tools/tools.ts:47-107) and runs dispatch through an explicit multi-status scheduler (gemini-cli/packages/core/src/scheduler/scheduler.ts:428-433) rather than executing inline.
• The permission gate → /stories/tools/2/. Same three-way allow / ask / deny verdict and same "ask → remember it" pattern, but where Claude Code's checks are code branches, Gemini CLI's are priority-sorted TOML data (gemini-cli/packages/core/src/policy/policy-engine.ts:209-212), even the approval modes are just rule filters (gemini-cli/packages/core/src/policy/types.ts:48-53), and "always allow" persists as a written rule (gemini-cli/packages/core/src/scheduler/scheduler.ts:691-700).
• Compaction → /stories/context/1/. Threshold-triggered LLM summarization that preserves a recent tail, with a Gemini-specific twist: a mergeable <state_snapshot> anchor so a second compaction folds the first in rather than dropping it (gemini-cli/packages/core/src/context/chatCompressionService.ts:353-374).
• Memory → /stories/context/2/. GEMINI.md is the direct analogue of CLAUDE.md, discovered hierarchically upward and injected into the system prompt (gemini-cli/packages/core/src/utils/memoryDiscovery.ts:458-470, gemini-cli/packages/core/src/core/prompts.ts:23-35).
• Sub-agents → /stories/multiagent/1/. Same shape — a tool spawns a child loop with separate history and a restricted tool set, defined by Markdown frontmatter (gemini-cli/packages/core/src/agents/agentLoader.ts:322-356) — but with a hard completion protocol: the child must call complete_task or it errors (gemini-cli/packages/core/src/agents/local-executor.ts:362-371).

What to steal

1. Permissions as priority-sorted TOML data. The entire gate — YOLO, plan mode, per-mode transitions, MCP trust, "always allow" persistence — is declarative rules with numeric priorities in tiered bands (gemini-cli/packages/core/src/policy/policies/plan.toml:6-14, gemini-cli/packages/core/src/policy/policy-engine.ts:209-212). "Allow everything in YOLO" is a single data row, not a code path (gemini-cli/packages/core/src/policy/policies/yolo.toml:50-56), and a user's "always allow" click writes a narrowed rule back into the engine (gemini-cli/packages/core/src/scheduler/scheduler.ts:691-700). The gate becomes auditable, overridable, and diffable.

2. Model-controlled parallelism (wait_for_previous). The harness injects a wait_for_previous: boolean into every tool's JSON schema, so the model itself declares data dependencies between calls in a batch (gemini-cli/packages/core/src/tools/tools.ts:538-565); the scheduler batches contiguous parallelizable calls, forcing edit tools sequential regardless (gemini-cli/packages/core/src/scheduler/scheduler.ts:552-569). Parallelism becomes a schema-level contract instead of a harness-side guess.

3. The inverse loop guard, checkNextSpeaker. Beside the runaway detector, an LLM judge decides whether the model's last turn implies it should keep going, driving a synthetic "Please continue." continuation (gemini-cli/packages/core/src/core/client.ts:880-904). Detection and continuation are both first-class, model-assisted harness services rather than fixed stop conditions.