Settings

PiG reads settings from ~/.pig/agent/settings.json. The file is optional. Every key is optional, and a key you leave out keeps its default. PiG uses the settings keys of Pi 1.5.0 (Pi's settings reference) and adds the PiG-only keys marked below.

Set PIG_HOME to move the whole configuration root. Set PIG_CODING_AGENT_DIR to move only this directory.

{
  "defaultProvider": "anthropic",
  "defaultModel": "claude-sonnet-4",
  "theme": "dark",
  "compaction": { "enabled": true }
}

Add "$schema": "https://pi.dev/schemas/settings.schema.json" to settings.json for editor validation and completion. PiG keeps the key when it writes the file. The schema is the one Pi 1.5.0 publishes. It does not list the PiG-only keys, but it accepts them.

Use /settings to change a setting from inside a session. PiG writes the file for you and applies the change without a restart.

Settings by example shows the common keys at work, with the output to expect.

Where PiG reads settings

PiG merges two files. A key set in the project file overrides the same key in the global file. Resource lists are combined. defaultProjectTrust, httpProxy, cacheWarming, extensionsAutoUpgrade and extensionsTypescriptRuntime are global settings: PiG ignores them in the project file.

PiG reads the project file only after you trust the project. An untrusted project contributes nothing, so cloning a repository cannot change your shell, your model or your packages before you agree to it. See Security.

If PiG is killed (kill -9, power loss), it can leave settings.json.lock next to the settings file. A lock younger than 10 seconds counts as held, so the next start waits about 0.2 seconds for each settings load, then warns Invalid settings file ...: Lock file is already being held and goes on with the defaults it has. After 10 seconds the lock is taken over. You can also delete the settings.json.lock directory. Pi behaves the same way.

A value of the wrong JSON type, such as {"skills": 5} or {"enabledModels": [5]}, is ignored, and PiG applies the other settings of the file. PiG prints one warning for each file that held such values, for example Warning: Invalid settings file <path>: ignored settings of the wrong type: "skills" (expected an array of strings). Pi 1.5.0 exits with a TypeError for these values, or reads a string as a list of one-character patterns (D158).

An empty default column means PiG has no value for the key until you set one, or the value depends on what it detects.

Models and providers

Provider retries

Keep retry.provider.maxRetries at 0 unless you need provider-level retries. Provider retries can delay PiG's own handling of quota and usage-limit errors.

Cache warming

Cache warming is on by default, as in Pi. Each refresh is a real provider request that you pay for. PiG replays the last request with a one-token output limit shortly before the prompt cache expires, so the next request reads the cache instead of writing it again at full price.

• off: PiG never sends refreshes.
• streaming: only while the agent is running. This is the default.
• idle: while the agent runs, and between runs for up to 30 minutes after the last request.

A refresh is sent only when the model declares a prompt cache lifetime and PiG expects it to save at least $0.05 in avoided cache-miss cost. Warming stops when the conversation or model changes, after one hour (30 minutes when idle), and when the session ends. Refresh usage counts toward the session's token and cost totals, but it never enters the model's context. /session shows the mode, the next decision, and its estimated cost. An extension can change the decision with a cache_warming_decision handler.

To turn cache warming off, choose off for Cache warming in /settings, or set it in ~/.pig/agent/settings.json:

{
  "cacheWarming": "off"
}

Session behavior

Interface

Images and terminal

Resources

Resource paths in the global file resolve from the agent directory. Paths in the project file resolve from the project's .pig directory. Absolute paths and a leading ~ work. Resource lists accept glob exclusions with !pattern, exact inclusion with +path, and exact exclusion with -path. A leading ~ in these patterns expands to your home directory, for example !~/claude-backup/skills/pdf, as in Pi 1.5.0. Pi 1.1.0 matched the ~ literally, so such a pattern matched nothing (Pi #10765).

The built-in extensions are named builtin:mcp, builtin:llama.cpp, builtin:codemode, and builtin:tool-search in extensions. They load by default; -builtin:mcp turns one off. A +builtin:<name> or -builtin:<name> entry in the project file overrides the global file. pig config lists them under Built-in. --no-extensions turns them off too, and -e builtin:<name> loads one explicitly.

Terminal capability overrides

A setting wins over the matching PI_HYPERLINKS, PI_IMAGE_PROTOCOL or PI_TRUE_COLOR variable, and the variable wins over detection. "auto" and any other value leave detection in charge. Without true color, PiG draws the theme in the 256-color palette, as Pi does. See terminal setup.

Shell and tools

Tools

See Codemode and tool search for codemode and MCP servers for the servers that turn it on.

A list of only +name and -name entries changes the inherited selection instead of replacing it, so a project can adjust the tools a user chose. For example, this enables codemode next to the default tools:

{
  "defaultTools": ["+codemode"]
}

This list replaces bash with powershell and enables grep: ["-bash", "+powershell", "+grep"]. In one list, plain names form the selection, and +name and -name then apply in order.

/reload enables tools newly added to defaultTools. It does not turn off tools removed from it or turn on unchanged tools you turned off. --tools with plain names, --no-tools and --no-builtin-tools override defaultTools, also on reload. --tools with only +name and -name entries changes the defaultTools selection instead, and a tool removed with -name stays removed after /reload.

The built-in tools are read, bash, powershell, edit, write, grep, find, and ls. defaultTools can also name codemode and tool_search, which built-in extensions register inactive. The CLI tool options override this setting for one run. See Tools.

Notices

Related

• Environment variables lists runtime overrides.
• Keybindings covers keybindings.json.
• Models covers model selection.