or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

configuration.mdcore-ai.mdide-integration.mdindex.mdmcp-oauth.mdservices.mdtelemetry.mdtools.mdutilities.md
tile.json

tessl/npm-google--gemini-cli-core

Gemini CLI Core - Core functionality library for the open-source AI agent that brings the power of Gemini directly into your terminal.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@google/gemini-cli-core@0.5.x

To install, run

npx @tessl/cli install tessl/npm-google--gemini-cli-core@0.5.0

index.mddocs/

Gemini CLI Core

Gemini CLI Core is a comprehensive TypeScript library that provides the foundational components for building AI-powered applications with Google's Gemini models. It offers a complete toolkit for content generation, tool execution, configuration management, and IDE integration, making it the core engine for sophisticated AI agent implementations.

Package Information

  • Package Name: @google/gemini-cli-core
  • Package Type: npm
  • Language: TypeScript
  • Version: 0.5.4
  • Installation: npm install @google/gemini-cli-core

Core Imports

// Main client and configuration
import { GeminiClient, Config } from '@google/gemini-cli-core';

// Content generation
import { 
  createContentGenerator, 
  createContentGeneratorConfig,
  AuthType 
} from '@google/gemini-cli-core';

// Tools and utilities
import { 
  DeclarativeTool, 
  BaseToolInvocation,
  ToolResult 
} from '@google/gemini-cli-core';

// Services
import { 
  FileDiscoveryService, 
  Storage 
} from '@google/gemini-cli-core';

CommonJS:

const { 
  GeminiClient, 
  Config, 
  createContentGenerator 
} = require('@google/gemini-cli-core');

Basic Usage

import {
  Config,
  GeminiClient,
  AuthType
} from '@google/gemini-cli-core';

// Initialize configuration with required parameters
const config = new Config({
  sessionId: 'example-session',
  targetDir: process.cwd(),
  debugMode: false,
  cwd: process.cwd(),
  model: 'gemini-1.5-flash'
});

// Initialize configuration and client
await config.initialize();
const client = config.getGeminiClient();

// Generate content with proper parameters
const contents = [{
  role: 'user' as const,
  parts: [{ text: 'Explain quantum computing' }]
}];

const response = await client.generateContent(
  contents,
  {}, // generation config
  new AbortController().signal,
  'gemini-1.5-flash'
);

console.log(response.text());

// Use chat session
const chat = await client.startChat();
const result = await chat.sendMessage(
  { message: 'List files in the current directory' },
  'prompt-id-123'
);

Architecture

Gemini CLI Core is built around several key architectural components:

  • Configuration System: Centralized configuration management with support for multiple authentication methods, tool approval modes, and extensibility
  • Content Generation Layer: Abstracted content generation with support for multiple providers (Gemini API, Vertex AI, Cloud Shell)
  • Tool Execution Framework: Declarative tool system with validation, confirmation workflows, and extensible tool registry
  • Chat Management: Stateful conversation handling with history management, compression, and turn-based execution
  • Service Architecture: Modular services for file discovery, git operations, shell execution, and IDE integration
  • Telemetry System: Comprehensive logging and metrics collection with OpenTelemetry integration

Capabilities

Configuration and Setup

Comprehensive configuration management with support for different authentication methods, tool approval modes, and extensibility settings.

class Config {
  constructor(parameters?: ConfigParameters);
  
  // Core configuration methods
  getModel(): string;
  setModel(model: string): void;
  getApiKey(): string | undefined;
  setApiKey(key: string): void;
}

enum AuthType {
  LOGIN_WITH_GOOGLE = 'oauth-personal',
  USE_GEMINI = 'gemini-api-key',
  USE_VERTEX_AI = 'vertex-ai',
  CLOUD_SHELL = 'cloud-shell'
}

enum ApprovalMode {
  DEFAULT = 'default',
  AUTO_EDIT = 'autoEdit',
  YOLO = 'yolo'
}

Configuration

Core AI Functionality

Powerful AI content generation and chat management with streaming support, tool integration, and conversation history management.

class GeminiClient {
  constructor(config: Config);

  initialize(): Promise<void>;
  isInitialized(): boolean;
  startChat(extraHistory?: Content[]): Promise<GeminiChat>;
  generateContent(
    contents: Content[],
    generationConfig: GenerateContentConfig,
    abortSignal: AbortSignal,
    model: string
  ): Promise<GenerateContentResponse>;
  generateJson<T>(
    contents: Content[],
    schema: Record<string, unknown>,
    abortSignal: AbortSignal,
    model: string,
    generationConfig?: GenerateContentConfig
  ): Promise<T>;
  sendMessageStream(message: string): AsyncGenerator<GeminiEvent>;
}

class GeminiChat {
  sendMessage(message: string | Part[]): Promise<GenerateContentResult>;
  sendMessageStream(message: string | Part[]): AsyncGenerator<EnhancedGenerateContentResponse>;
  getHistory(curated?: boolean): Content[];
  setTools(tools: Tool[]): void;
}

Core AI Functionality

Tools and Extensions

Extensible tool system for file operations, shell commands, web operations, and custom tool development.

abstract class DeclarativeTool<TParams = any, TResult = any> {
  abstract readonly name: string;
  abstract readonly description: string;
  abstract readonly parameters: object;
  
  abstract invoke(params: TParams): Promise<ToolResult<TResult>>;
}

interface ToolResult<T = any> {
  result: T;
  confirmationState?: ToolConfirmationOutcome;
  displayResult?: ToolResultDisplay;
}

enum Kind {
  Read = 'Read',
  Edit = 'Edit', 
  Delete = 'Delete',
  Move = 'Move',
  Search = 'Search',
  Execute = 'Execute',
  Think = 'Think',
  Fetch = 'Fetch',
  Other = 'Other'
}

Tools and Extensions

Services and Utilities

Comprehensive service layer for file discovery, git operations, shell execution, and system integration.

class FileDiscoveryService {
  filterFiles(filePaths: string[], options?: FilterFilesOptions): string[];
  shouldIgnoreFile(filePath: string, options?: FilterFilesOptions): boolean;
  getGeminiIgnorePatterns(): string[];
}

class Storage {
  static getGlobalGeminiDir(): string;
  static getGlobalSettingsPath(): string;
  
  getGeminiDir(): string;
  getProjectRoot(): string;
  getHistoryDir(): string;
}

Services and Utilities

IDE Integration

Deep integration capabilities for IDEs with context awareness, file monitoring, and installation utilities.

interface IdeContext {
  files: File[];
  cwd: string;
}

interface File {
  name: string;
  path: string;
  content: string;
  cursor?: { line: number; column: number };
}

IDE Integration

MCP and OAuth

Model Context Protocol support with OAuth authentication for secure server integrations.

class MCPOAuthProvider {
  authenticate(
    serverName: string, 
    config: MCPOAuthConfig, 
    mcpServerUrl?: string
  ): Promise<OAuthToken>;
  
  getValidToken(serverName: string, config: MCPOAuthConfig): Promise<string | null>;
}

interface MCPOAuthConfig {
  authorizationUrl: string;
  tokenUrl: string;
  clientId: string;
  scopes?: string[];
}

MCP and OAuth

Error Handling and Utilities

Robust error handling system with specialized error types and utility functions for common operations.

class FatalError extends Error {
  constructor(message: string);
}

class FatalAuthenticationError extends FatalError {}
class FatalInputError extends FatalError {}
class FatalConfigError extends FatalError {}

function getErrorMessage(error: unknown): string;
function toFriendlyError(error: unknown): unknown;

Error Handling and Utilities

Telemetry and Monitoring

Comprehensive telemetry system with OpenTelemetry integration for monitoring AI interactions and system performance.

enum TelemetryTarget {
  GCP = 'GCP',
  LOCAL = 'LOCAL'
}

function initializeTelemetry(target: TelemetryTarget): void;
function logUserPrompt(prompt: string, metadata?: object): void;
function logToolCall(toolName: string, params: object, result?: object): void;
function logApiRequest(model: string, request: object): void;

Telemetry and Monitoring