Pi reads JSON settings and applies them with clear precedence rules.
Pi loads settings from (up to) two files:
| Location | Scope |
|---|---|
~/.pi/agent/settings.json |
Global (all projects) |
.pi/settings.json |
Project (current directory) |
You can override the path entirely with PI_CONFIG_PATH (see below).
Run pi config to print the effective paths and precedence.
- CLI flags
- Environment variables
- Project settings (
.pi/settings.json) - Global settings (
~/.pi/agent/settings.json) - Built-in defaults
If PI_CONFIG_PATH is set, Pi loads only that file and skips the global/project merge.
Project settings override global settings on a per-field basis.
Important detail: nested objects like compaction, retry, images, terminal, branch_summary,
and thinking_budgets are treated as single fields. If .pi/settings.json contains a
compaction object, it replaces the entire global compaction object.
Within a single file, missing nested keys fall back to built-in defaults when accessed (see
src/config.rs).
Example:
// ~/.pi/agent/settings.json (global)
{ "compaction": { "enabled": false, "reserve_tokens": 16384 } }// .pi/settings.json (project)
{ "compaction": { "reserve_tokens": 8192 } }Resulting behavior:
compaction.reserve_tokensbecomes8192compaction.enableddoes not inheritfalsefrom global; it falls back to its built-in default
theme(string): Theme to apply. Built-ins:dark,light,solarized; also accepts a discovered theme name or a path to a theme JSON file.light/dark,auto, orsystemauto-detect dark/light from the terminal background via theCOLORFGBGenvironment variable (dark when unavailable). If unset, auto-detects the same way.hide_thinking_block(bool): Hide thinking blocks in interactive output. Defaultfalse.show_hardware_cursor(bool): Show terminal hardware cursor. DefaultfalseunlessPI_HARDWARE_CURSOR=1.
default_provider(string)default_model(string)default_thinking_level(string)enabled_models(array of model patterns)
Example:
{
"default_provider": "anthropic",
"default_model": "claude-sonnet-4-20250514",
"default_thinking_level": "medium",
"enabled_models": ["claude-*", "gpt-*"]
}steering_mode(string):one-at-a-timeorall(defaultone-at-a-time).follow_up_mode(string):one-at-a-timeorall(defaultone-at-a-time).
Legacy aliases: steeringMode, followUpMode.
{
"steering_mode": "one-at-a-time",
"follow_up_mode": "one-at-a-time"
}double_escape_action(string):tree,fork, ornone(defaulttree). Alias:doubleEscapeAction. Usenoneto disable the double-escape shortcut.editor_padding_x(u32): Horizontal editor padding (clamped to 0–3). Default0.autocomplete_max_visible(u32): Max autocomplete rows (clamped 3–20). Default5.session_picker_input(u32): Non-interactive session picker selection (1-based). Alias:sessionPickerInput.quiet_startup(bool): Suppress the startup header.collapse_changelog(bool): Condense “What’s New” output when present.
Accessor defaults:
compaction.enabled:truecompaction.reserve_tokens:16384compaction.keep_recent_tokens:20000
{
"compaction": {
"enabled": true,
"reserve_tokens": 16384,
"keep_recent_tokens": 20000
}
}branch_summary.reserve_tokens(u32): Defaults tocompaction.reserve_tokens.
Accessor defaults:
retry.enabled:trueretry.max_retries:3retry.base_delay_ms:2000retry.max_delay_ms:60000
{
"retry": {
"enabled": true,
"max_retries": 3,
"base_delay_ms": 2000,
"max_delay_ms": 60000
}
}search_backend(string): Backend for thegrep/findtools.inproc(default) searches in-process with the same engines ripgrep uses (norgorfdbinaries required);externalshells out torg/fdas before — kept as a debugging escape hatch. Alias:searchBackend.
foreign_rules(bool): Import rules from other tools' native config files found in the workspace — Cursor.cursor/rules/*.mdcand.cursorrules, Cline.clinerules, Copilot.github/copilot-instructions.mdand*.instructions.md(applyToglobs), Windsurf.windsurfrules/.windsurf/rules/, andGEMINI.md. Always-apply rules join the system prompt with provenance headers; glob-scoped rules are delivered the first time a tool call touches a matching path. Import is read-only, deduped againstAGENTS.md/CLAUDE.md(native wins), and budget-capped with a truncation notice. Defaulttrue. Alias:foreignRules.
ask_policy(string): How theasktool (opt-in via--tools ...,ask) resolves in sessions without an interactive picker (print/JSON mode).recommended(default) auto-answers with each question's recommended option and loudly annotates the result;errorfails the tool call. Alias:askPolicy.
shell_path(string): Shell binary path. Default/bin/bash.shell_command_prefix(string): Defaultset -e.gh_path(string): Override path toghfor/share. Alias:ghPath.
{
"shell_path": "/bin/bash",
"shell_command_prefix": "set -e"
}subagent_structured_results(bool): Defaultfalse. Alias:subagentStructuredResults. Whentrue, thesubagenttool appends a machine-readable<subagent-structured-result>block to its result text: a compact JSON array with one entry per child (agent,step,status,exitCode,output,error— the same field names as thepi.subagent.result.v1details schema).output/errorare truncated to 2 KiB each and the whole block is capped at 16 KiB; when entries must be dropped, the final array element is{"truncated": true, "omittedResults": N}. Defaultfalsekeeps the tool output byte-identical to previous releases.
{
"subagent_structured_results": true
}images.auto_resize(bool): Defaulttrue.images.block_images(bool): Defaultfalse.
{
"images": {
"auto_resize": true,
"block_images": false
}
}terminal.show_images(bool): Defaulttrue. Whenfalse, Pi hides image blocks in terminal tool output (images are still stored in sessions/exports).terminal.clear_on_shrink(bool): Defaultfalse. Whentrue, Pi purges scrollback on terminal shrink to avoid stale rows reappearing after resize.
thinking_budgets.minimal: default1024thinking_budgets.low: default2048thinking_budgets.medium: default8192thinking_budgets.high: default16384thinking_budgets.xhigh: default32768thinking_budgets.max: default65536
packages(array): package sources (string or{ source, local, kind }).extensions,skills,prompts,themes(arrays): resource filters.enable_skill_commands(bool): defaulttrue.
media.enable_media(bool): Defaultfalse. Whentrue, activatesinspect_image,generate_image, andtts.media.tts_provider(string): Default"elevenlabs". Supported:"openai","elevenlabs","system".media.tts_voice(string): Voice identifier (e.g."alloy","rachel").media.image_gen_provider(string): Default"gemini". Supported:"gemini","dall-e-3".media.output_dir(string): Destination folder for generated media artifacts.
computer.enable_computer(bool): Defaultfalse. Whentrue, activatescomputertool.computer.require_approval(bool): Defaulttrue. Requires operator approval for mouse/keyboard inputs.computer.screenshot_dir(string): Destination directory for captured screen artifacts.
browser.enable_browser(bool): Defaultfalse. Whentrue, activatesbrowsertool.browser.headless(bool): Defaulttrue. Runs browser in headless mode.browser.remote_debugging_port(integer): CDP debugging port (default9222).browser.domain_allowlist(array of strings): Restricts browser navigation to approved hosts.
web.port(integer): Port forpi webWebSocket server (default8080).web.bind_mode(string):"loopback","tailscale","lan".web.view_only(bool): Restricts all remote clients to view-only mode.web.max_viewers(integer): Max concurrent viewer connections (default4).
src/config.rs is the authoritative list of supported fields and defaulting behavior.