# System map — google-gemini/gemini-cli

> Canonical page: https://codevetter.com/unpack/gemini-cli/system-map

# System map — google-gemini/gemini-cli

Scanned commit d5b3e3accb26000d273abf16e0f1dd83aa5428a9 (2026-09-21). Generated by codevetter codevetter 1.12.0 on 2026-09-22.

The repo is an npm workspaces monorepo (Node >=20, ESM, TypeScript 5.8) with the runtime split between packages/cli (Ink/React TUI, arg parsing, settings, extensions, sandboxing, ACP) and packages/core (agentic loop, tool registry, scheduler, policy engine, hooks, MCP client, telemetry). Secondary packages are a2a-server (Express A2A endpoint), sdk (programmatic sessions), vscode-ide-companion (IDE bridge), devtools (Vite React activity viewer), and test-utils. The shipped binary is produced by esbuild into bundle/gemini.js via the root `bundle` script. Runtime state lives under ~/.gemini (or GEMINI_CLI_HOME) via the Storage class; external integrations include the Gemini API / Code Assist / Vertex AI backends, arbitrary MCP servers, IDE companions over a local server, and git for worktrees/checkpointing.
- The published `gemini` bin is bundle/gemini.js, built by `npm run bundle` which runs esbuild.config.js after generating git-commit info and bundling devtools; per-package `npm run build` uses scripts/build_package.js. — [package.json#L47](https://github.com/google-gemini/gemini-cli/blob/d5b3e3accb26000d273abf16e0f1dd83aa5428a9/package.json#L47) [package.json#L92-94](https://github.com/google-gemini/gemini-cli/blob/d5b3e3accb26000d273abf16e0f1dd83aa5428a9/package.json#L92-L94) [esbuild.config.js](https://github.com/google-gemini/gemini-cli/blob/d5b3e3accb26000d273abf16e0f1dd83aa5428a9/esbuild.config.js) [scripts/build.js](https://github.com/google-gemini/gemini-cli/blob/d5b3e3accb26000d273abf16e0f1dd83aa5428a9/scripts/build.js)
- The true process entrypoint is packages/cli/index.ts run(): unless GEMINI_CLI_NO_RELAUNCH or SANDBOX is set it stays a lightweight parent that spawns `process.execPath` with IPC for admin-settings messages and loops on RELAUNCH_EXIT_CODE; only the child dynamically imports src/gemini.js main(). — [packages/cli/index.ts#L54-163](https://github.com/google-gemini/gemini-cli/blob/d5b3e3accb26000d273abf16e0f1dd83aa5428a9/packages/cli/index.ts#L54-L163) [packages/cli/src/utils/processUtils.ts](https://github.com/google-gemini/gemini-cli/blob/d5b3e3accb26000d273abf16e0f1dd83aa5428a9/packages/cli/src/utils/processUtils.ts)
- packages/cli/src/gemini.tsx main() is the heavy child orchestrator: patchStdio, unhandled-rejection/uncaught-exception handlers, loadSettings, optional worktree setup (process.chdir), parseArguments (yargs), resolveSessionId, loadCliConfig, refreshAuth, optional sandbox relaunch, then interactive UI or runNonInteractive. — [packages/cli/src/gemini.tsx#L466-1004](https://github.com/google-gemini/gemini-cli/blob/d5b3e3accb26000d273abf16e0f1dd83aa5428a9/packages/cli/src/gemini.tsx#L466-L1004) [packages/cli/src/config/config.ts](https://github.com/google-gemini/gemini-cli/blob/d5b3e3accb26000d273abf16e0f1dd83aa5428a9/packages/cli/src/config/config.ts)
- packages/core exposes its surface through src/index.ts; the Config class (config.ts, ~4200 lines) is the central god-object implementing McpContext and AgentLoopContext and owning the ToolRegistry, GeminiClient, McpClientManager, PolicyEngine, MessageBus, Storage, and HookSystem. — [packages/core/src/index.ts](https://github.com/google-gemini/gemini-cli/blob/d5b3e3accb26000d273abf16e0f1dd83aa5428a9/packages/core/src/index.ts) [packages/core/src/config/config.ts#L753-756](https://github.com/google-gemini/gemini-cli/blob/d5b3e3accb26000d273abf16e0f1dd83aa5428a9/packages/core/src/config/config.ts#L753-L756)
- Config._initialize() wires the runtime in order: storage, workspace context dirs, PromptRegistry/ResourceRegistry, AgentRegistry, createToolRegistry(), McpClientManager (started non-blockingly unless non-interactive/ACP), skills discovery, HookSystem, MemoryContextManager, and geminiClient.initialize(). — [packages/core/src/config/config.ts#L1450-1564](https://github.com/google-gemini/gemini-cli/blob/d5b3e3accb26000d273abf16e0f1dd83aa5428a9/packages/core/src/config/config.ts#L1450-L1564)
- The agentic core is GeminiClient.sendMessageStream → Turn.run → GeminiChat.sendMessageStream, yielding typed ServerGeminiStreamEvent values (Content, Thought, ToolCallRequest, Finished, LoopDetected, InvalidStream, AgentExecutionStopped/Blocked, ...). — [packages/core/src/core/client.ts#L910-1061](https://github.com/google-gemini/gemini-cli/blob/d5b3e3accb26000d273abf16e0f1dd83aa5428a9/packages/core/src/core/client.ts#L910-L1061) [packages/core/src/core/turn.ts#L55-74](https://github.com/google-gemini/gemini-cli/blob/d5b3e3accb26000d273abf16e0f1dd83aa5428a9/packages/core/src/core/turn.ts#L55-L74) [packages/core/src/core/turn.ts#L270-399](https://github.com/google-gemini/gemini-cli/blob/d5b3e3accb26000d273abf16e0f1dd83aa5428a9/packages/core/src/core/turn.ts#L270-L399) [packages/core/src/core/geminiChat.ts#L372](https://github.com/google-gemini/gemini-cli/blob/d5b3e3accb26000d273abf16e0f1dd83aa5428a9/packages/core/src/core/geminiChat.ts#L372)
- Model access is abstracted behind the ContentGenerator interface; createContentGenerator() picks FakeContentGenerator (test replay), Code Assist (OAuth/ADC via createCodeAssistContentGenerator wrapped in ModelMappingContentGenerator+LoggingContentGenerator), or @google/genai GoogleGenAI for API-key/Vertex/Gateway auth, with proxy agents, custom headers, and Vertex REP endpoints for us/eu. — [packages/core/src/core/contentGenerator.ts#L39-70](https://github.com/google-gemini/gemini-cli/blob/d5b3e3accb26000d273abf16e0f1dd83aa5428a9/packages/core/src/core/contentGenerator.ts#L39-L70) [packages/core/src/core/contentGenerator.ts#L210-422](https://github.com/google-gemini/gemini-cli/blob/d5b3e3accb26000d273abf16e0f1dd83aa5428a9/packages/core/src/core/contentGenerator.ts#L210-L422) [packages/core/src/code_assist/codeAssist.ts](https://github.com/google-gemini/gemini-cli/blob/d5b3e3accb26000d273abf16e0f1dd83aa5428a9/packages/core/src/code_assist/codeAssist.ts)
- Cross-layer signaling uses two buses: coreEvents, a process-wide EventEmitter with a CoreEvent enum (UserFeedback, Output, ConsoleLog, ModelChanged, ConsentRequest, ...), and a MessageBus (confirmation-bus) that carries tool-confirmation and policy-update messages to the UI. — [packages/core/src/utils/events.ts#L196-221](https://github.com/google-gemini/gemini-cli/blob/d5b3e3accb26000d273abf16e0f1dd83aa5428a9/packages/core/src/utils/events.ts#L196-L221) [packages/core/src/confirmation-bus/message-bus.ts](https://github.com/google-gemini/gemini-cli/blob/d5b3e3accb26000d273abf16e0f1dd83aa5428a9/packages/core/src/confirmation-bus/message-bus.ts) [packages/core/src/scheduler/scheduler.ts#L44-55](https://github.com/google-gemini/gemini-cli/blob/d5b3e3accb26000d273abf16e0f1dd83aa5428a9/packages/core/src/scheduler/scheduler.ts#L44-L55)
- Persistent state is rooted at ~/.gemini (GEMINI_DIR, overridable via GEMINI_CLI_HOME or tmpdir on some paths) managed by the Storage class; per-project data is namespaced by a hash of the project root. — [packages/core/src/config/storage.ts#L57-105](https://github.com/google-gemini/gemini-cli/blob/d5b3e3accb26000d273abf16e0f1dd83aa5428a9/packages/core/src/config/storage.ts#L57-L105) [packages/core/src/config/storage.ts#L204](https://github.com/google-gemini/gemini-cli/blob/d5b3e3accb26000d273abf16e0f1dd83aa5428a9/packages/core/src/config/storage.ts#L204) [packages/cli/index.ts#L26-28](https://github.com/google-gemini/gemini-cli/blob/d5b3e3accb26000d273abf16e0f1dd83aa5428a9/packages/cli/index.ts#L26-L28)
- packages/a2a-server is a separate Express app exposing an A2A-protocol agent card ('Gemini SDLC Agent') with bearer/basic auth schemes and pluggable TaskStore (InMemory/GCS/NoOp), reusing core via @google/gemini-cli-core. — [packages/a2a-server/src/http/app.ts#L45-120](https://github.com/google-gemini/gemini-cli/blob/d5b3e3accb26000d273abf16e0f1dd83aa5428a9/packages/a2a-server/src/http/app.ts#L45-L120) [packages/a2a-server/src/index.ts](https://github.com/google-gemini/gemini-cli/blob/d5b3e3accb26000d273abf16e0f1dd83aa5428a9/packages/a2a-server/src/index.ts) [packages/a2a-server/src/persistence/gcs.ts](https://github.com/google-gemini/gemini-cli/blob/d5b3e3accb26000d273abf16e0f1dd83aa5428a9/packages/a2a-server/src/persistence/gcs.ts)
- packages/sdk re-exports agent/session/tool/skills/fs helpers as a programmatic API, and packages/vscode-ide-companion runs an ide-server plus diff-manager/open-files-manager that the core connects to via IdeClient. — [packages/sdk/src/index.ts](https://github.com/google-gemini/gemini-cli/blob/d5b3e3accb26000d273abf16e0f1dd83aa5428a9/packages/sdk/src/index.ts) [packages/sdk/src/session.ts](https://github.com/google-gemini/gemini-cli/blob/d5b3e3accb26000d273abf16e0f1dd83aa5428a9/packages/sdk/src/session.ts) [packages/vscode-ide-companion/src/ide-server.ts](https://github.com/google-gemini/gemini-cli/blob/d5b3e3accb26000d273abf16e0f1dd83aa5428a9/packages/vscode-ide-companion/src/ide-server.ts) [packages/core/src/ide/ide-client.ts](https://github.com/google-gemini/gemini-cli/blob/d5b3e3accb26000d273abf16e0f1dd83aa5428a9/packages/core/src/ide/ide-client.ts)
- OS sandboxing is a first-class runtime boundary: the CLI can relaunch itself inside Docker/Podman images or macOS Seatbelt profiles (BUILTIN_SEATBELT_PROFILES/*.sb files) before doing expensive init, and per-command sandboxing is mediated by sandboxManager.prepareCommand in tools. — [packages/cli/src/gemini.tsx#L684-737](https://github.com/google-gemini/gemini-cli/blob/d5b3e3accb26000d273abf16e0f1dd83aa5428a9/packages/cli/src/gemini.tsx#L684-L737) [packages/cli/src/utils/sandbox.ts#L55-120](https://github.com/google-gemini/gemini-cli/blob/d5b3e3accb26000d273abf16e0f1dd83aa5428a9/packages/cli/src/utils/sandbox.ts#L55-L120) [packages/cli/src/utils/sandboxUtils.ts](https://github.com/google-gemini/gemini-cli/blob/d5b3e3accb26000d273abf16e0f1dd83aa5428a9/packages/cli/src/utils/sandboxUtils.ts) [packages/core/src/services/sandboxManager.ts](https://github.com/google-gemini/gemini-cli/blob/d5b3e3accb26000d273abf16e0f1dd83aa5428a9/packages/core/src/services/sandboxManager.ts) [packages/core/src/tools/tool-registry.ts#L404-416](https://github.com/google-gemini/gemini-cli/blob/d5b3e3accb26000d273abf16e0f1dd83aa5428a9/packages/core/src/tools/tool-registry.ts#L404-L416)

Every claim links to its cited files at the pinned commit. Citations identify source evidence; they do not establish runtime correctness. Independent CodeVetter scan — not reviewed by upstream maintainers.

## Public product links

- [CodeVetter](https://codevetter.com/)
- [Download](https://codevetter.com/download)
- [Documentation](https://codevetter.com/docs/)
- [Source](https://github.com/Codevetter/codevetter)