Configuration Management

enum SettingScope {
  SystemDefaults = 'systemDefaults',    // Built-in defaults
  System = 'system',                    // System-wide configuration
  User = 'user',                        // User home directory (~/.gemini/settings.json)
  Workspace = 'workspace'               // Project directory (.gemini/settings.json)
}

# System defaults (built-in)
# No file - hardcoded in application

# System-wide settings
/etc/gemini/settings.json

# User settings
~/.gemini/settings.json

# Workspace settings
.gemini/settings.json

/**
 * Load settings from all scopes, merging in hierarchy order
 * @param workspaceDir - Optional workspace directory path
 * @returns Loaded settings with scope access methods
 */
function loadSettings(workspaceDir?: string): LoadedSettings;

class LoadedSettings {
  /** Merged settings from all scopes */
  merged: Settings;

  /**
   * Get settings for specific scope
   * @param scope - Setting scope to retrieve
   * @returns Settings file for the scope
   */
  forScope(scope: SettingScope): SettingsFile;

  /**
   * Set value in specific scope
   * @param scope - Target scope for the setting
   * @param key - Setting key path (dot notation supported)
   * @param value - Value to set
   */
  setValue(scope: SettingScope, key: string, value: unknown): void;
}

interface GeneralSettings {
  /** Preferred external editor command */
  preferredEditor?: string;

  /** Enable Vim mode for text editing */
  vimMode?: boolean;

  /** Disable automatic application updates */
  disableAutoUpdate?: boolean;

  /** Disable update notification prompts */
  disableUpdateNag?: boolean;

  /** File edit checkpointing configuration */
  checkpointing?: {
    enabled: boolean;
  };

  /** Enable prompt completion suggestions */
  enablePromptCompletion?: boolean;

  /** Enable debug-level keystroke logging */
  debugKeystrokeLogging?: boolean;
}

{
  "general": {
    "preferredEditor": "code",
    "vimMode": true,
    "checkpointing": {
      "enabled": true
    }
  }
}

interface UISettings {
  /** Active theme name */
  theme?: string;

  /** Custom theme definitions */
  customThemes?: Record<string, CustomTheme>;

  /** Hide window title bar */
  hideWindowTitle?: boolean;

  /** Hide helpful tips display */
  hideTips?: boolean;

  /** Hide startup banner */
  hideBanner?: boolean;

  /** Hide context summary display */
  hideContextSummary?: boolean;

  /** Hide footer information */
  hideFooter?: boolean;

  /** Show memory usage in status bar */
  showMemoryUsage?: boolean;

  /** Show line numbers in code blocks */
  showLineNumbers?: boolean;

  /** Show citation information */
  showCitations?: boolean;

  /** Custom witty loading phrases */
  customWittyPhrases?: string[];

  /** Footer component visibility settings */
  footer?: {
    hideCWD?: boolean;
    hideSandboxStatus?: boolean;
    hideModelInfo?: boolean;
  };

  /** Accessibility configuration */
  accessibility?: {
    /** Disable animated loading phrases */
    disableLoadingPhrases?: boolean;

    /** Enable screen reader optimizations */
    screenReader?: boolean;
  };
}

{
  "ui": {
    "theme": "dracula",
    "showMemoryUsage": true,
    "hideFooter": false,
    "customWittyPhrases": [
      "Thinking deeply...",
      "Processing your request..."
    ],
    "accessibility": {
      "screenReader": true
    }
  }
}

interface ModelSettings {
  /** Model name/identifier */
  name?: string;

  /** Maximum conversation turns before compression */
  maxSessionTurns?: number;

  /** Tool output summarization settings */
  summarizeToolOutput?: Record<string, any>;

  /** Chat compression configuration */
  chatCompression?: Record<string, any>;

  /** Skip next speaker validation check */
  skipNextSpeakerCheck?: boolean;
}

{
  "model": {
    "name": "gemini-2.0-flash-exp",
    "maxSessionTurns": 50
  }
}

interface ContextSettings {
  /** Context file name(s) to load */
  fileName?: string | string[];

  /** Context import format */
  importFormat?: 'tree' | 'flat';

  /** Maximum directories to discover */
  discoveryMaxDirs?: number;

  /** Additional directories to include in context */
  includeDirectories?: string[];

  /** Load memory from include directories */
  loadMemoryFromIncludeDirectories?: boolean;

  /** File filtering options */
  fileFiltering?: {
    /** Respect .gitignore files */
    respectGitIgnore?: boolean;

    /** Respect .geminiignore files */
    respectGeminiIgnore?: boolean;

    /** Enable recursive file search */
    enableRecursiveFileSearch?: boolean;

    /** Disable fuzzy file matching */
    disableFuzzySearch?: boolean;
  };
}

{
  "context": {
    "fileName": ["GEMINI.md", "README.md"],
    "importFormat": "tree",
    "includeDirectories": ["src", "docs"],
    "fileFiltering": {
      "respectGitIgnore": true,
      "enableRecursiveFileSearch": true
    }
  }
}

interface ToolsSettings {
  /** Sandbox configuration (boolean or image URI) */
  sandbox?: boolean | string;

  /** Use pseudo-terminal for shell commands */
  usePty?: boolean;

  /** Automatically accept tool usage */
  autoAccept?: boolean;

  /** Core tools always available */
  core?: string[];

  /** Tools allowed without confirmation */
  allowed?: string[];

  /** Tools to exclude from availability */
  exclude?: string[];

  /** Command for tool discovery */
  discoveryCommand?: string;

  /** Command for tool execution */
  callCommand?: string;

  /** Use ripgrep for search operations */
  useRipgrep?: boolean;

  /** Enable tool output truncation */
  enableToolOutputTruncation?: boolean;

  /** Threshold for output truncation */
  truncateToolOutputThreshold?: number;

  /** Number of lines to keep when truncating */
  truncateToolOutputLines?: number;
}

{
  "tools": {
    "sandbox": true,
    "autoAccept": false,
    "allowed": ["file_edit", "shell", "web_search"],
    "useRipgrep": true,
    "enableToolOutputTruncation": true,
    "truncateToolOutputThreshold": 1000
  }
}

interface SecuritySettings {
  /** Folder trust system configuration */
  folderTrust?: {
    enabled: boolean;
  };

  /** Authentication configuration */
  auth?: {
    /** Currently selected authentication type */
    selectedType?: AuthType;

    /** Enforced authentication type (if set) */
    enforcedType?: AuthType;

    /** Use external authentication provider */
    useExternal?: boolean;
  };
}

enum AuthType {
  LOGIN_WITH_GOOGLE = 'login_with_google',
  CLOUD_SHELL = 'cloud_shell'
  // Additional auth types available
}

{
  "security": {
    "folderTrust": {
      "enabled": true
    },
    "auth": {
      "selectedType": "login_with_google",
      "useExternal": false
    }
  }
}

interface MCPSettings {
  /** Default server command template */
  serverCommand?: string;

  /** Globally allowed MCP server names */
  allowed?: string[];

  /** Globally excluded MCP server names */
  excluded?: string[];
}

interface MCPServerConfig {
  // Stdio transport
  command?: string;
  args?: string[];
  env?: Record<string, string>;

  // HTTP/SSE transport
  url?: string;
  httpUrl?: string;
  headers?: Record<string, string>;

  // Configuration
  timeout?: number;
  trust?: boolean;
  description?: string;
  includeTools?: string[];
  excludeTools?: string[];
  extensionName?: string;
}

interface IDESettings {
  /** Enable IDE integration mode */
  enabled?: boolean;

  /** Whether user has seen IDE integration nudge */
  hasSeenNudge?: boolean;
}

interface PrivacySettings {
  /** Enable collection of usage statistics */
  usageStatisticsEnabled?: boolean;
}

interface ExperimentalSettings {
  /** Enable extension management features */
  extensionManagement?: boolean;
}

interface ExtensionsSettings {
  /** List of disabled extensions */
  disabled?: string[];

  /** Workspaces where migration nudge has been shown */
  workspacesWithMigrationNudge?: string[];
}

interface AdvancedSettings {
  /** Automatically configure Node.js memory limits */
  autoConfigureMemory?: boolean;

  /** Configuration for the bug report command */
  bugCommand?: BugCommandSettings;
}

interface BugCommandSettings {
  /** Custom bug report template */
  template?: string;

  /** Additional data to include in bug reports */
  includeSystemInfo?: boolean;
}

interface Settings {
  general?: GeneralSettings;
  ui?: UISettings;
  model?: ModelSettings;
  context?: ContextSettings;
  tools?: ToolsSettings;
  security?: SecuritySettings;
  mcp?: MCPSettings;
  mcpServers?: Record<string, MCPServerConfig>;

  // Top-level settings
  useSmartEdit?: boolean;

  // Additional setting categories
  ide?: IDESettings;
  privacy?: PrivacySettings;
  experimental?: ExperimentalSettings;
  extensions?: ExtensionsSettings;
  advanced?: AdvancedSettings;
}

{
  "mcp": {
    "allowed": ["weather-service", "calculator"],
    "excluded": ["untrusted-server"]
  },
  "mcpServers": {
    "weather-service": {
      "command": "npx",
      "args": ["weather-mcp-server"],
      "description": "Weather information provider",
      "trust": true
    },
    "api-gateway": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer token123"
      },
      "timeout": 5000
    }
  }
}

interface SettingsFile {
  /** File path */
  path: string;

  /** Settings data */
  data: Partial<Settings>;

  /** Check if file exists */
  exists(): boolean;

  /** Load settings from file */
  load(): Partial<Settings>;

  /** Save settings to file */
  save(settings: Partial<Settings>): void;
}

/**
 * Validate settings configuration
 * @param settings - Settings object to validate
 * @returns Validation result with errors if any
 */
function validateSettings(settings: Settings): {
  valid: boolean;
  errors: string[];
  warnings: string[];
};

/**
 * Update setting value and persist to appropriate scope
 * @param key - Setting key path (e.g., "ui.theme")
 * @param value - New value
 * @param scope - Target scope for persistence
 */
function updateSetting(
  key: string,
  value: any,
  scope: SettingScope
): Promise<void>;

{
  "tools": {
    "sandbox": "${SANDBOX_IMAGE_URI:-true}"
  },
  "mcp": {
    "serverCommand": "${MCP_SERVER_COMMAND}"
  }
}

interface ConfigMigration {
  /** Migration version identifier */
  version: string;

  /** Migration description */
  description: string;

  /** Migration function */
  migrate: (oldSettings: any) => Settings;
}