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/core/src/tools/: Built-in tools for file system, shell, and web operations.
  • packages/a2a-server: Experimental Agent-to-Agent server.
  • 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
  • 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.)
• 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.
• Commit Messages: Follow the Conventional Commits standard.
• Coding Style: Adhere to existing patterns in packages/cli (React/Ink) and packages/core (Backend logic).
• Imports: Use specific imports and avoid restricted relative imports between packages (enforced by ESLint).

Documentation

• Located in the docs/ directory.
• Architecture overview: docs/architecture.md.
• Contribution guide: CONTRIBUTING.md.
• Documentation is organized via docs/sidebar.json.
• Follows the Google Developer Documentation Style Guide.