Skip to content

Latest commit

 

History

History
275 lines (205 loc) · 9.04 KB

settings.md

File metadata and controls

275 lines (205 loc) · 9.04 KB

Settings

Pi reads JSON settings and applies them with clear precedence rules.

Locations

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.

Precedence (highest → lowest)

  1. CLI flags
  2. Environment variables
  3. Project settings (.pi/settings.json)
  4. Global settings (~/.pi/agent/settings.json)
  5. Built-in defaults

PI_CONFIG_PATH (single-file mode)

If PI_CONFIG_PATH is set, Pi loads only that file and skips the global/project merge.

Merge behavior (global vs project)

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_tokens becomes 8192
  • compaction.enabled does not inherit false from global; it falls back to its built-in default

Supported settings (snake_case JSON keys)

Appearance

  • 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, or system auto-detect dark/light from the terminal background via the COLORFGBG environment variable (dark when unavailable). If unset, auto-detects the same way.
  • hide_thinking_block (bool): Hide thinking blocks in interactive output. Default false.
  • show_hardware_cursor (bool): Show terminal hardware cursor. Default false unless PI_HARDWARE_CURSOR=1.

Model selection

  • 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-*"]
}

Message delivery (queue modes)

  • steering_mode (string): one-at-a-time or all (default one-at-a-time).
  • follow_up_mode (string): one-at-a-time or all (default one-at-a-time).

Legacy aliases: steeringMode, followUpMode.

{
  "steering_mode": "one-at-a-time",
  "follow_up_mode": "one-at-a-time"
}

Interactive UX / editor

  • double_escape_action (string): tree, fork, or none (default tree). Alias: doubleEscapeAction. Use none to disable the double-escape shortcut.
  • editor_padding_x (u32): Horizontal editor padding (clamped to 0–3). Default 0.
  • autocomplete_max_visible (u32): Max autocomplete rows (clamped 3–20). Default 5.
  • 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.

Compaction (defaults)

Accessor defaults:

  • compaction.enabled: true
  • compaction.reserve_tokens: 16384
  • compaction.keep_recent_tokens: 20000
{
  "compaction": {
    "enabled": true,
    "reserve_tokens": 16384,
    "keep_recent_tokens": 20000
  }
}

Branch summary

  • branch_summary.reserve_tokens (u32): Defaults to compaction.reserve_tokens.

Retry (defaults)

Accessor defaults:

  • retry.enabled: true
  • retry.max_retries: 3
  • retry.base_delay_ms: 2000
  • retry.max_delay_ms: 60000
{
  "retry": {
    "enabled": true,
    "max_retries": 3,
    "base_delay_ms": 2000,
    "max_delay_ms": 60000
  }
}

Search

  • search_backend (string): Backend for the grep/find tools. inproc (default) searches in-process with the same engines ripgrep uses (no rg or fd binaries required); external shells out to rg/fd as before — kept as a debugging escape hatch. Alias: searchBackend.

Imported rules (foreign formats)

  • foreign_rules (bool): Import rules from other tools' native config files found in the workspace — Cursor .cursor/rules/*.mdc and .cursorrules, Cline .clinerules, Copilot .github/copilot-instructions.md and *.instructions.md (applyTo globs), Windsurf .windsurfrules / .windsurf/rules/, and GEMINI.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 against AGENTS.md/CLAUDE.md (native wins), and budget-capped with a truncation notice. Default true. Alias: foreignRules.

Ask tool

  • ask_policy (string): How the ask tool (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; error fails the tool call. Alias: askPolicy.

Shell

  • shell_path (string): Shell binary path. Default /bin/bash.
  • shell_command_prefix (string): Default set -e.
  • gh_path (string): Override path to gh for /share. Alias: ghPath.
{
  "shell_path": "/bin/bash",
  "shell_command_prefix": "set -e"
}

Subagents

  • subagent_structured_results (bool): Default false. Alias: subagentStructuredResults. When true, the subagent tool 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 the pi.subagent.result.v1 details schema). output/error are 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}. Default false keeps the tool output byte-identical to previous releases.
{
  "subagent_structured_results": true
}

Images

  • images.auto_resize (bool): Default true.
  • images.block_images (bool): Default false.
{
  "images": {
    "auto_resize": true,
    "block_images": false
  }
}

Terminal display

  • terminal.show_images (bool): Default true. When false, Pi hides image blocks in terminal tool output (images are still stored in sessions/exports).
  • terminal.clear_on_shrink (bool): Default false. When true, Pi purges scrollback on terminal shrink to avoid stale rows reappearing after resize.

Thinking budgets (tokens)

  • thinking_budgets.minimal: default 1024
  • thinking_budgets.low: default 2048
  • thinking_budgets.medium: default 8192
  • thinking_budgets.high: default 16384
  • thinking_budgets.xhigh: default 32768
  • thinking_budgets.max: default 65536

Packages and resources

  • packages (array): package sources (string or { source, local, kind }).
  • extensions, skills, prompts, themes (arrays): resource filters.
  • enable_skill_commands (bool): default true.

Media (multimodal perception & speech)

  • media.enable_media (bool): Default false. When true, activates inspect_image, generate_image, and tts.
  • 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 (desktop automation)

  • computer.enable_computer (bool): Default false. When true, activates computer tool.
  • computer.require_approval (bool): Default true. Requires operator approval for mouse/keyboard inputs.
  • computer.screenshot_dir (string): Destination directory for captured screen artifacts.

Browser (headless Chromium automation)

  • browser.enable_browser (bool): Default false. When true, activates browser tool.
  • browser.headless (bool): Default true. Runs browser in headless mode.
  • browser.remote_debugging_port (integer): CDP debugging port (default 9222).
  • browser.domain_allowlist (array of strings): Restricts browser navigation to approved hosts.

Web Remote & Collab

  • web.port (integer): Port for pi web WebSocket server (default 8080).
  • 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 (default 4).

Full reference

src/config.rs is the authoritative list of supported fields and defaulting behavior.