Settings, configuration, and trust

Configuration directory

The runtime resolves the agent configuration directory (<agent-dir>) in this order:

1. PI_CODING_AGENT_DIR environment variable.
2. The platform home directory (HOME on Unix, USERPROFILE on Windows) with /.pi/agent appended.

Source: crates/pi-coding/src/resources.rs:26-41.

Within <agent-dir> the CLI reads:

• settings.json — global startup defaults and operational settings.
• models.json — custom providers and model overrides.
• auth.json — stored provider credentials.
• trust.json — persisted project trust decisions.
• sessions/ — native Pi v3 JSONL session files.
• skills/, prompts/, themes/ — global resources.

Project-local resources are loaded from <workspace>/.pi/ only when that project is trusted. Source: crates/pi-coding/src/resource_manager.rs:49-70.

Project trust

By default, rpi asks before loading project-local .pi resources (skills, prompts, themes, keybindings, extensions, agents, and package settings). Trust decisions are stored in <agent-dir>/trust.json, versioned as TRUST_STORE_VERSION = 1, and scoped to the canonical project path. The resolver walks parent directories, so a decision at <workspace> covers <workspace>/sub-project.

Source: crates/pi-coding/src/trust.rs:67-140 and crates/pi-coding/src/trust.rs:180-216.

Default behavior is controlled by settings.json:

{
  "defaultProjectTrust": "ask"
}

Allowed values:

• "ask" — prompt for trust in interactive modes; treat as untrusted in headless modes (default).
• "always" — trust every project with a .pi directory without asking.
• "never" — never trust project-local resources.

One-run overrides:

rpi -a "hello"           # --approve: trust this project's .pi for this run
rpi --no-approve "hello" # refuse project .pi for this run

Headless modes (--print, --mode json, --mode rpc) never prompt. In headless mode an unset or "ask" decision is treated as untrusted, so use --approve when you need project resources. If the project has no .pi directory, it is implicitly trusted.

Source: crates/pi-coding/src/trust.rs:37-43 and crates/pi-cli/src/args.rs:168-174.

settings.json

Global settings live at <agent-dir>/settings.json. Project settings live at <workspace>/.pi/settings.json and are merged on top of global settings when trusted. Unknown fields are retained across merges so other product modules can use them.

Source: crates/pi-coding/src/settings.rs:666-669 and crates/pi-coding/src/settings.rs:729-843.

{
  "defaultProvider": "openai",
  "defaultModel": "openai/gpt-5",
  "defaultThinkingLevel": "medium",
  "defaultProjectTrust": "ask",
  "theme": "dark",
  "compaction": {
    "enabled": true,
    "reserveTokens": 8192,
    "keepRecentTokens": 4096
  },
  "terminal": {
    "showImages": true,
    "imageWidthCells": 80,
    "clearOnShrink": false,
    "showTerminalProgress": true
  },
  "images": {
    "autoResize": true,
    "blockImages": false
  },
  "retry": {
    "enabled": true,
    "maxRetries": 3,
    "baseDelayMs": 2000,
    "provider": {
      "timeoutMs": 60000,
      "maxRetries": 3,
      "maxRetryDelayMs": 60000
    }
  },
  "transport": "auto",
  "timeoutMs": 60000,
  "maxRetryDelayMs": 60000,
  "temperature": 0.7,
  "maxTokens": 4096,
  "cacheRetention": "short",
  "thinkingBudgets": {
    "minimal": 1024,
    "low": 2048,
    "medium": 4096,
    "high": 8192
  },
  "scopedModels": ["openai/*", "anthropic/*"],
  "branchSummary": {
    "reserveTokens": 16384,
    "skipPrompt": false
  },
  "keybindings": {
    "toggleTheme": "ctrl+t"
  },
  "quietStartup": false,
  "showThinking": true,
  "exposeSessionEnvironment": true,
  "doubleEscapeAction": "tree",
  "orchestration": {
    "process": false,
    "tasks": false,
    "todo": false,
    "maxConcurrency": 8,
    "maxRecursionDepth": 8,
    "mailboxCapacity": 1000,
    "maxToolsPerAgent": 16
  },
  "packages": [
    "git:github.com/owner/pi-my-tools",
    { "source": "./my-pi-tools", "extensions": ["*"] }
  ],
  "extensions": ["ext-id"],
  "skills": ["rust-review"],
  "prompts": ["custom-prompt"],
  "themes": ["solarized"]
}

Known fields

Source: crates/pi-coding/src/settings.rs:342-416, crates/pi-coding/src/settings.rs:970-1096, and crates/pi-coding/src/settings.rs:1104-1129.

Supported operational settings coverage

The following keys are the supported operational settings coverage used by the runtime. Any other field may exist but is either a startup default, a resource list, or module-specific configuration.

Source: crates/pi-coding/src/settings.rs:302-330.

Model and thinking-level precedence

When the CLI starts without an explicit model:

1. --model / -m flag.
2. Resumed session's saved model (when --resume or --continue is used).
3. settings.json defaultModel.
4. First authenticated model in the catalog.

Thinking level precedence:

1. --think flag.
2. Thinking level parsed from a :level model suffix (anthropic/claude-sonnet-4-5:high).
3. Resumed session's saved thinking level.
4. settings.json defaultThinkingLevel.
5. medium.

The final level is clamped to the resolved model's supported levels.

Live reload semantics

Configuration and resources are loaded into an atomic snapshot.

• rpi reload validates the current settings/resource graph and prints a structured snapshot, including generation, trust, discovered resources, and diagnostics. It always runs headlessly and emits JSON.
• SettingsManager::reload() re-reads global settings and, when the project is trusted, project settings, then recomputes the effective snapshot.
• ResourceManager::stage_reload() builds a new candidate snapshot without replacing the active one. commit_reload() swaps the active snapshot only after validation succeeds; any error leaves the previous generation in place.
• Interactive TUI /reload and REPL reload call the same stage-and-commit path, so malformed files never silently replace a working configuration.
• Settings writes performed through update_global or update_project are atomic (temp file + fs::rename + directory sync). Session-only overrides via apply_overrides are never persisted.

Source: crates/pi-cli/src/commands.rs:145-180, crates/pi-coding/src/settings.rs:729-843, and crates/pi-coding/src/resource_manager.rs:139-253.

Trust boundaries

• No project-local configuration is loaded unless the project is trusted. Use -a/--approve or set defaultProjectTrust explicitly.
• approvalMode is a global safety policy and is rejected in project .pi/settings.json; --approval-mode is the explicit one-run override. It is independent of --approve/--no-approve, which control only project resource trust.
• Interactive approval runs before the existing host hook and extension reducer. Headless modes fail closed whenever the selected policy requires confirmation.
• Bash tool commands run in the configured working directory (--cwd).
• API keys are never printed in error messages or logs.
• models.json and auth.json values may contain $VAR / ${VAR} templates, which are expanded from the current process environment or an explicit env map. Command-valued values (!command) are rejected.

Custom config path for tests or isolation

export PI_CODING_AGENT_DIR="<workspace>/.my-pi-config"
mkdir -p "$PI_CODING_AGENT_DIR"
rpi --print "hello"