Settings Reference

This reference lists user-configurable settings, their types, defaults, and purposes. Project settings override agent-directory settings. Resource lists are combined. See Configuration for file locations and trust behavior.

Model and thinking

Cache warming runs only when the model declares a cache lifetime and Pi estimates at least $0.05 in avoided cache-miss cost. Refresh usage counts toward session totals but does not enter model context. /session shows the next decision; extensions can override it with cache_warming_decision. See Prompt Cache Lifetimes.

See Choose a Model for model selection and thinking controls.

Interaction

Tools

Available built-in tools are read, bash, powershell, edit, write, grep, find, and ls. defaultTools can also name codemode and tool_search, which built-in extensions register inactive, and other extension tools registered inactive.

A list of only +name and -name entries changes the inherited selection instead of replacing it. For example, this enables codemode next to the default tools:

{
  "defaultTools": ["+codemode"]
}

This replaces bash with powershell and enables grep: ["-bash", "+powershell", "+grep"]. Project settings apply on top of user settings: a project list with only +name and -name entries changes the user's selection, and a project list with a plain name replaces it. In one list, plain names form the selection, and +name and -name then apply in order.

/reload enables tools newly added to defaultTools. It does not disable tools removed from it or re-enable unchanged tools you turned off. --tools with plain names, --no-tools, and --no-builtin-tools override defaultTools, also on reload.

CLI tool options override this setting for one invocation. --tools with only +name and -name entries changes the resolved defaultTools selection instead, for example pi --tools +codemode. On /reload, these entries apply to the reloaded setting too, so a tool removed with -name stays removed. See Command Line.

Sessions and context

Compaction

Compaction token values must be non-negative safe integers. Each value resolves independently from the matching model override, then the ordinary compaction setting, then the built-in default. Project and user objects merge before model lookup.

See Compaction Reference for trigger, summarization, and validation behavior.

Branch summaries

Terminal and display

See Themes and Terminal Setup for format and platform details.

Network and retries

Keep retry.provider.maxRetries at 0 unless provider-level retries are required. Provider retries can delay Pi from handling quota and usage-limit errors itself.

Shell

See Shell aliases for shell setup and Pi Packages for package-manager behavior.

Resources

Resource paths in user settings resolve from the agent directory. Paths in project settings resolve from the project .pi directory. Absolute paths and ~ are supported.

Resource arrays support glob exclusions with !pattern, exact inclusion with +path, and exact exclusion with -path. Pi loads resources listed in both user-level and project settings.

The built-in extensions are named builtin:mcp, builtin:llama.cpp, builtin:codemode, and builtin:tool-search in extensions. They load by default; -builtin:mcp disables one. A +builtin:<name> or -builtin:<name> entry in project settings overrides the user setting. pi config lists them under Built-in. --no-extensions disables them too, and -e builtin:<name> loads one explicitly.

Updates, telemetry, and warnings