This reference lists user-configurable settings, their types, defaults, and purposes. Project settings override agent-directory settings. Objects merge one level deep: keys directly inside an object such as compaction merge, but a nested object such as compaction.modelOverrides in project settings replaces the user's whole object. Resource lists are combined. See Configuration for file locations and trust behavior.

Setting	Type	Default	Description
defaultProvider	string	Automatic	Startup AI provider.
defaultModel	string	Automatic	Startup model ID.
defaultThinkingLevel	`"off" \	"minimal" \	"low" \	"medium" \	"high" \	"xhigh" \	"max"`	"medium"	Startup thinking level, clamped to what the model supports.
modelThinkingLevels	object	None	Per-model startup thinking levels keyed by exact provider/modelId.
thinkingBudgets	object	Built-in budgets	Token budgets for minimal, low, medium, and high thinking levels.
enabledModels	string[]	All available models	Model patterns used for startup selection and model cycling. Uses the same format as --models. /scoped-models writes it.
fallbackModels	string[]	None	pig-only. Model patterns, in --models format, that a turn moves on to, in order, when the current model has run out of quota.
hideThinkingBlock	boolean	false	Hide thinking blocks in the transcript.
showCacheMissNotices	boolean	false	Show notices for significant cache misses (20,000 tokens or $0.10 and up), cache warming, compaction and branch-summary cost, and dropped thinking blocks; /session adds the total re-billed.
cacheWarming	`"off" \	"streaming" \	"idle"`	"streaming"	Keep eligible provider prompt caches warm during active runs or, with "idle", between runs. Global setting only.

Cache warming runs only when the model declares a cache lifetime and pig estimates at least $0.05 in avoided cache-miss cost. Refresh usage counts toward session totals but does not enter model context. /session shows the next decision; extensions can override it with cache_warming_decision. Only the interactive terminal and --mode rpc warm; -p and --mode json end with their answer and never do. See Prompt Cache Lifetimes.

See Choose a Model for model selection and thinking controls.

Setting	Type	Default	Description
steeringMode	`"all" \	"one-at-a-time"`	"one-at-a-time"	How queued steering messages are delivered.
followUpMode	`"all" \	"one-at-a-time"`	"one-at-a-time"	How queued follow-up messages are delivered.
externalEditor	string	$VISUAL, $EDITOR, then platform default	Command opened by the external-editor keybinding.
doubleEscapeAction	`"tree" \	"fork" \	"none"`	"tree"	Action for double Escape with an empty editor.
treeFilterMode	`"default" \	"no-tools" \	"user-only" \	"labeled-only" \	"all"`	"default"	Initial filter used by /tree.
defaultProjectTrust	`"ask" \	"always" \	"never"`	"ask"	Fallback project-trust behavior. Can only be set in agent-directory settings.

Setting	Type	Default	Description
defaultTools	string[]	read, bash, edit, write	Tools enabled at startup. Plain names replace the defaults; +name adds a tool and -name removes one. An empty array disables all built-in tools but not extension or SDK tools. Extension tools are active unless a -name removes them, except tools registered inactive, such as codemode, which are on only when named.
codemode.mode	"on" \	"only"	"on"	How the codemode tool presents tools while it is active. on: declared tools get their codemode declaration appended to their description, and codemode lists only tools that are not declared (MCP codemode exposure). only: codemode lists every tool scripts can call, and active built-in and extension tools are hidden from the model, so it reaches them through codemode.
codemode.inlineBudget	number	3000	Estimated tokens (characters / 4) the codemode tool's description may spend on tool declarations. Tools that do not fit are left out and found with search_tools(). 0 lists only namespaces.

Available built-in tools are read, bash, powershell, edit, write, grep, find, and ls. codemode is registered inactive, so naming it turns it on:

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

tool_search is registered automatically while any deferred MCP tool is listed.

A list of only +name and -name entries changes the inherited selection instead of replacing it. For example, this replaces bash with powershell and enables grep: ["-bash", "+powershell", "+grep"]. Project settings apply on top of user settings: a project list with only +name and -name entries changes the user's selection, and a project list with a plain name replaces it. In one list, plain names form the selection, and +name and -name then apply in order.

CLI tool options override this setting for one invocation. See Command Line.

Setting	Type	Default	Description
sessionDir	string	Agent session directory	Session storage directory. Relative paths resolve from the working directory. PIG_CODING_AGENT_SESSION_DIR and --session-dir override this setting.

Setting	Type	Default	Description
compaction.enabled	boolean	true	Enable automatic compaction.
compaction.reserveTokens	number	16384	Tokens reserved for the model response.
compaction.keepRecentTokens	number	20000	Recent tokens retained without summarization.
compaction.modelOverrides	object	None	Per-model token settings keyed by exact provider/modelId.

Compaction token values must be non-negative safe integers; 0 is allowed, and an invalid value is an error when it is read. Each value resolves independently from the matching model override, then the ordinary compaction setting, then the built-in default. A project compaction.modelOverrides object replaces the user's rather than merging with it.

See Compaction Reference for trigger, summarization, and validation behavior.

Setting	Type	Default	Description
branchSummary.reserveTokens	number	16384	Tokens reserved when summarizing branch history.
branchSummary.skipPrompt	boolean	false	Skip the branch-summary prompt and default to no summary.

Setting	Type	Default	Description
theme	string	"system"	Built-in or custom theme name. system derives colors from the terminal theme.
quietStartup	`boolean \	"header"`	false	true hides the startup header and loaded resources; "header" keeps the header and hides the resources.
tuiMode	`"regular" \	"fullscreen"`	"regular"	Interactive terminal UI mode (tui.mode is also read).
fullscreenExitOutput	`"transcript" \	"resume-hint"`	"transcript"	Output printed when fullscreen mode exits.
fullscreenScrollbar	`"auto" \	"always" \	"hidden"`	"auto"	Fullscreen transcript scrollbar behavior.
fullscreenCopyOnSelect	boolean	true	Copy selected text automatically in fullscreen mode.
fullscreenWheelScrollLines	"auto" \	number	"auto"	Lines per mouse-wheel event in fullscreen mode, from 1 to 100. "auto" moves one line per event in local macOS terminals, which already accelerate wheel and trackpad input; elsewhere, and over SSH, it speeds up fast wheel spins to at most 6 lines per event. Alt+wheel moves five times as far.
editorPaddingX	number	0	Horizontal editor padding from 0 to 3 cells.
outputPad	`0 \	1`	1	Horizontal transcript padding.
autocompleteMaxVisible	number	5	Visible autocomplete entries, from 3 to 20.
showHardwareCursor	boolean	false	Show the terminal cursor while pig positions it for input methods.
terminal.showImages	boolean	true	Display inline images when supported.
terminal.imageWidthCells	number	60	Preferred inline image width in terminal cells.
terminal.clearOnShrink	boolean	false	Clear empty rows when rendered content shrinks.
terminal.showTerminalProgress	boolean	false	Show OSC 9;4 progress in the terminal tab.
terminal.hyperlinks	`boolean \	"auto"`	"auto"	Override OSC 8 hyperlink detection.
terminal.images	`"kitty" \	"iterm2" \	"auto" \	false`	"auto"	Override inline-image protocol detection.
terminal.trueColor	`boolean \	"auto"`	"auto"	Override true-color detection.
images.autoResize	boolean	true	Resize images to at most 2000 by 2000 pixels before sending them to a model.
images.blockImages	boolean	false	Prevent images from being sent to models.
markdown.codeBlockIndent	string	" "	Prefix used to indent rendered code blocks.
markdown.mermaid	`"off" \	"final" \	"streaming"`	"streaming"	Mermaid rendering mode.

See Themes and Terminal Setup for format and platform details.

Setting	Type	Default	Description
transport	`"auto" \	"sse" \	"websocket" \	"websocket-cached"`	"auto"	Preferred transport for AI providers that support multiple transports.
httpProxy	string	None	Proxy URL that fills an unset HTTP_PROXY or HTTPS_PROXY for pig-managed HTTP clients. Can only be set in agent-directory settings.
proxy.bypass	string[]	[]	Hosts to reach directly, added to no_proxy. An empty list leaves no_proxy as it is. Loopback is always direct.
httpIdleTimeoutMs	number	300000	HTTP header and body idle timeout in milliseconds. Set to 0 to disable.
websocketConnectTimeoutMs	number	15000	WebSocket connection timeout in milliseconds. Set to 0 to disable.
retry.enabled	boolean	true	Enable automatic agent-level retry for transient failures.
retry.maxRetries	number	3	Maximum agent-level retry attempts.
retry.baseDelayMs	number	2000	Initial exponential-backoff delay in milliseconds.
retry.maxAgentDelayMs	number	60000	Maximum agent-level retry delay in milliseconds.
retry.provider.timeoutMs	number	httpIdleTimeoutMs	Provider request timeout in milliseconds.
retry.provider.maxRetries	number	0	Provider-level retry attempts.
retry.provider.maxRetryDelayMs	number	60000	Maximum server-requested delay in milliseconds. Set to 0 to disable the limit.

Keep retry.provider.maxRetries at 0 unless provider-level retries are required. Provider retries can delay pig from handling quota and usage-limit errors itself.

Setting	Type	Default	Description
shellPath	string	Platform default	Custom shell executable path. Supports a leading ~ and file:// URLs. A path that does not exist is an error (Custom shell path not found).
shellCommandPrefix	string	None	Prefix prepended to every shell command.

Without shellPath, pig uses /bin/bash, then bash on PATH, then sh on Unix, and Git Bash (under ProgramFiles or ProgramFiles(x86)) or bash.exe on PATH on Windows. See Shell aliases for shell setup.

Resource paths in user settings resolve from the agent directory. Paths in project settings resolve from the project .pig directory. Absolute paths and ~ are supported.

Setting	Type	Default	Description
packages	array	[]	Git or local pig package sources. See pig Packages.
extensions	string[]	[]	Extension files or directories.
disabledExtensions	string[]	[]	Bundled or installed extensions not to load, by directory name.
hooks	string[]	[]	Hook files on top of <agent-dir>/hooks and .pig/hooks.
customTools	string[]	[]	Custom tool entry files on top of <agent-dir>/tools and .pig/tools.
skills	string[]	[]	Skill files or directories.
prompts	string[]	[]	Prompt-template files or directories.
themes	string[]	[]	Theme files or directories.
enableSkillCommands	boolean	true	Register skills as /skill:name commands.

skills, prompts, and themes are lists of strings. Resource arrays support glob exclusions with !pattern, exact inclusion with +path, and exact exclusion with -path. pig loads resources listed in both user-level and project settings. The older object form of skills is reported as a problem and ignored; enableSkillCommands is a top-level setting.

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 disables one. A +builtin:<name> or -builtin:<name> entry in project settings overrides the user setting. pig config lists them under Built-in. --no-extensions disables them too, and -e builtin:<name> loads one explicitly.

Setting	Type	Default	Description
collapseChangelog	boolean	false	Show a condensed changelog after an update.
update.check	boolean	true	Ask Packagist at startup whether a newer pig exists. --no-update-check and --update-check override it for one run.
enableInstallTelemetry	boolean	true	Send the provider attribution headers that tell OpenRouter, NVIDIA and Cloudflare pig is the client. pig sends no install report. Does not control update checks.
warnings.anthropicExtraUsage	boolean	true	Warn when Anthropic subscription authentication may use paid extra usage.