Settings

Pi uses JSON settings files with project settings overriding global settings.

Edit directly or use /settings for common options.

All Settings

Model & Thinking

thinkingBudgets

{
  "thinkingBudgets": {
    "minimal": 1024,
    "low": 4096,
    "medium": 10240,
    "high": 32768
  }
}

UI & Display

Telemetry and update checks

enableInstallTelemetry only controls the anonymous install/update ping to https://pi.dev/api/report-install. Opting out of telemetry does not disable update checks; Pi can still fetch https://pi.dev/api/latest-version to look for the latest version.

Set PI_SKIP_VERSION_CHECK=1 to disable the Pi version update check. Use --offline or PI_OFFLINE=1 to disable all startup network operations described here, including update checks, package update checks, and install/update telemetry.

Warnings

{
  "warnings": {
    "anthropicExtraUsage": false
  }
}

Compaction

{
  "compaction": {
    "enabled": true,
    "reserveTokens": 16384,
    "keepRecentTokens": 20000
  }
}

Branch Summary

Retry

When a provider requests a retry delay longer than retry.provider.maxRetryDelayMs (e.g., Google's "quota will reset after 5h"), the request fails immediately with an informative error instead of waiting silently. Set to 0 to disable the cap.

{
  "retry": {
    "enabled": true,
    "maxRetries": 3,
    "baseDelayMs": 2000,
    "provider": {
      "timeoutMs": 3600000,
      "maxRetries": 0,
      "maxRetryDelayMs": 60000
    }
  }
}

Message Delivery

Terminal & Images

Shell

{
  "npmCommand": ["mise", "exec", "node@20", "--", "npm"]
}

npmCommand is used for all npm package-manager operations, including installs, uninstalls, and dependency installs inside git packages. Use argv-style entries exactly as the process should be launched. When npmCommand is configured, git package dependency installs use plain install to avoid npm-specific flags in wrappers or alternate package managers.

Normally the package manager's global modules location is queried using root -g. As a special case, if the first element of npmCommand is "bun", the modules location will instead be queried with pm bin -g.

Sessions

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

When multiple sources specify a session directory, precedence is --session-dir, PI_CODING_AGENT_SESSION_DIR, then sessionDir in settings.json.

Model Cycling

{
  "enabledModels": ["claude-*", "gpt-4o", "gemini-2*"]
}

Markdown

Resources

These settings define where to load extensions, skills, prompts, and themes from.

Paths in ~/.pi/agent/settings.json resolve relative to ~/.pi/agent. Paths in .pi/settings.json resolve relative to .pi. Absolute paths and ~ are supported.

Arrays support glob patterns and exclusions. Use !pattern to exclude. Use +path to force-include an exact path and -path to force-exclude an exact path.

packages

String form loads all resources from a package:

{
  "packages": ["pi-skills", "@org/my-extension"]
}

Object form filters which resources to load:

{
  "packages": [
    {
      "source": "pi-skills",
      "skills": ["brave-search", "transcribe"],
      "extensions": []
    }
  ]
}

See packages.md for package management details.

Example

{
  "defaultProvider": "anthropic",
  "defaultModel": "claude-sonnet-4-20250514",
  "defaultThinkingLevel": "medium",
  "theme": "dark",
  "compaction": {
    "enabled": true,
    "reserveTokens": 16384,
    "keepRecentTokens": 20000
  },
  "retry": {
    "enabled": true,
    "maxRetries": 3
  },
  "enabledModels": ["claude-*", "gpt-4o"],
  "warnings": {
    "anthropicExtraUsage": true
  },
  "packages": ["pi-skills"]
}

Project Overrides

Project settings (.pi/settings.json) override global settings. Nested objects are merged:

// ~/.pi/agent/settings.json (global)
{
  "theme": "dark",
  "compaction": { "enabled": true, "reserveTokens": 16384 }
}

// .pi/settings.json (project)
{
  "compaction": { "reserveTokens": 8192 }
}

// Result
{
  "theme": "dark",
  "compaction": { "enabled": true, "reserveTokens": 8192 }
}