Configuration

Control your Gemini CLI experience through the /settings command or by editing settings.json files directly. Settings control UI behavior, model parameters, security policies, and more.

Configuration Files

Settings are stored in settings.json files at two levels:

User Settings

Location: ~/.gemini/settings.jsonGlobal settings that apply to all projects.

Workspace Settings

Location: <project>/.gemini/settings.jsonProject-specific settings that override user settings.

Workspace settings take precedence over user settings.

Managing Settings

Using the `/settings` Command

The recommended way to manage settings is through the interactive editor:

/settings

The editor provides:

Browse or search for specific settings
View current values with descriptions
Validation to prevent errors
Immediate or restart-required change notifications

Manual Editing

You can also edit settings.json files directly with any text editor:

{
  "general": {
    "vimMode": true,
    "defaultApprovalMode": "auto_edit"
  },
  "ui": {
    "hideBanner": false,
    "showLineNumbers": true
  },
  "model": {
    "name": "gemini-2.0-flash",
    "maxSessionTurns": 100
  }
}

Settings Reference

Below is a comprehensive list of all available settings grouped by category.

General

Setting	Type	Description	Default
`general.vimMode`	boolean	Enable Vim keybindings	`false`
`general.defaultApprovalMode`	string	Default approval mode: `default`, `auto_edit`, `plan`	`"default"`
`general.enableAutoUpdate`	boolean	Enable automatic updates	`true`
`general.enableNotifications`	boolean	Enable notifications for action-required prompts (macOS only)	`false`
`general.maxAttempts`	number	Maximum attempts for chat model requests (max 10)	`10`
`general.debugKeystrokeLogging`	boolean	Log keystrokes to console for debugging	`false`

Plan Mode

Setting	Type	Description	Default
`general.plan.directory`	string	Directory for planning artifacts	`undefined`
`general.plan.modelRouting`	boolean	Auto-switch between Pro/Flash for plan/implementation	`true`

Session Retention

See Session Management for detailed information on retention policies.

Setting	Type	Description	Default
`general.sessionRetention.enabled`	boolean	Enable automatic session cleanup	`true`
`general.sessionRetention.maxAge`	string	Delete chats older than this (e.g., “30d”, “7d”, “24h”)	`"30d"`

Output

Setting	Type	Description	Default
`output.format`	string	Output format: `text` or `json`	`"text"`

UI

Appearance

Setting	Type	Description	Default
`ui.autoThemeSwitching`	boolean	Auto-switch light/dark themes based on terminal background	`true`
`ui.terminalBackgroundPollingInterval`	number	Seconds between terminal background color polls	`60`
`ui.hideWindowTitle`	boolean	Hide window title bar	`false`
`ui.hideBanner`	boolean	Hide application banner	`false`
`ui.hideFooter`	boolean	Hide footer from UI	`false`
`ui.useBackgroundColor`	boolean	Use background colors in UI	`true`
`ui.useAlternateBuffer`	boolean	Use alternate screen buffer (preserves shell history)	`false`
`ui.incrementalRendering`	boolean	Reduce flickering (requires `useAlternateBuffer`)	`true`
`ui.showSpinner`	boolean	Show spinner during operations	`true`

Content Display

Setting	Type	Description	Default
`ui.inlineThinkingMode`	string	Display model thinking inline: `off` or `full`	`"off"`
`ui.showStatusInTitle`	boolean	Show model thoughts in window title	`false`
`ui.dynamicWindowTitle`	boolean	Update title with status icons (◇/✋/✦)	`true`
`ui.showLineNumbers`	boolean	Show line numbers in chat	`true`
`ui.showCitations`	boolean	Show citations for generated text	`false`
`ui.showModelInfoInChat`	boolean	Show model name for each turn	`false`
`ui.showUserIdentity`	boolean	Show logged-in user’s identity	`true`
`ui.showMemoryUsage`	boolean	Display memory usage information	`false`
`ui.loadingPhrases`	string	What to show while working: `tips`, `witty`, `both`, or `nothing`	`"tips"`
`ui.errorVerbosity`	string	Error display: `low` (hide recoverable) or `full`	`"low"`

UI Elements

Setting	Type	Description	Default
`ui.hideTips`	boolean	Hide helpful tips	`false`
`ui.showShortcutsHint`	boolean	Show ”? for shortcuts” hint	`true`
`ui.hideContextSummary`	boolean	Hide GEMINI.md/MCP context summary	`false`
`ui.showHomeDirectoryWarning`	boolean	Warn when running in home directory	`true`
`ui.showCompatibilityWarnings`	boolean	Show terminal/OS compatibility warnings	`true`

Setting	Type	Description	Default
`ui.footer.hideCWD`	boolean	Hide current working directory path	`false`
`ui.footer.hideSandboxStatus`	boolean	Hide sandbox status indicator	`false`
`ui.footer.hideModelInfo`	boolean	Hide model name and context usage	`false`
`ui.footer.hideContextPercentage`	boolean	Hide context window percentage	`true`

Accessibility

Setting	Type	Description	Default
`ui.accessibility.screenReader`	boolean	Plain-text output for screen readers	`false`

IDE

Setting	Type	Description	Default
`ide.enabled`	boolean	Enable IDE integration mode	`false`

Billing

Setting	Type	Description	Default
`billing.overageStrategy`	string	Quota exhaustion handling: `ask`, `always`, `never`	`"ask"`

Model

Setting	Type	Description	Default
`model.name`	string	Gemini model for conversations	`undefined`
`model.maxSessionTurns`	number	Max user/model/tool turns (-1 = unlimited)	`-1`
`model.compressionThreshold`	number	Context usage fraction to trigger compression (0.0-1.0)	`0.5`
`model.disableLoopDetection`	boolean	Disable infinite loop detection	`false`
`model.skipNextSpeakerCheck`	boolean	Skip next speaker check	`true`

Set model.maxSessionTurns to limit context window size and control costs. See Session Management for details.

Context

Memory Discovery

Setting	Type	Description	Default
`context.discoveryMaxDirs`	number	Max directories to search for GEMINI.md	`200`
`context.loadMemoryFromIncludeDirectories`	boolean	Scan include directories for GEMINI.md	`false`

File Filtering

Setting	Type	Description	Default
`context.fileFiltering.respectGitIgnore`	boolean	Respect .gitignore files	`true`
`context.fileFiltering.respectGeminiIgnore`	boolean	Respect .geminiignore files	`true`
`context.fileFiltering.enableRecursiveFileSearch`	boolean	Recursive search for @ references	`true`
`context.fileFiltering.enableFuzzySearch`	boolean	Fuzzy search when searching files	`true`
`context.fileFiltering.customIgnoreFilePaths`	array	Additional ignore files (highest precedence)	`[]`

Tools

Shell

Setting	Type	Description	Default
`tools.shell.enableInteractiveShell`	boolean	Use node-pty for interactive shell	`true`
`tools.shell.showColor`	boolean	Show color in shell output	`false`

Tool Behavior

Setting	Type	Description	Default
`tools.useRipgrep`	boolean	Use ripgrep for faster content search	`true`
`tools.truncateToolOutputThreshold`	number	Max characters before truncation (0 = disabled)	`40000`
`tools.disableLLMCorrection`	boolean	Disable LLM error correction for edit tools	`true`

See Sandboxing for sandbox-specific configuration.

Security

Setting	Type	Description	Default
`security.disableYoloMode`	boolean	Disable YOLO mode even if flagged	`false`
`security.enablePermanentToolApproval`	boolean	Enable “Allow for all future sessions” option	`false`
`security.blockGitExtensions`	boolean	Block installing/loading extensions from Git	`false`
`security.allowedExtensions`	array	Regex patterns for allowed extensions (overrides blockGitExtensions)	`[]`
`security.folderTrust.enabled`	boolean	Enable folder trust tracking	`true`
`security.environmentVariableRedaction.enabled`	boolean	Redact environment variables with secrets	`false`
`security.enableConseca`	boolean	Enable context-aware security checker (LLM-based)	`false`

Advanced

Setting	Type	Description	Default
`advanced.autoConfigureMemory`	boolean	Auto-configure Node.js memory limits	`false`

Experimental

Experimental features may change or be removed in future versions.

Setting	Type	Description	Default
`experimental.toolOutputMasking.enabled`	boolean	Enable tool output masking to save tokens	`true`
`experimental.useOSC52Paste`	boolean	Use OSC 52 for pasting (remote sessions)	`false`
`experimental.useOSC52Copy`	boolean	Use OSC 52 for copying (remote sessions)	`false`
`experimental.plan`	boolean	Enable Plan Mode and planning tools	`false`
`experimental.modelSteering`	boolean	Enable user hints to guide model	`false`
`experimental.directWebFetch`	boolean	Web fetch without LLM summarization	`false`
`experimental.gemmaModelRouter.enabled`	boolean	Enable Gemma Model Router (requires local endpoint)	`false`

Skills

Setting	Type	Description	Default
`skills.enabled`	boolean	Enable Agent Skills	`true`

Hooks

Setting	Type	Description	Default
`hooksConfig.enabled`	boolean	Master toggle for hooks system	`true`
`hooksConfig.notifications`	boolean	Show visual indicators when hooks execute	`true`

Example Configurations

Minimal Setup

{
  "model": {
    "name": "gemini-2.0-flash"
  }
}

Productivity Setup

{
  "general": {
    "vimMode": true,
    "defaultApprovalMode": "auto_edit"
  },
  "ui": {
    "hideWindowTitle": true,
    "showLineNumbers": true,
    "inlineThinkingMode": "full"
  },
  "model": {
    "maxSessionTurns": 150
  },
  "tools": {
    "sandbox": "docker"
  }
}

Security-Focused

{
  "general": {
    "defaultApprovalMode": "default"
  },
  "security": {
    "disableYoloMode": true,
    "blockGitExtensions": true,
    "folderTrust.enabled": true,
    "enableConseca": true
  },
  "tools": {
    "sandbox": "restrictive-open",
    "disableLLMCorrection": true
  }
}

Hierarchical Memory (GEMINI.md)

The /memory command manages hierarchical instructional context from GEMINI.md files.

File Locations

GEMINI.md files are loaded from:

Global: ~/.gemini/GEMINI.md
Project ancestors: All parent directories up to project root
Current directory: ./GEMINI.md
Sub-directories: When configured

Commands

/memory list       # List paths of loaded GEMINI.md files
/memory show       # Display full concatenated content
/memory refresh    # Reload from all locations
/memory add <text> # Add text to memory

Control memory loading behavior:

{
  "context": {
    "discoveryMaxDirs": 200,
    "loadMemoryFromIncludeDirectories": false
  }
}

Next Steps

Commands Overview

Explore all available commands

Session Management

Configure session retention and limits

Checkpointing

Enable automatic checkpoints

Sandboxing

Configure sandboxed execution

Get Started

Core Concepts

CLI Usage

Tools & Extensions

Advanced

Resources

​Configuration Files

User Settings

Workspace Settings

​Managing Settings

​Using the /settings Command

​Manual Editing

​Settings Reference

​General

​Plan Mode

​Session Retention

​Output

​UI

​Appearance

​Content Display

​UI Elements

​Footer Settings

​Accessibility

​IDE

​Billing

​Model

​Context

​Memory Discovery

​File Filtering

​Tools

​Shell

​Tool Behavior

​Security

​Advanced

​Experimental

​Skills

​Hooks

​Example Configurations

​Minimal Setup

​Productivity Setup

​Security-Focused

​Hierarchical Memory (GEMINI.md)

​File Locations

​Commands

​Configuration

​Next Steps

Commands Overview

Session Management

Checkpointing

Sandboxing

Build docs developers (and LLMs) love

Configuration Files

Managing Settings

Using the `/settings` Command

Manual Editing

Settings Reference

General

Plan Mode

Session Retention

Output

UI

Appearance

Content Display

UI Elements

Footer Settings

Accessibility

IDE

Billing

Model

Context

Memory Discovery

File Filtering

Tools

Shell

Tool Behavior

Security

Advanced

Experimental

Skills

Hooks

Example Configurations

Minimal Setup

Productivity Setup

Security-Focused

Hierarchical Memory (GEMINI.md)

File Locations

Commands

Configuration

Next Steps