Pi Agent Configuration Reference Manual
The following is a quick reference table for Pi Agent settings.json configuration items.
This table includes common configuration items; a few JSON-specific advanced keys (such as tuiMode, fullscreen series, terminal.hyperlinks, markdown.mermaid, etc.) are not listed individually.
Configuration File Location
Configuration is divided into two levels: global and project. Project configuration is only loaded after the project has been trusted.
| File Path | Scope | Description |
|---|---|---|
| ~/.pi/agent/settings.json | Global (all projects) | Common configuration effective for all projects |
| .pi/settings.json | Project-level | Only loaded after the project is trusted; overrides keys with the same name in the global configuration. |
Model and Reasoning
The configuration in this section determines the default provider, model, and reasoning effort.
| Configuration Item | Type | Required | Default Value | Description |
|---|---|---|---|---|
| defaultProvider | string | Optional | None (set on first use via /login or /model) | Default provider, e.g., "anthropic", "openai" |
| defaultModel | string | Optional | None (set on first use via /login or /model) | Default model ID, e.g., "claude-sonnet-4-20250514" |
| defaultThinkingLevel | string | Optional | None (not provided by documentation) | Default reasoning effort: off/minimal/low/medium/high/xhigh/max |
| modelThinkingLevels | object | Optional | None | Set the startup reasoning effort for each model by "provider/modelId" |
| hideThinkingBlock | boolean | Optional | false | Hide reasoning process |
| showCacheMissNotices | boolean | Optional | false | Display cache miss notifications |
| thinkingBudgets | object | Optional | None (custom budget not enabled) | Customize token budget for each level |
| warnings.anthropicExtraUsage | boolean | Optional | true | Remind when Anthropic subscription may incur paid extra usage |
UI and Display
The configuration in this section controls interface appearance, external editor, and display density.
| Configuration Item | Type | Required | Default Value | Description |
|---|---|---|---|---|
| theme | string | Optional | "dark" | Theme name |
| externalEditor | string | Optional | Uses $VISUAL, then $EDITOR; otherwise uses Notepad on Windows and nano on other systems | External editor command (explicit configuration takes precedence over environment variables) |
| quietStartup | boolean | Optional | false | Hide startup header |
| defaultProjectTrust | string | Optional | "ask" | Project trust default behavior: "ask" (prompt), "always" (auto-trust), "never" (auto-reject); only effective in global configuration |
| collapseChangelog | boolean | Optional | false | Collapse changelog |
| enableInstallTelemetry | boolean | Optional | true | Anonymous installation statistics |
| enableAnalytics | boolean | Optional | false | User behavior analytics (requires opt-in) |
| doubleEscapeAction | string | Optional | "tree" | Action triggered by double-pressing Escape; defaults to opening the session tree browser |
| treeFilterMode | string | Optional | "default" | /tree default filter mode: default/no-tools/user-only/labeled-only/all |
| editorPaddingX | number | Optional | 0 | Editor horizontal padding (0-3) |
| outputPad | number | Optional | 1 | Message padding (0 or 1) |
| autocompleteMaxVisible | number | Optional | 5 | Maximum autocomplete entries (3-20) |
Network
The configuration in this section is used for proxy access in restricted network environments.
| Configuration Item | Type | Required | Default Value | Description |
|---|---|---|---|---|
| httpProxy | string | Optional | None (no proxy used) | HTTP proxy (global only) |
httpProxyOnly effective in global configuration; it is ignored if written in project-level configuration.
When a proxy is needed, write it into the global configuration.~/.pi/agent/settings.json。
Compression
The configuration in this section controls the triggering and retention policy of automatic context compression.
| Configuration Item | Type | Required | Default Value | Description |
|---|---|---|---|---|
| compaction.enabled | boolean | Optional | true | Automatic compression |
| compaction.reserveTokens | number | Optional | 16384 | Reserved tokens for LLM response |
| compaction.keepRecentTokens | number | Optional | 20000 | Recent tokens to retain |
Branch Summary
The configuration in this section controls whether to generate a summary of abandoned branches when jumping between session trees.
| Configuration Item | Type | Required | Default Value | Description |
|---|---|---|---|---|
| branchSummary.reserveTokens | number | Optional | 16384 | Reserved tokens for summary |
| branchSummary.skipPrompt | boolean | Optional | false | Skip summary prompt |
Retry
The configuration in this section controls automatic retry behavior after request failures.
| Configuration Item | Type | Required | Default Value | Description |
|---|---|---|---|---|
| retry.enabled | boolean | Optional | true | Automatic retry |
| retry.maxRetries | number | Optional | 3 | Maximum number of retries |
| retry.baseDelayMs | number | Optional | 2000 | Base delay (ms) |
| retry.provider.timeoutMs | number | Optional | SDK default | Request timeout |
| retry.provider.maxRetries | number | Optional | 0 | Provider-level retry count |
| retry.provider.maxRetryDelayMs | number | Optional | 60000 | Maximum retry delay |
Message Passing
The configuration in this section determines how directive and follow-up messages are inserted, as well as the transport protocol used.
| Configuration Item | Type | Required | Default Value | Description |
|---|---|---|---|---|
| steeringMode | string | Optional | "one-at-a-time" | Directive message policy: "all" (insert all directive messages immediately) or "one-at-a-time" (insert one by one) |
| followUpMode | string | Optional | "one-at-a-time" | Follow-up message policy |
| transport | string | Optional | "auto" | Transport protocol: sse / websocket / websocket-cached / auto |
| httpIdleTimeoutMs | number | Optional | 300000 | HTTP idle timeout |
| websocketConnectTimeoutMs | number | Optional | 15000 | WebSocket connection timeout |
Terminal and Images
The configuration in this section controls the display size and sending behavior of images in the terminal.
| Configuration Item | Type | Required | Default Value | Description |
|---|---|---|---|---|
| terminal.showImages | boolean | Optional | true | Display images in terminal |
| terminal.imageWidthCells | number | Optional | 60 | Image width (cells) |
| terminal.clearOnShrink | boolean | Optional | false | Clear empty lines when content shrinks |
| images.autoResize | boolean | Optional | true | Automatic image scaling |
| images.blockImages | boolean | Optional | false | Prevent sending images to LLM |
Shell
The configuration in this section is used to customize the shell and npm wrapper when executing commands.
| Configuration Item | Type | Required | Default Value | Description |
|---|---|---|---|---|
| shellPath | string | Optional | None (use system default shell) | Custom shell path |
| shellCommandPrefix | string | Optional | None (no prefix added) | Command prefix |
| npmCommand | string[] | Optional | None (invoke npm directly) | npm command wrapper |
Built-in Tools
The configuration in this section controls the set of built-in tools enabled by default at startup.
| Configuration Item | Type | Required | Default Value | Description |
|---|---|---|---|---|
| defaultTools | string[] | Optional | None (use the built-in default toolset) | Initially enabled built-in tools, optional values: read/bash/powershell/edit/write/grep/find/ls, where powershell is only available on Windows |
This configuration only affects built-in tools; custom tools registered by extensions and the SDK are not affected.
The project-level defaultTools array completely replaces the global array.
Model Loop and Resources
This section configures the Ctrl+P model loop scope, as well as the load paths for resources such as extensions and Skills.
| Configuration item | Type | Required | Default value | Description |
|---|---|---|---|---|
| enabledModels | string[] | Optional | None (all available models) | Ctrl+P available models |
| packages | array (mixed strings or objects) | Optional | [] | Package source; string form loads all resources, object form filters using fields such as {source, skills, extensions} |
| extensions | string[] | Optional | [] | Extension path |
| skills | string[] | Optional | [] | Skill path |
| prompts | string[] | Optional | [] | Template path |
| themes | string[] | Optional | [] | Theme path |
| enableSkillCommands | boolean | Optional | true | Register /skill:name command |
| sessionDir | string | Optional | None (uses ~/.pi/agent/sessions/) | Session storage directory |