Configure Pi with settings.json

Pi reads settings from JSON files. Global settings apply to all projects; project settings override them for the current directory. Use /settings in interactive mode to modify common options, or edit the JSON files directly.

Location	Scope
`~/.pi/agent/settings.json`	Global (all projects)
`.pi/settings.json`	Project (current directory only)

Example

{
  "defaultProvider": "anthropic",
  "defaultModel": "claude-sonnet-4-20250514",
  "defaultThinkingLevel": "medium",
  "theme": "dark",
  "compaction": {
    "enabled": true,
    "reserveTokens": 16384,
    "keepRecentTokens": 20000
  },
  "retry": {
    "enabled": true,
    "maxRetries": 3
  },
  "enabledModels": ["claude-*", "gpt-4o"],
  "warnings": {
    "anthropicExtraUsage": true
  },
  "packages": ["pi-skills"]
}

All settings

Model and thinking

Setting	Type	Default	Description
`defaultProvider`	string	—	Default provider (e.g., `"anthropic"`, `"openai"`)
`defaultModel`	string	—	Default model ID
`defaultThinkingLevel`	string	—	`"off"`, `"minimal"`, `"low"`, `"medium"`, `"high"`, `"xhigh"`
`hideThinkingBlock`	boolean	`false`	Hide thinking blocks in output
`thinkingBudgets`	object	—	Custom token budgets per thinking level

Use thinkingBudgets to override default token allocations per level:

{
  "thinkingBudgets": {
    "minimal": 1024,
    "low": 4096,
    "medium": 10240,
    "high": 32768
  }
}

UI and display

Setting	Type	Default	Description
`theme`	string	`"dark"`	Theme name: `"dark"`, `"light"`, or a custom theme
`quietStartup`	boolean	`false`	Hide the startup header
`collapseChangelog`	boolean	`false`	Show a condensed changelog after updates
`enableInstallTelemetry`	boolean	`true`	Send an anonymous install/update version ping after first install or changelog-detected updates
`doubleEscapeAction`	string	`"tree"`	Action on double-escape: `"tree"`, `"fork"`, or `"none"`
`treeFilterMode`	string	`"default"`	Default filter for `/tree`: `"default"`, `"no-tools"`, `"user-only"`, `"labeled-only"`, `"all"`
`editorPaddingX`	number	`0`	Horizontal padding for the input editor (0–3)
`autocompleteMaxVisible`	number	`5`	Max visible items in the autocomplete dropdown (3–20)
`showHardwareCursor`	boolean	`false`	Show the terminal cursor

enableInstallTelemetry only controls the anonymous install/update ping to https://pi.dev/api/report-install. Disabling it does not disable update checks. Set PI_SKIP_VERSION_CHECK=1 to skip version checks, or use --offline / PI_OFFLINE=1 to disable all startup network operations.

Warnings

Setting	Type	Default	Description
`warnings.anthropicExtraUsage`	boolean	`true`	Show a warning when Anthropic subscription auth may use paid extra usage

{
  "warnings": {
    "anthropicExtraUsage": false
  }
}

Compaction

Setting	Type	Default	Description
`compaction.enabled`	boolean	`true`	Enable auto-compaction
`compaction.reserveTokens`	number	`16384`	Tokens reserved for the LLM response
`compaction.keepRecentTokens`	number	`20000`	Recent tokens to keep (not summarized)

See sessions for a full explanation of how compaction works.

Branch summary

Setting	Type	Default	Description
`branchSummary.reserveTokens`	number	`16384`	Tokens reserved for branch summarization
`branchSummary.skipPrompt`	boolean	`false`	Skip the “Summarize branch?” prompt on `/tree` navigation (defaults to no summary)

Retry

Setting	Type	Default	Description
`retry.enabled`	boolean	`true`	Enable automatic agent-level retry on transient errors
`retry.maxRetries`	number	`3`	Maximum agent-level retry attempts
`retry.baseDelayMs`	number	`2000`	Base delay for exponential backoff (2s, 4s, 8s)
`retry.provider.timeoutMs`	number	SDK default	Provider/SDK request timeout in milliseconds
`retry.provider.maxRetries`	number	SDK default	Provider/SDK retry attempts
`retry.provider.maxRetryDelayMs`	number	`60000`	Max server-requested retry delay before failing (60s)

When a provider requests a retry delay longer than retry.provider.maxRetryDelayMs (for example, Google’s “quota resets after 5h”), the request fails immediately with an informative error. Set to 0 to disable the cap.

{
  "retry": {
    "enabled": true,
    "maxRetries": 3,
    "baseDelayMs": 2000,
    "provider": {
      "timeoutMs": 3600000,
      "maxRetries": 0,
      "maxRetryDelayMs": 60000
    }
  }
}

Message delivery

Setting	Type	Default	Description
`steeringMode`	string	`"one-at-a-time"`	How steering messages are delivered: `"all"` or `"one-at-a-time"`
`followUpMode`	string	`"one-at-a-time"`	How follow-up messages are delivered: `"all"` or `"one-at-a-time"`
`transport`	string	`"sse"`	Preferred transport for providers that support multiple transports: `"sse"`, `"websocket"`, or `"auto"`

Terminal and images

Setting	Type	Default	Description
`terminal.showImages`	boolean	`true`	Show images in the terminal (if supported)
`terminal.imageWidthCells`	number	`60`	Preferred inline image width in terminal cells
`terminal.clearOnShrink`	boolean	`false`	Clear empty rows when content shrinks (can cause flicker)
`images.autoResize`	boolean	`true`	Resize images to 2000×2000 max before sending
`images.blockImages`	boolean	`false`	Block all images from being sent to the LLM

Shell

Setting	Type	Default	Description
`shellPath`	string	—	Custom shell path (e.g., for Cygwin on Windows)
`shellCommandPrefix`	string	—	Prefix prepended to every bash command (e.g., `"shopt -s expand_aliases"`)
`npmCommand`	string[]	—	Command argv for npm package operations (e.g., `["mise", "exec", "node@20", "--", "npm"]`)

{
  "npmCommand": ["mise", "exec", "node@20", "--", "npm"]
}

npmCommand affects all npm operations including installs, uninstalls, and dependency installs inside git packages. When configured, git package dependency installs use plain install to avoid npm-specific flags.

Sessions

Setting	Type	Default	Description
`sessionDir`	string	—	Directory where session files are stored; accepts absolute paths, relative paths, or `~`

{ "sessionDir": ".pi/sessions" }

Precedence for session directory: --session-dir flag > PI_CODING_AGENT_SESSION_DIR env var > sessionDir in settings.

Model cycling

Setting	Type	Default	Description
`enabledModels`	string[]	—	Model patterns for `Ctrl+P` cycling (same format as `--models` CLI flag)

{
  "enabledModels": ["claude-*", "gpt-4o", "gemini-2*"]
}

Markdown

Setting	Type	Default	Description
`markdown.codeBlockIndent`	string	`" "`	Indentation for code blocks

Resources

These settings control where Pi loads extensions, skills, prompts, and themes from. Paths in ~/.pi/agent/settings.json resolve relative to ~/.pi/agent. Paths in .pi/settings.json resolve relative to .pi. Absolute paths and ~ are supported.

Setting	Type	Default	Description
`packages`	array	`[]`	npm or git packages to load resources from
`extensions`	string[]	`[]`	Local extension file paths or directories
`skills`	string[]	`[]`	Local skill file paths or directories
`prompts`	string[]	`[]`	Local prompt template paths or directories
`themes`	string[]	`[]`	Local theme file paths or directories
`enableSkillCommands`	boolean	`true`	Register skills as `/skill:name` commands

Arrays support glob patterns and exclusions. Use !pattern to exclude, +path to force-include, and -path to force-exclude. Load a package with string form (loads all resources) or object form (filters specific resources):

{
  "packages": [
    "pi-skills",
    {
      "source": "pi-skills",
      "skills": ["brave-search", "transcribe"],
      "extensions": []
    }
  ]
}

Project overrides

Project settings (.pi/settings.json) override global settings. Nested objects are merged — you only need to specify the keys you want to change:

// ~/.pi/agent/settings.json (global)
{
  "theme": "dark",
  "compaction": { "enabled": true, "reserveTokens": 16384 }
}

// .pi/settings.json (project)
{
  "compaction": { "reserveTokens": 8192 }
}

// Result
{
  "theme": "dark",
  "compaction": { "enabled": true, "reserveTokens": 8192 }
}

Get Started

Using Pi

Customization

Programmatic Usage

Configure Pi with settings.json

Example

All settings

Model and thinking

UI and display

Warnings

Compaction

Branch summary

Retry

Message delivery

Terminal and images

Shell

Sessions

Model cycling

Markdown

Resources

Project overrides

Build docs developers (and LLMs) love

Get Started

Using Pi

Customization

Programmatic Usage

Documentation Index

​Example

​All settings

​Model and thinking

​UI and display

​Warnings

​Compaction

​Branch summary

​Retry

​Message delivery

​Terminal and images

​Shell

​Sessions

​Model cycling

​Markdown

​Resources

​Project overrides

Build docs developers (and LLMs) love

Example

All settings

Model and thinking

UI and display

Warnings

Compaction

Branch summary

Retry

Message delivery

Terminal and images

Shell

Sessions

Model cycling

Markdown

Resources

Project overrides