google-gemini/gemini-cli

An agent editing this repo should treat packages/core and packages/cli as separate layers (core must not import cli), keep the Config god-object edits minimal, route all tool gating through the PolicyEngine/MessageBus rather than ad-hoc checks, and always run the colocated vitest file plus typecheck before considering a change done. Build is `npm run bundle` (esbuild → bundle/gemini.js); quick dev loop is `npm run start` / `npm start -- -p '...'` after build. Conventions: ESM with .js import specifiers for .ts files, Apache license header enforced by eslint, debugLogger instead of console.*, proper-lockfile/proper JSONL append for session files. Traps: two-process relaunch means env changes need GEMINI_CLI_NO_RELAUNCH=1 to debug the real process; posttest triggers a full build; Ink is a forked package via npm overrides.

• Read-first files for any agentic-loop change: packages/core/src/core/client.ts (GeminiClient), turn.ts (event types Turn/GeminiEventType), geminiChat.ts (stream+retry), scheduler/scheduler.ts (tool execution), config/config.ts (wiring). CLI-side entry: packages/cli/index.ts then src/gemini.tsx main().
  packages/core/src/core/client.tspackages/core/src/core/turn.tspackages/core/src/scheduler/scheduler.tspackages/cli/src/gemini.tsx
• Build/dev commands: `npm run bundle` produces bundle/gemini.js (esbuild, includes generated git commit info and devtools bundle); `npm run start` runs scripts/start.js with NODE_ENV=development; `npm run build` builds packages only.
  package.json#L20-47esbuild.config.jsscripts/start.jsscripts/build.js
• Test commands: `npm run test:ci --workspace @google/gemini-cli-core` for core unit tests; `npm run test:integration:sandbox:none` for e2e without sandbox; `npm run typecheck` across workspaces; `npm run preflight` = clean+ci+format+build+lint+typecheck+test:ci (slow, full gate).
  package.json#L48-72.github/workflows/ci.yml#L188-194CONTRIBUTING.md
• Imports must use ESM `.js` specifiers referencing the compiled names (e.g. './utils/cleanup.js'), the repo is "type":"module" everywhere, and every file needs the SPDX Apache header enforced by eslint-plugin-headers.
  package.json#L7packages/cli/src/gemini.tsx#L43-101package.json#L126
• Logging convention: never use console.log/console.error in library paths — ConsolePatcher intercepts them; use debugLogger (debug/error/warn) for diagnostics and coreEvents.emitFeedback for user-facing messages so headless JSON output stays clean.
  packages/cli/src/ui/utils/ConsolePatcher.tspackages/cli/src/gemini.tsx#L583-592packages/core/src/utils/events.ts
• Tool-approval changes must go through the PolicyEngine + MessageBus confirmation flow (checkPolicy → resolveConfirmation → MessageBusType.ToolConfirmationRequest); bypassing it (e.g. auto-executing in a new tool) defeats --approval-mode/--yolo/plan-mode semantics and enterprise admin policies.
  packages/core/src/scheduler/scheduler.ts#L10-13packages/core/src/scheduler/policy.tspackages/core/src/confirmation-bus/types.tspackages/core/src/policy/policy-engine.ts
• Safe edit boundaries: new tools go in packages/core/src/tools/ + registration in config.ts createToolRegistry; new slash commands in packages/cli/src/ui/commands/ + BuiltinCommandLoader; new settings keys in settingsSchema.ts (docs regenerated via npm run docs:settings, which CI verifies with --check).
  packages/core/src/config/config.ts#L3966-4087packages/cli/src/services/BuiltinCommandLoader.ts#L123-240packages/cli/src/config/settingsSchema.tspackage.json#L32-34.github/workflows/ci.yml#L116-119
• Debugging trap: the CLI double-forks — the visible process is a thin parent; to debug or test the real logic run with GEMINI_CLI_NO_RELAUNCH=1 (or `npm run debug` which uses --inspect-brk), otherwise breakpoints attach to the wrong process and stdin/stdio patching differs.
  packages/cli/index.ts#L54-56packages/cli/src/gemini.tsx#L138-140package.json#L23
• Trap: `npm test` at the root runs a build afterwards (posttest → npm run build) and the prepare script runs `husky && npm run bundle`, so npm install/test are not side-effect-free; the package-lock is guarded by check:lockfile in CI.
  package.json#L52package.json#L73package.json#L77.github/workflows/ci.yml#L89
• Layering rule: packages/cli depends on @google/gemini-cli-core (file:../core) and everything cross-layer is exported through packages/core/src/index.ts; a2a-server and sdk also consume core only through that barrel — new core APIs must be re-exported there to be usable.
  packages/cli/package.json#L34packages/core/src/index.tspackages/a2a-server/src/http/app.ts#L29-35packages/sdk/package.json
• Ink is pinned to a fork (@jrichman/ink@6.6.9) via npm overrides with wrap-ansi/cliui pinned too — do not upgrade ink casually; TUI tests rely on the fork's behavior (react-devtools-core in devDeps).
  package.json#L81-86package.json#L143
• Session transcript writes must remain append-only JSONL with proper record shapes (MessageRecord/$set/$rewindTo/$partial metadata guards in chatRecordingService); --resume and rewind depend on parsing these exact line types.
  packages/core/src/services/chatRecordingService.ts#L76-98packages/cli/src/gemini.tsx#L336-407
• Enterprise/admin settings arrive via parent→child IPC and CCPA fetch in refreshAuth; features must consult admin flags (e.g. getAdminBlockedMcpServersMessage, adminSkillsEnabled, applyAdminAllowlist) rather than only user settings, or enterprise controls are bypassed.
  packages/cli/src/gemini.tsx#L669-679packages/cli/src/config/extension-manager.ts#L55-56packages/core/src/config/config.ts#L1534-1550docs/admin/enterprise-controls.md