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.

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

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

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

Where PiG reads settings

PiG merges two files. A key set in the project file overrides the same key in the global file. defaultProjectTrust is the exception: PiG reads it from the global file only.

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.

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

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.

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

PiG also reads the older flat keys showImages, imageWidthCells, clearOnShrink, imageAutoResize, and blockImages. A nested key wins over the flat key with the same meaning.

Resources

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

The built-in tools are read, bash, powershell, edit, write, grep, find, and ls. 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.