gemini-cli/docs/codebase_understanding_antigrav.md

Gemini CLI - Codebase Understanding

Gemini CLI is an open-source AI agent designed to let you interact with Google's Gemini models directly from your terminal. It's built as a TypeScript monorepo (using npm workspaces) and relies heavily on Node.js, React, and Ink (a library that lets you build terminal UIs using React components).

Here is a high-level walkthrough of the repository to help you understand how all the pieces fit together.

1. High-Level Architecture (The packages/ Directory)

The project is split into several focused packages to maintain a clean separation of concerns:

• packages/cli (The Frontend)
  • This is the user-facing terminal UI.
  • It uses React + Ink. This means the terminal layout, styling, and interactions are managed like a modern web app (with hooks, contexts, and components).
  • It handles all the terminal-specific logic like key bindings, processing mouse/keyboard events, and rendering the chat stream or tool progress indicators.
• packages/core (The Brain/Backend)
  • This is where the actual "agentic" logic lives. It is entirely UI-agnostic.
  • Contains the core looping mechanism that communicates with the Gemini API, maintains conversation history, compresses context, and evaluates whether the agent needs to invoke a tool.
  • Houses the Tool Registry (file system tools, shell runner, web tools) and the Policy Engine (deciding if a tool is safe to run automatically or needs your permission).
• packages/devtools
  • A Chrome DevTools-like web server that runs locally! If you enable general.devtools in your settings, you can inspect network requests, agent thoughts, and console logs in a local browser, just like you would for a web app.
• packages/vscode-ide-companion
  • A VS Code extension that pairs dynamically with the CLI. It allows the terminal agent to "read" your active editor state, seamlessly pulling context on exactly what files or lines of code you currently have highlighted in VS Code.
• packages/sdk
  • Provides libraries and types so people can build custom MCP (Model Context Protocol) extensions or tools for the CLI.
• packages/a2a-server
  • An experimental Agent-to-Agent server, hinting at future capabilities for having different agents talk to each other.

2. The Core Application Lifecycle

When you type gemini in your terminal, here's roughly what happens under the hood:

1. Bootstrapping (packages/cli/src/gemini.tsx): The CLI loads user configurations, parses command-line arguments, checks authentication, and verifies if it needs to launch itself in a controlled "sandbox" environment (using Docker/Podman to isolate dangerous shell tools).
2. Mode Resolution: It determines if you are piping data in or running a single command (nonInteractiveCli.ts), or if you are firing up the chat TUI (Terminal User Interface).
3. The Agent Loop (packages/core/src/core/):
   • GeminiClient: The main orchestrator. It manages sessions and compresses chat histories using ChatCompressionService so you don't breach token limits.
   • GeminiChat & Turn: For every prompt you send, a Turn is created. This represents one "exchange" where the model might think, respond, and realize it needs to search your codebase. It streams these requests back in real-time.

3. The Tool System & Execution

The most powerful aspect of this CLI is its ability to interact with your environment.

• In packages/core/src/tools/, there are native TypeScript implementations for operations (like reading files, searching directories, or running tests).
• When Gemini asks to use a tool, the Scheduler (packages/core/src/scheduler/) intercepts the request.
• It runs the request through the Policy Engine (packages/core/src/policy/). Some commands (like rm -rf) are flagged and routed to a Confirmation Bus, which pauses execution and asks you in the UI: "Do you want to allow this command?"
• Once approved (or auto-approved), it executes the tool, captures standard output/error, and pipes that text back to Gemini to continue its thought process.

4. Code Quality, Building, and Testing

• Bundling & Running: The project uses esbuild to compile everything very quickly. During development, you can use npm run start or npm run debug (which attaches a Node.js inspector).
• Testing (vitest): Testing is extremely rigorous here.
  • Unit Tests: npm run test handles basic component functionality.
  • Integration Tests: npm run test:e2e simulates an actual sandbox, mocking/hitting models to make sure the CLI interacts realistically.
  • Evals (evals/): Standalone performance benchmarks where they evaluate how smart the CLI is at navigating codebases or using its tools autonomously.
• npm run preflight: Before a PR is pushed, this massive script runs formatting (Prettier), linting (ESLint), type checking (TypeScript), unit testing, and building, ensuring nothing breaks the main branch.