feat(cli): add streamlined gemini gemma local model setup

docs/cli/settings.md

@@ -161,17 +161,19 @@ they appear in the UI.
 
 ### Experimental
 
-| UI Label                                             | Setting                          | Description                                                                                                                                               | Default |
-| ---------------------------------------------------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
-| Enable Git Worktrees                                 | `experimental.worktrees`         | Enable automated Git worktree management for parallel work.                                                                                               | `false` |
-| Use OSC 52 Paste                                     | `experimental.useOSC52Paste`     | Use OSC 52 for pasting. This may be more robust than the default system when using remote terminal sessions (if your terminal is configured to allow it). | `false` |
-| Use OSC 52 Copy                                      | `experimental.useOSC52Copy`      | Use OSC 52 for copying. This may be more robust than the default system when using remote terminal sessions (if your terminal is configured to allow it). | `false` |
-| Model Steering                                       | `experimental.modelSteering`     | Enable model steering (user hints) to guide the model during tool execution.                                                                              | `false` |
-| Direct Web Fetch                                     | `experimental.directWebFetch`    | Enable web fetch behavior that bypasses LLM summarization.                                                                                                | `false` |
-| Memory Manager Agent                                 | `experimental.memoryManager`     | Replace the built-in save_memory tool with a memory manager subagent that supports adding, removing, de-duplicating, and organizing memories.             | `false` |
-| Auto Memory                                          | `experimental.autoMemory`        | Automatically extract reusable skills from past sessions in the background. Review results with /memory inbox.                                            | `false` |
-| Use the generalist profile to manage agent contexts. | `experimental.generalistProfile` | Suitable for general coding and software development tasks.                                                                                               | `false` |
-| Enable Context Management                            | `experimental.contextManagement` | Enable logic for context management.                                                                                                                      | `false` |
+| UI Label                                             | Setting                                         | Description                                                                                                                                               | Default |
+| ---------------------------------------------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
+| Enable Git Worktrees                                 | `experimental.worktrees`                        | Enable automated Git worktree management for parallel work.                                                                                               | `false` |
+| Use OSC 52 Paste                                     | `experimental.useOSC52Paste`                    | Use OSC 52 for pasting. This may be more robust than the default system when using remote terminal sessions (if your terminal is configured to allow it). | `false` |
+| Use OSC 52 Copy                                      | `experimental.useOSC52Copy`                     | Use OSC 52 for copying. This may be more robust than the default system when using remote terminal sessions (if your terminal is configured to allow it). | `false` |
+| Model Steering                                       | `experimental.modelSteering`                    | Enable model steering (user hints) to guide the model during tool execution.                                                                              | `false` |
+| Direct Web Fetch                                     | `experimental.directWebFetch`                   | Enable web fetch behavior that bypasses LLM summarization.                                                                                                | `false` |
+| Enable Gemma Model Router                            | `experimental.gemmaModelRouter.enabled`         | Enable the Gemma Model Router (experimental). Requires a local endpoint serving Gemma via the Gemini API using LiteRT-LM shim.                            | `false` |
+| Auto-start LiteRT Server                             | `experimental.gemmaModelRouter.autoStartServer` | Automatically start the LiteRT-LM server when Gemini CLI starts and the Gemma router is enabled.                                                          | `false` |
+| Memory Manager Agent                                 | `experimental.memoryManager`                    | Replace the built-in save_memory tool with a memory manager subagent that supports adding, removing, de-duplicating, and organizing memories.             | `false` |
+| Auto Memory                                          | `experimental.autoMemory`                       | Automatically extract reusable skills from past sessions in the background. Review results with /memory inbox.                                            | `false` |
+| Use the generalist profile to manage agent contexts. | `experimental.generalistProfile`                | Suitable for general coding and software development tasks.                                                                                               | `false` |
+| Enable Context Management                            | `experimental.contextManagement`                | Enable logic for context management.                                                                                                                      | `false` |
 
 ### Skills
 

docs/reference/configuration.md

@@ -1711,6 +1711,18 @@ their corresponding top-level category object in your `settings.json` file.
   - **Default:** `false`
   - **Requires restart:** Yes
 
+- **`experimental.gemmaModelRouter.autoStartServer`** (boolean):
+  - **Description:** Automatically start the LiteRT-LM server when Gemini CLI
+    starts and the Gemma router is enabled.
+  - **Default:** `false`
+  - **Requires restart:** Yes
+
+- **`experimental.gemmaModelRouter.binaryPath`** (string):
+  - **Description:** Custom path to the LiteRT-LM binary. Leave empty to use the
+    default location (~/.gemini/bin/litert/).
+  - **Default:** `""`
+  - **Requires restart:** Yes
+
 - **`experimental.gemmaModelRouter.classifier.host`** (string):
   - **Description:** The host of the classifier.
   - **Default:** `"http://localhost:9379"`

packages/cli/src/commands/gemma.ts

@@ -0,0 +1,33 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { CommandModule, Argv } from 'yargs';
+import { initializeOutputListenersAndFlush } from '../gemini.js';
+import { defer } from '../deferred.js';
+import { setupCommand } from './gemma/setup.js';
+import { startCommand } from './gemma/start.js';
+import { stopCommand } from './gemma/stop.js';
+import { statusCommand } from './gemma/status.js';
+import { logsCommand } from './gemma/logs.js';
+
+export const gemmaCommand: CommandModule = {
+  command: 'gemma',
+  describe: 'Manage local Gemma model routing',
+  builder: (yargs: Argv) =>
+    yargs
+      .middleware((argv) => {
+        initializeOutputListenersAndFlush();
+        argv['isCommand'] = true;
+      })
+      .command(defer(setupCommand, 'gemma'))
+      .command(defer(startCommand, 'gemma'))
+      .command(defer(stopCommand, 'gemma'))
+      .command(defer(statusCommand, 'gemma'))
+      .command(defer(logsCommand, 'gemma'))
+      .demandCommand(1, 'You need at least one command before continuing.')
+      .version(false),
+  handler: () => {},
+};

packages/cli/src/commands/gemma/constants.ts

@@ -0,0 +1,45 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import path from 'node:path';
+import { Storage } from '@google/gemini-cli-core';
+
+export const LITERT_RELEASE_VERSION = 'v0.9.0-alpha03';
+export const LITERT_RELEASE_BASE_URL =
+  'https://github.com/google-ai-edge/LiteRT-LM/releases/download';
+export const GEMMA_MODEL_NAME = 'gemma3-1b-gpu-custom';
+export const DEFAULT_PORT = 9379;
+export const HEALTH_CHECK_TIMEOUT_MS = 5000;
+export const LITERT_API_VERSION = 'v1beta';
+export const SERVER_START_WAIT_MS = 3000;
+
+export const PLATFORM_BINARY_MAP: Record<string, string> = {
+  'darwin-arm64': 'lit.macos_arm64',
+  'linux-x64': 'lit.linux_x86_64',
+  'win32-x64': 'lit.windows_x86_64.exe',
+};
+
+// SHA-256 hashes for the official LiteRT-LM v0.9.0-alpha03 release binaries.
+export const PLATFORM_BINARY_SHA256: Record<string, string> = {
+  'lit.macos_arm64':
+    '9e826a2634f2e8b220ad0f1e1b5c139e0b47cb172326e3b7d46d31382f49478e',
+  'lit.linux_x86_64':
+    '66601df8a07f08244b188e9fcab0bf4a16562fe76d8d47e49f40273d57541ee8',
+  'lit.windows_x86_64.exe':
+    'de82d2829d2fb1cbdb318e2d8a78dc2f9659ff14cb11b2894d1f30e0bfde2bf6',
+};
+
+export function getLiteRtBinDir(): string {
+  return path.join(Storage.getGlobalGeminiDir(), 'bin', 'litert');
+}
+
+export function getPidFilePath(): string {
+  return path.join(Storage.getGlobalTempDir(), 'litert-server.pid');
+}
+
+export function getLogFilePath(): string {
+  return path.join(Storage.getGlobalTempDir(), 'litert-server.log');
+}

packages/cli/src/commands/gemma/logs.test.ts

@@ -0,0 +1,186 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import fs from 'node:fs';
+import type { ChildProcess } from 'node:child_process';
+import { EventEmitter } from 'node:events';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { spawn } from 'node:child_process';
+import { exitCli } from '../utils.js';
+import { getLogFilePath } from './constants.js';
+import { logsCommand, readLastLines } from './logs.js';
+
+vi.mock('@google/gemini-cli-core', async (importOriginal) => {
+  const { mockCoreDebugLogger } = await import(
+    '../../test-utils/mockDebugLogger.js'
+  );
+  return mockCoreDebugLogger(
+    await importOriginal<typeof import('@google/gemini-cli-core')>(),
+    {
+      stripAnsi: false,
+    },
+  );
+});
+
+vi.mock('node:child_process', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('node:child_process')>();
+  return {
+    ...actual,
+    spawn: vi.fn(),
+  };
+});
+
+vi.mock('../utils.js', () => ({
+  exitCli: vi.fn(),
+}));
+
+vi.mock('./constants.js', () => ({
+  getLogFilePath: vi.fn(),
+}));
+
+function createMockChild(): ChildProcess {
+  return Object.assign(new EventEmitter(), {
+    kill: vi.fn(),
+  }) as unknown as ChildProcess;
+}
+
+async function flushMicrotasks() {
+  await Promise.resolve();
+  await Promise.resolve();
+}
+
+describe('readLastLines', () => {
+  const tempFiles: string[] = [];
+
+  afterEach(async () => {
+    await Promise.all(
+      tempFiles
+        .splice(0)
+        .map((filePath) => fs.promises.rm(filePath, { force: true })),
+    );
+  });
+
+  it('returns only the requested tail lines without reading the whole file eagerly', async () => {
+    const filePath = path.join(
+      os.tmpdir(),
+      `gemma-logs-${Date.now()}-${Math.random().toString(36).slice(2)}.log`,
+    );
+    tempFiles.push(filePath);
+
+    const content = Array.from({ length: 2000 }, (_, i) => `line-${i + 1}`)
+      .join('\n')
+      .concat('\n');
+    await fs.promises.writeFile(filePath, content, 'utf-8');
+
+    await expect(readLastLines(filePath, 3)).resolves.toBe(
+      'line-1998\nline-1999\nline-2000\n',
+    );
+  });
+
+  it('returns an empty string when zero lines are requested', async () => {
+    const filePath = path.join(
+      os.tmpdir(),
+      `gemma-logs-${Date.now()}-${Math.random().toString(36).slice(2)}.log`,
+    );
+    tempFiles.push(filePath);
+    await fs.promises.writeFile(filePath, 'line-1\nline-2\n', 'utf-8');
+
+    await expect(readLastLines(filePath, 0)).resolves.toBe('');
+  });
+});
+
+describe('logsCommand', () => {
+  const originalPlatform = process.platform;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    Object.defineProperty(process, 'platform', {
+      value: 'linux',
+      configurable: true,
+    });
+    vi.mocked(getLogFilePath).mockReturnValue('/tmp/gemma.log');
+    vi.spyOn(fs.promises, 'access').mockResolvedValue(undefined);
+  });
+
+  afterEach(() => {
+    Object.defineProperty(process, 'platform', {
+      value: originalPlatform,
+      configurable: true,
+    });
+    vi.restoreAllMocks();
+  });
+
+  it('waits for the tail process to close before exiting in follow mode', async () => {
+    const child = createMockChild();
+    vi.mocked(spawn).mockReturnValue(child);
+
+    let resolved = false;
+    const handlerPromise = (
+      logsCommand.handler as (argv: Record<string, unknown>) => Promise<void>
+    )({}).then(() => {
+      resolved = true;
+    });
+
+    await flushMicrotasks();
+
+    expect(spawn).toHaveBeenCalledWith(
+      'tail',
+      ['-f', '-n', '20', '/tmp/gemma.log'],
+      { stdio: 'inherit' },
+    );
+    expect(resolved).toBe(false);
+    expect(exitCli).not.toHaveBeenCalled();
+
+    child.emit('close', 0);
+    await handlerPromise;
+
+    expect(exitCli).toHaveBeenCalledWith(0);
+  });
+
+  it('uses one-shot tail output when follow is disabled', async () => {
+    const child = createMockChild();
+    vi.mocked(spawn).mockReturnValue(child);
+
+    const handlerPromise = (
+      logsCommand.handler as (argv: Record<string, unknown>) => Promise<void>
+    )({ follow: false });
+
+    await flushMicrotasks();
+
+    expect(spawn).toHaveBeenCalledWith('tail', ['-n', '20', '/tmp/gemma.log'], {
+      stdio: 'inherit',
+    });
+
+    child.emit('close', 0);
+    await handlerPromise;
+
+    expect(exitCli).toHaveBeenCalledWith(0);
+  });
+
+  it('follows from the requested line count when both --lines and --follow are set', async () => {
+    const child = createMockChild();
+    vi.mocked(spawn).mockReturnValue(child);
+
+    const handlerPromise = (
+      logsCommand.handler as (argv: Record<string, unknown>) => Promise<void>
+    )({ lines: 5, follow: true });
+
+    await flushMicrotasks();
+
+    expect(spawn).toHaveBeenCalledWith(
+      'tail',
+      ['-f', '-n', '5', '/tmp/gemma.log'],
+      { stdio: 'inherit' },
+    );
+
+    child.emit('close', 0);
+    await handlerPromise;
+
+    expect(exitCli).toHaveBeenCalledWith(0);
+  });
+});