9  Settings

9.1 Overview

Pi settings are stored as JSON files in two locations: global (~/.pi/agent/settings.json) and project-local (.pi/settings.json). Project settings override global settings on a per-key basis.

9.2 Settings Locations

Location Scope Priority
~/.pi/agent/settings.json Global (all projects) Lower
.pi/settings.json Project-local Higher (overrides global)

Use /settings in interactive mode to change common settings visually. Settings changes take effect immediately for most values; restart Pi for changes that affect provider configuration or session storage.

9.3 Model & Thinking

9.3.1 model

Default model pattern or ID.

{
  "model": "claude-sonnet-4-20250514"
}

Supports provider/id syntax and :thinking suffix:

{
  "model": "anthropic/claude-sonnet-4:high"
}

9.3.2 provider

Default provider name. When set, Pi skips provider auto-detection.

{
  "provider": "anthropic"
}

9.3.3 thinkingLevel

Default thinking level for reasoning models.

{
  "thinkingLevel": "medium"
}

Options: "off", "minimal", "low", "medium", "high", "xhigh", "max".

9.3.4 scopedModels

Comma-separated list of model patterns for Ctrl+P / Shift+Ctrl+P cycling.

{
  "scopedModels": "claude-sonnet-4,claude-haiku-4,gpt-5"
}

9.3.5 apiKey

API key to use for the default provider, overriding environment variables.

{
  "apiKey": "sk-ant-..."
}

9.4 UI Settings

9.4.1 theme

Color theme name.

{
  "theme": "default-dark"
}

9.4.2 altScreen

Use the alternate screen buffer.

{
  "altScreen": false
}

9.4.3 externalEditor

External editor command for Ctrl+G.

{
  "externalEditor": "code --wait"
}

9.4.4 verbose

Force verbose startup output.

{
  "verbose": false
}

9.5 Telemetry

9.5.1 telemetry

Controls anonymous usage telemetry.

{
  "telemetry": true
}

Set to false to disable telemetry reporting.

9.6 Network Settings

9.6.1 proxy

HTTP/HTTPS proxy URL for API requests.

{
  "proxy": "http://127.0.0.1:7890"
}

Uses HTTPS_PROXY environment variable by default. Settings value takes priority over the environment variable.

9.7 Warnings

9.7.1 suppressBackupWarning

Suppress the warning about working outside a git repository.

{
  "suppressBackupWarning": false
}

9.8 Compaction

9.8.1 autoCompact

Controls automatic context compaction when approaching context window limits.

{
  "autoCompact": true
}

When enabled, Pi summarizes older messages to free context before hitting the model’s context limit. See the Compaction chapter for details.

9.8.2 compactExcludedTools

Tool names whose results should not be truncated during compaction.

{
  "compactExcludedTools": ["read", "grep"]
}

9.9 Branch Summary

9.9.1 branchSummary

Controls automatic summarization of abandoned session branches in the tree view.

{
  "branchSummary": true
}

When enabled, Pi summarizes branches that were explored but not continued, making it easier to understand the session tree at a glance.

9.10 Retry

9.10.1 retry

Retry configuration for transient API errors.

{
  "retry": {
    "maxRetries": 3,
    "retryDelay": 1000,
    "backoffMultiplier": 2
  }
}

9.11 Message Delivery

9.11.1 steeringMode

Controls how messages typed during agent execution are delivered.

{
  "steeringMode": "queue"
}

Options:

  • "queue" — deliver after current tool calls complete (default)
  • "immediate" — deliver immediately, interrupting the current turn
  • "off" — do not allow steering messages

9.11.2 followUpMode

Controls how follow-up messages (Alt+Enter) are delivered.

{
  "followUpMode": "queue"
}

Same options as steeringMode.

9.12 Terminal Settings

9.12.1 terminalType

Override terminal type detection.

{
  "terminalType": "xterm-256color"
}

9.12.2 shell

Shell to use for bash tool execution. Defaults to the user’s login shell.

{
  "shell": "/bin/zsh"
}

9.12.3 shellArgs

Arguments to pass to the shell.

{
  "shellArgs": ["-l", "-c"]
}

9.13 Sessions

9.13.1 sessionDir

Custom session storage directory.

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

9.13.2 defaultProjectTrust

Default trust decision for new projects.

{
  "defaultProjectTrust": "ask"
}

Options: "ask" (default), "always", "never".

9.14 Model Cycling

9.14.1 modelCycleDirection

Default direction for model cycling with Ctrl+P.

{
  "modelCycleDirection": "forward"
}

9.15 Markdown

9.15.1 markdown

Markdown rendering options.

{
  "markdown": {
    "renderHtml": false,
    "breaks": false
  }
}

9.16 Resources

9.16.1 extensions

Additional extension paths to load.

{
  "extensions": [
    "/path/to/local/extension.ts",
    "/path/to/local/extension/dir"
  ]
}

9.16.2 packages

Pi packages to install.

{
  "packages": [
    "npm:@foo/bar@1.0.0",
    "git:github.com/user/repo@v1"
  ]
}

9.16.3 skills

Additional skill paths to load.

{
  "skills": [
    "/path/to/skill/dir"
  ]
}

9.16.4 prompts

Additional prompt template paths to load.

{
  "prompts": [
    "/path/to/prompts/dir"
  ]
}

9.16.5 themes

Additional theme paths to load.

{
  "themes": [
    "/path/to/theme.json"
  ]
}

9.17 Project Overrides

Project-local settings (.pi/settings.json) override global settings on a per-key basis. For nested objects like retry, the entire object replaces the global value — there is no deep merge.

9.17.1 Example

Global ~/.pi/agent/settings.json:

{
  "model": "claude-sonnet-4",
  "thinkingLevel": "medium",
  "theme": "default-dark"
}

Project .pi/settings.json:

{
  "model": "gpt-5",
  "thinkingLevel": "high"
}

Effective settings for this project:

{
  "model": "gpt-5",
  "thinkingLevel": "high",
  "theme": "default-dark"
}
Tip

Use /settings in interactive mode to view and change common settings without editing JSON files directly. The visual settings panel shows the effective merged configuration.

9.18 Complete Settings Example

{
  "model": "claude-sonnet-4-20250514",
  "provider": "anthropic",
  "thinkingLevel": "medium",
  "scopedModels": "claude-sonnet-4,claude-haiku-4",
  "theme": "default-dark",
  "altScreen": false,
  "externalEditor": "code --wait",
  "verbose": false,
  "telemetry": true,
  "proxy": null,
  "autoCompact": true,
  "branchSummary": true,
  "retry": {
    "maxRetries": 3
  },
  "steeringMode": "queue",
  "followUpMode": "queue",
  "defaultProjectTrust": "ask",
  "packages": [],
  "extensions": [],
  "skills": [],
  "prompts": [],
  "themes": []
}

9.19 Environment Variables

Some settings can also be controlled via environment variables:

Environment Variable Setting
PI_MODEL model
PI_PROVIDER provider
PI_THINKING thinkingLevel
HTTPS_PROXY proxy
PI_THEME theme
PI_ALT_SCREEN altScreen
PI_NO_TELEMETRY telemetry (set to 1 to disable)
PI_SESSION_DIR sessionDir
PI_SHELL shell
PI_SHELL_ARGS shellArgs
PI_EXTERNAL_EDITOR externalEditor
Note

Settings file values take priority over environment variables, which take priority over built-in defaults.