Chapter 7 · Settings and Project Trust

Chapter goals: Master the priority and常用配置项 of pi's全局/项目两级 settings.json; understand the Project Trust安全机制; learn to manage telemetry switches and速查常用环境变量.

7.1 Two-Level Settings Files and Priority

pi's settings are纯 JSON files with only two levels:

Location	Scope
`~/.pi/agent/settings.json`	Global (all projects)
`.pi/settings.json`	Project (current directory; overrides global)

There are两条路 to改 config daily: type /settings in interactive mode to修改常用项, or直接 edit the JSON. A typical全局配置:

jsonc

// ~/.pi/agent/settings.json
{
  "defaultProvider": "anthropic",
  "defaultModel": "claude-sonnet-4-20250514",
  "defaultThinkingLevel": "medium",
  "theme": "dark",
  "enabledModels": ["claude-*", "gpt-4o"],
  "compaction": {
    "enabled": true,
    "reserveTokens": 16384
  },
  "retry": { "enabled": true, "maxRetries": 3 }
}

Nested objects are merged not整体 replaced — this is the最容易踩的坑:

jsonc

// Global
{ "theme": "dark", "compaction": { "enabled": true, "reserveTokens": 16384 } }

// Project .pi/settings.json
{ "compaction": { "reserveTokens": 8192 } }

// Merged result: theme=dark (inherited), enabled=true (inherited), reserveTokens=8192 (overridden)
{ "theme": "dark", "compaction": { "enabled": true, "reserveTokens": 8192 } }

7.2 Quick Reference for Common Settings

There are many settings;先记住最常用的几组 (完整清单见 /settings and the official docs/settings.md):

jsonc

{
  // Model and thinking
  "defaultThinkingLevel": "high",     // off/minimal/low/medium/high/xhigh/max
  "thinkingBudgets": { "high": 32768 },

  // UI
  "externalEditor": "code --wait",    // Ctrl+G external editor; VS Code必须带 --wait
  "quietStartup": true,               // Hide the startup banner

  // Tools: built-in tools enabled at startup (extension/SDK custom tools不受影响)
  "defaultTools": ["bash", "edit", "write"],

  // Session storage dir; priority: --session-dir > PI_CODING_AGENT_SESSION_DIR > this setting
  "sessionDir": ".pi/sessions",

  // Network
  "httpProxy": "http://127.0.0.1:7890"   // Only effective in the global setting
}

Two-Layer Structure of Retry Settings

retry.maxRetries (default 3) controls pi's own exponential-backoff retries (2s/4s/8s); retry.provider.maxRetries defaults to 0; the官方明确建议保持为 0 — raising it会让 SDK层 retries抢在 pi之前处理 "rate limited"等错误;某些情况下会把 agent卡到配额重置为止.

7.3 Project Trust: Why "Trust" a Project

pi's extensions, skills, and packages are all resources that can execute任意代码; and they can be藏 in the project repo's .pi/ directory. Clone a恶意仓库 then open pi; if project resources auto-execute, the attack是 complete. Project Trust is这道防线:

At interactive mode启动时, if the project contains项目级设置/资源 and no saved trust决定 has been made, pi弹出询问; only after trusting will it加载 .pi/settings.json, install项目包, and执行项目扩展;
The trust决定 is saved in ~/.pi/agent/trust.json; in interactive mode you can also随时用 /trust to save the current project's trust (written;需重启 pi生效);
Non-interactive modes (-p, --mode json, --mode rpc) do not弹窗; falling back to the global setting defaultProjectTrust:

jsonc

// ~/.pi/agent/settings.json —常见 config on CI machines
{
  "defaultProjectTrust": "never"   // ask (default) / always / never
}

bash

# One-shot override (does not写入 trust.json):
pi -p "Run tests" --approve     # Trust project resources this run
pi -p "Run tests" --no-approve  # Ignore project resources this run

The Meaning of the Security Default

The default value is ask —宁可多问一次. If you发现 a team member图省事把 CI configured to always; show them the security model from Chapter 18.

7.4 Telemetry and Update Checks

pi has two mutually independent startup network behaviors; closing one does not关闭 the other:

Behavior	Access Target	How to Disable
Update check	`pi.dev/api/latest-version`	`PI_SKIP_VERSION_CHECK=1`
Install/update telemetry (anonymous version ping + partial provider attribution headers)	`pi.dev/api/report-install`	`enableInstallTelemetry: false` in settings or `PI_TELEMETRY=0`

bash

#一刀切: disable上述全部启动 network behaviors (including package update checks)
pi --offline
# Or via env var
PI_OFFLINE=1 pi

7.5 Environment Variable Quick Reference

Env vars分三类;先分清类别 when排查问题 (完整表见 the official docs/environment-variables.md):

bash

# ① pi process config类
PI_CODING_AGENT_DIR=~/.pi/agent      # Config dir (default;可覆盖)
PI_CODING_AGENT_SESSION_DIR=...      # Session storage dir (--session-dir优先级更高)
PI_OFFLINE=1                         # Disable全部启动 network ops
PI_SKIP_VERSION_CHECK=1              # Only disable the version check
PI_TELEMETRY=0                       # Close telemetry and attribution headers

# ② Process marker类 (pi自动设置给子进程)
AI_AGENT=pi                          # Generic marker
PI_CODING_AGENT=true                 # pi-exclusive marker (not auto-set when SDK嵌入)

# ③ Bash tool session env类 (可读 when the LLM calls bash)
PI_SESSION_ID / PI_SESSION_FILE      # Current session ID / JSONL file path
PI_PROVIDER / PI_MODEL               # Current model provider / model ID
PI_REASONING_LEVEL                   # Current reasoning level

The第③ class is最有趣: the model itself也能感知 session state. The官方建议 the model answer "what model are you using" by directly reading the vars rather than guessing:

bash

# Have the agent执行 in a pi session:
printf '%s/%s\n' "$PI_PROVIDER" "$PI_MODEL"
printf 'reasoning=%s session=%s\n' "$PI_REASONING_LEVEL" "$PI_SESSION_ID"

Note: these vars only注入 into bash tools可 called by the LLM; they do not inject into your manually输入 !/!! commands; after switching models; the next bash command拿到的就是新值;无需重启.

Chapter Summary

Settings只有两级: global ~/.pi/agent/settings.json and project .pi/settings.json; nested objects merged; scalars overridden;
defaultProjectTrust (ask/always/never) is the非交互模式的信任回落值; trust records在 ~/.pi/agent/trust.json; --approve/--no-approve可单次覆盖;
Update checks (PI_SKIP_VERSION_CHECK=1) and telemetry (PI_TELEMETRY=0) are两件事; --offline关闭全部;
Env vars三类: process config, process markers, bash tool session env; PI_PROVIDER/PI_MODEL etc.解析 at each command start.

🧪 随堂测验

点击你认为正确的选项。答错时会展示正确答案与原因解析。

1. The global settings have compaction with enabled and reserveTokens fields; the project setting only写了 reserveTokens: 8192. What is生效 in the最终项目?

2. In CI's -p non-interactive mode; when the project has never保存过 a trust决定; how does pi handle project-level resources?

3. Regarding update checks and telemetry; which statement is correct?

4. When does the PI_MODEL variable in the bash tool env取值?

🛠️ Hands-on Practice

Configure a global settings.json: default model, quietStartup: true, sessionDir pointing to a自定义目录; restart and验证生效.
In a project .pi/settings.json only覆盖 compaction.reserveTokens; confirm其他 compaction子项从全局继承而非丢失.
In an "untrusted"项目分别用 --approve and --no-approve run -p mode;观察项目扩展加载行为的差异.

After completing the exercises, proceed to Chapter 8: Prompt Templates.

Chapter 7 · Settings and Project Trust ​

7.1 Two-Level Settings Files and Priority ​

7.2 Quick Reference for Common Settings ​

7.3 Project Trust: Why "Trust" a Project ​

7.4 Telemetry and Update Checks ​

7.5 Environment Variable Quick Reference ​

Chapter Summary ​

🧪 随堂测验

🛠️ Hands-on Practice ​

Chapter 7 · Settings and Project Trust

7.1 Two-Level Settings Files and Priority

7.2 Quick Reference for Common Settings

7.3 Project Trust: Why "Trust" a Project

7.4 Telemetry and Update Checks

7.5 Environment Variable Quick Reference

Chapter Summary

🛠️ Hands-on Practice