GEMINI.md

1# Gemini CLI Project Context
2 
3Gemini CLI is an open-source AI agent that brings the power of Gemini directly
4into the terminal. It is designed to be a terminal-first, extensible, and
5powerful tool for developers.
6 
7## Project Overview
8 
9- **Purpose:** Provide a seamless terminal interface for Gemini models,
10  supporting code understanding, generation, automation, and integration via MCP
11  (Model Context Protocol).
12- **Main Technologies:**
13  - **Runtime:** Node.js (>=20.0.0, recommended ~20.19.0 for development)
14  - **Language:** TypeScript
15  - **UI Framework:** React (using [Ink](https://github.com/vadimdemedes/ink)
16    for CLI rendering)
17  - **Testing:** Vitest
18  - **Bundling:** esbuild
19  - **Linting/Formatting:** ESLint, Prettier
20- **Architecture:** Monorepo structure using npm workspaces.
21  - `packages/cli`: User-facing terminal UI, input processing, and display
22    rendering.
23  - `packages/core`: Backend logic, Gemini API orchestration, prompt
24    construction, and tool execution.
25  - `packages/a2a-server`: Experimental Agent-to-Agent server.
26  - `packages/sdk`: Programmatic SDK for embedding Gemini CLI capabilities.
27  - `packages/devtools`: Integrated developer tools (Network/Console inspector).
28  - `packages/test-utils`: Shared test utilities and test rig.
29  - `packages/vscode-ide-companion`: VS Code extension pairing with the CLI.
30 
31## Building and Running
32 
33- **Install Dependencies:** `npm install`
34- **Build All:** `npm run build:all` (Builds packages, sandbox, and VS Code
35  companion)
36- **Build Packages:** `npm run build`
37- **Run in Development:** `npm run start`
38- **Run in Debug Mode:** `npm run debug` (Enables Node.js inspector)
39- **Bundle Project:** `npm run bundle`
40- **Clean Artifacts:** `npm run clean`
41 
42## Testing and Quality
43 
44- **Test Commands:**
45  - **Unit (All):** `npm run test`
46  - **Integration (E2E):** `npm run test:e2e`
47  - > **NOTE**: Please run the memory and perf tests locally **only if** you are
48    > implementing changes related to those test areas. Otherwise skip these
49    > tests locally and rely on CI to run them on nightly builds.
50  - **Memory (Nightly):** `npm run test:memory` (Runs memory regression tests
51    against baselines. Excluded from `preflight`, run nightly.)
52  - **Performance (Nightly):** `npm run test:perf` (Runs CPU performance
53    regression tests against baselines. Excluded from `preflight`, run nightly.)
54  - **Workspace-Specific:** `npm test -w <pkg> -- <path>` (Note: `<path>` must
55    be relative to the workspace root, e.g.,
56    `-w @google/gemini-cli-core -- src/routing/modelRouterService.test.ts`)
57- **Full Validation:** `npm run preflight` (Heaviest check; runs clean, install,
58  build, lint, type check, and tests. Recommended before submitting PRs. Due to
59  its long runtime, only run this at the very end of a code implementation task.
60  If it fails, use faster, targeted commands (e.g., `npm run test`,
61  `npm run lint`, or workspace-specific tests) to iterate on fixes before
62  re-running `preflight`. For simple, non-code changes like documentation or
63  prompting updates, skip `preflight` at the end of the task and wait for PR
64  validation.)
65- **Individual Checks:** `npm run lint` / `npm run format` / `npm run typecheck`
66 
67## Development Conventions
68 
69- **Contributions:** Follow the process outlined in `CONTRIBUTING.md`. Requires
70  signing the Google CLA.
71- **Pull Requests:** Keep PRs small, focused, and linked to an existing issue.
72  Always activate the `pr-creator` skill for PR generation, even when using the
73  `gh` CLI.
74- **Commit Messages:** Follow the
75  [Conventional Commits](https://www.conventionalcommits.org/) standard.
76- **Imports:** Use specific imports and avoid restricted relative imports
77  between packages (enforced by ESLint).
78- **License Headers:** For all new source code files (`.ts`, `.tsx`, `.js`),
79  include the Apache-2.0 license header with the current year. (e.g.,
80  `Copyright 2026 Google LLC`). This is enforced by ESLint.
81 
82## Testing Conventions
83 
84- **Environment Variables:** When testing code that depends on environment
85  variables, use `vi.stubEnv('NAME', 'value')` in `beforeEach` and
86  `vi.unstubAllEnvs()` in `afterEach`. Avoid modifying `process.env` directly as
87  it can lead to test leakage and is less reliable. To "unset" a variable, use
88  an empty string `vi.stubEnv('NAME', '')`.
89 
90## Documentation
91 
92- Always use the `docs-writer` skill when you are asked to write, edit, or
93  review any documentation.
94- Documentation is located in the `docs/` directory.
95- Suggest documentation updates when code changes render existing documentation
96  obsolete or incomplete.
97