# google-gemini/gemini-cli architecture

> Architecture diagram of the GitHub repository google-gemini/gemini-cli, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/google-gemini/gemini-cli
- Repository: https://github.com/google-gemini/gemini-cli

## Overview

Gemini CLI is a terminal-based AI coding agent. Its main workflow takes a developer prompt through the interactive or scriptable CLI, uses core model and tool capabilities to produce a response or perform work, and presents the result in the terminal. The repository also includes documented MCP extensibility and checkpointing, plus a separate A2A server. The graph preserves these product branches and selected internal layers; source excerpts are partial, so undocumented runtime links are omitted.

Main entry points: [`packages/cli/src/interactiveCli.tsx`](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/interactiveCli.tsx) (Interactive terminal), [`packages/a2a-server/src/http/app.ts`](https://github.com/google-gemini/gemini-cli/blob/main/packages/a2a-server/src/http/app.ts) (A2A HTTP API), [`packages/cli/src/nonInteractiveCli.ts`](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/nonInteractiveCli.ts) (Script mode), [`packages/core/src/core/baseLlmClient.ts`](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/core/baseLlmClient.ts) (Model client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI experience"]
  node_interactive["Interactive terminal<br/>[interactiveCli.tsx]"]
  node_script["Script mode"]
  node_terminal_ui["Terminal UI<br/>[App.tsx]"]
  node_history["Conversation history"]
end

subgraph group_agent["Agent runtime"]
  node_model_client["Model client<br/>[baseLlmClient.ts]"]
  node_content_generator["Content generation"]
  node_context["Context pipeline<br/>[pipeline.ts]"]
  node_events["Core events<br/>[events.ts]"]
end

subgraph group_capabilities["Tools and extensions"]
  node_policy["Tool policy<br/>[policy-engine.ts]"]
  node_sandbox["Command sandbox<br/>[sandboxManager.ts]"]
  node_edit_tool["File editing<br/>[edit.ts]"]
  node_mcp_client["MCP integrations<br/>[mcp-client.ts]"]
  node_skills["Project skills<br/>[skillManager.ts]"]
end

subgraph group_state["Configuration and state"]
  node_config["Agent configuration<br/>[config.ts]"]
  node_storage[("Project storage<br/>[storage.ts]")]
  node_settings["CLI settings<br/>[settings.ts]"]
  node_recording["Session recording"]
  node_oauth_storage[("MCP credentials")]
end

subgraph group_server["A2A server"]
  node_a2a_http["A2A HTTP API<br/>[app.ts]"]
  node_a2a_executor["Task executor<br/>[executor.ts]"]
  node_a2a_config["Server configuration<br/>[config.ts]"]
  node_a2a_settings["Server settings<br/>[settings.ts]"]
  node_a2a_commands["Server commands"]
end

node_developer(("Developer"))
node_a2a_user(("A2A client"))

node_developer -->|"prompts"| node_interactive
node_developer -->|"submits prompt"| node_script
node_interactive -.->|"renders"| node_terminal_ui
node_interactive -.->|"configures"| node_config
node_script -.->|"configures"| node_config
node_interactive -.->|"requests generation"| node_model_client
node_script -.->|"requests generation"| node_model_client
node_model_client -->|"calls"| node_content_generator
node_model_client -->|"reads settings"| node_config
node_interactive -.->|"provides project context"| node_context
node_script -.->|"provides project context"| node_context
node_interactive -.->|"updates"| node_history
node_history -.->|"records"| node_recording
node_config -->|"uses"| node_storage
node_policy -->|"checks commands"| node_sandbox
node_interactive -.->|"authorizes tool calls"| node_policy
node_interactive -.->|"invokes tools"| node_edit_tool
node_interactive -.->|"invokes integrations"| node_mcp_client
node_interactive -.->|"loads skills"| node_skills
node_skills -->|"loads skill locations"| node_storage
node_mcp_client -.->|"uses credentials"| node_oauth_storage
node_oauth_storage -->|"emits events"| node_events
node_a2a_user -->|"submits tasks"| node_a2a_http
node_a2a_http -->|"creates tasks"| node_a2a_executor
node_a2a_http -->|"dispatches commands"| node_a2a_commands
node_a2a_http -->|"loads settings"| node_a2a_settings
node_a2a_http -->|"loads configuration"| node_a2a_config

click node_interactive "https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/interactiveCli.tsx"
click node_script "https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/nonInteractiveCli.ts"
click node_terminal_ui "https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/ui/App.tsx"
click node_history "https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/ui/hooks/useHistoryManager.ts"
click node_config "https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/config/config.ts"
click node_storage "https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/config/storage.ts"
click node_settings "https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/config/settings.ts"
click node_model_client "https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/core/baseLlmClient.ts"
click node_content_generator "https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/core/contentGenerator.ts"
click node_context "https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/context/pipeline.ts"
click node_recording "https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/services/chatRecordingService.ts"
click node_policy "https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/policy/policy-engine.ts"
click node_sandbox "https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/services/sandboxManager.ts"
click node_edit_tool "https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/tools/edit.ts"
click node_mcp_client "https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/tools/mcp-client.ts"
click node_skills "https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/skills/skillManager.ts"
click node_oauth_storage "https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/mcp/oauth-token-storage.ts"
click node_events "https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/utils/events.ts"
click node_a2a_http "https://github.com/google-gemini/gemini-cli/blob/main/packages/a2a-server/src/http/app.ts"
click node_a2a_executor "https://github.com/google-gemini/gemini-cli/blob/main/packages/a2a-server/src/agent/executor.ts"
click node_a2a_config "https://github.com/google-gemini/gemini-cli/blob/main/packages/a2a-server/src/config/config.ts"
click node_a2a_settings "https://github.com/google-gemini/gemini-cli/blob/main/packages/a2a-server/src/config/settings.ts"
click node_a2a_commands "https://github.com/google-gemini/gemini-cli/blob/main/packages/a2a-server/src/commands/command-registry.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_interactive,node_script,node_terminal_ui,node_history,node_a2a_user toneBlue
class node_model_client,node_content_generator,node_context,node_events toneAmber
class node_policy,node_sandbox,node_edit_tool,node_mcp_client,node_skills toneMint
class node_config,node_storage,node_settings,node_recording,node_oauth_storage toneRose
class node_a2a_http,node_a2a_executor,node_a2a_config,node_a2a_settings,node_a2a_commands,node_developer toneIndigo
```

## Components

### CLI experience

- [Interactive terminal](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/interactiveCli.tsx): `packages/cli/src/interactiveCli.tsx`
- [Script mode](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/nonInteractiveCli.ts): `packages/cli/src/nonInteractiveCli.ts`
- [Terminal UI](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/ui/App.tsx): `packages/cli/src/ui/App.tsx`
- [Conversation history](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/ui/hooks/useHistoryManager.ts): `packages/cli/src/ui/hooks/useHistoryManager.ts`

### Agent runtime

- [Model client](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/core/baseLlmClient.ts): `packages/core/src/core/baseLlmClient.ts`
- [Content generation](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/core/contentGenerator.ts): `packages/core/src/core/contentGenerator.ts`
- [Context pipeline](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/context/pipeline.ts): `packages/core/src/context/pipeline.ts`
- [Core events](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/utils/events.ts): `packages/core/src/utils/events.ts`

### Tools and extensions

- [Tool policy](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/policy/policy-engine.ts): `packages/core/src/policy/policy-engine.ts`
- [Command sandbox](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/services/sandboxManager.ts): `packages/core/src/services/sandboxManager.ts`
- [File editing](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/tools/edit.ts): `packages/core/src/tools/edit.ts`
- [MCP integrations](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/tools/mcp-client.ts): `packages/core/src/tools/mcp-client.ts`
- [Project skills](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/skills/skillManager.ts): `packages/core/src/skills/skillManager.ts`

### Configuration and state

- [Agent configuration](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/config/config.ts): `packages/core/src/config/config.ts`
- [Project storage](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/config/storage.ts): `packages/core/src/config/storage.ts`
- [CLI settings](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/config/settings.ts): `packages/cli/src/config/settings.ts`
- [Session recording](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/services/chatRecordingService.ts): `packages/core/src/services/chatRecordingService.ts`
- [MCP credentials](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/mcp/oauth-token-storage.ts): `packages/core/src/mcp/oauth-token-storage.ts`

### A2A server

- [A2A HTTP API](https://github.com/google-gemini/gemini-cli/blob/main/packages/a2a-server/src/http/app.ts): `packages/a2a-server/src/http/app.ts`
- [Task executor](https://github.com/google-gemini/gemini-cli/blob/main/packages/a2a-server/src/agent/executor.ts): `packages/a2a-server/src/agent/executor.ts`
- [Server configuration](https://github.com/google-gemini/gemini-cli/blob/main/packages/a2a-server/src/config/config.ts): `packages/a2a-server/src/config/config.ts`
- [Server settings](https://github.com/google-gemini/gemini-cli/blob/main/packages/a2a-server/src/config/settings.ts): `packages/a2a-server/src/config/settings.ts`
- [Server commands](https://github.com/google-gemini/gemini-cli/blob/main/packages/a2a-server/src/commands/command-registry.ts): `packages/a2a-server/src/commands/command-registry.ts`

### Other components

- **Developer**
- **A2A client**

## Connections

- Developer → Interactive terminal: prompts (evidence: `README.md`)
- Developer → Script mode: submits prompt (evidence: `README.md`)
- Interactive terminal → Terminal UI: renders
- Interactive terminal → Agent configuration: configures
- Script mode → Agent configuration: configures
- Interactive terminal → Model client: requests generation
- Script mode → Model client: requests generation
- Model client → Content generation: calls (evidence: `packages/core/src/core/baseLlmClient.ts`)
- Model client → Agent configuration: reads settings (evidence: `packages/core/src/core/baseLlmClient.ts`)
- Interactive terminal → Context pipeline: provides project context
- Script mode → Context pipeline: provides project context
- Interactive terminal → Conversation history: updates
- Conversation history → Session recording: records
- Agent configuration → Project storage: uses (evidence: `packages/core/src/config/storage.ts`)
- Tool policy → Command sandbox: checks commands (evidence: `packages/core/src/policy/policy-engine.ts`)
- Interactive terminal → Tool policy: authorizes tool calls
- Interactive terminal → File editing: invokes tools
- Interactive terminal → MCP integrations: invokes integrations
- Interactive terminal → Project skills: loads skills
- Project skills → Project storage: loads skill locations (evidence: `packages/core/src/skills/skillManager.ts`)
- MCP integrations → MCP credentials: uses credentials
- MCP credentials → Core events: emits events (evidence: `packages/core/src/mcp/oauth-token-storage.ts`)
- A2A client → A2A HTTP API: submits tasks (evidence: `packages/a2a-server/src/http/app.ts`)
- A2A HTTP API → Task executor: creates tasks (evidence: `packages/a2a-server/src/http/app.ts`)
- A2A HTTP API → Server commands: dispatches commands (evidence: `packages/a2a-server/src/http/app.ts`)
- A2A HTTP API → Server settings: loads settings (evidence: `packages/a2a-server/src/http/app.ts`)
- A2A HTTP API → Server configuration: loads configuration (evidence: `packages/a2a-server/src/http/app.ts`)
