gemini-cli/GEMINI.md

Gemini CLI Project Context

Gemini CLI is an open-source AI agent that brings the power of Gemini directly into the terminal. It is designed to be a terminal-first, extensible, and powerful tool for developers.

Project Overview

• Purpose: Provide a seamless terminal interface for Gemini models, supporting code understanding, generation, automation, and integration via MCP (Model Context Protocol).
• Main Technologies:
  • Runtime: Node.js (>=20.0.0, recommended ~20.19.0 for development)
  • Language: TypeScript
  • UI Framework: React (using Ink for CLI rendering)
  • Testing: Vitest
  • Bundling: esbuild
  • Linting/Formatting: ESLint, Prettier
• Architecture: Monorepo structure using npm workspaces.
  • packages/cli: User-facing terminal UI, input processing, and display rendering.
  • packages/core: Backend logic, Gemini API orchestration, prompt construction, and tool execution.
  • packages/a2a-server: Experimental Agent-to-Agent server.
  • packages/sdk: Programmatic SDK for embedding Gemini CLI capabilities.
  • packages/devtools: Integrated developer tools (Network/Console inspector).
  • packages/test-utils: Shared test utilities and test rig.
  • packages/vscode-ide-companion: VS Code extension pairing with the CLI.

Building and Running

• Install Dependencies: npm install
• Build All: npm run build:all (Builds packages, sandbox, and VS Code companion)
• Build Packages: npm run build
• Run in Development: npm run start
• Run in Debug Mode: npm run debug (Enables Node.js inspector)
• Bundle Project: npm run bundle
• Clean Artifacts: npm run clean

Testing and Quality

• Test Commands:
  • Unit (All): npm run test
  • Integration (E2E): npm run test:e2e

  • Note

    : Please run the memory and perf tests locally only if you are implementing changes related to those test areas. Otherwise skip these tests locally and rely on CI to run them on nightly builds.

  • Memory (Nightly): npm run test:memory (Runs memory regression tests against baselines. Excluded from preflight, run nightly.)
  • Performance (Nightly): npm run test:perf (Runs CPU performance regression tests against baselines. Excluded from preflight, run nightly.)
  • Workspace-Specific: npm test -w <pkg> -- <path> (Note: <path> must be relative to the workspace root, e.g., -w @google/gemini-cli-core -- src/routing/modelRouterService.test.ts)
• Full Validation: npm run preflight (Heaviest check; runs clean, install, build, lint, type check, and tests. Recommended before submitting PRs. Due to its long runtime, only run this at the very end of a code implementation task. If it fails, use faster, targeted commands (e.g., npm run test, npm run lint, or workspace-specific tests) to iterate on fixes before re-running preflight. For simple, non-code changes like documentation or prompting updates, skip preflight at the end of the task and wait for PR validation.)
• Individual Checks: npm run lint / npm run format / npm run typecheck

Development Conventions

• Contributions: Follow the process outlined in CONTRIBUTING.md. Requires signing the Google CLA.
• Pull Requests: Keep PRs small, focused, and linked to an existing issue. Always activate the pr-creator skill for PR generation, even when using the gh CLI.
• Commit Messages: Follow the Conventional Commits standard.
• Imports: Use specific imports and avoid restricted relative imports between packages (enforced by ESLint).
• License Headers: For all new source code files (.ts, .tsx, .js), include the Apache-2.0 license header with the current year. (e.g., Copyright 2026 Google LLC). This is enforced by ESLint.

Testing Conventions

• Environment Variables: When testing code that depends on environment variables, use vi.stubEnv('NAME', 'value') in beforeEach and vi.unstubAllEnvs() in afterEach. Avoid modifying process.env directly as it can lead to test leakage and is less reliable. To "unset" a variable, use an empty string vi.stubEnv('NAME', '').

Documentation

• Always use the docs-writer skill when you are asked to write, edit, or review any documentation.
• Documentation is located in the docs/ directory.
• Suggest documentation updates when code changes render existing documentation obsolete or incomplete.