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.

Scope	Path
global	`~/.pig/agent/settings.json`
project	`<project>/.pig/settings.json`

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

Key	Type	Default	Meaning
`defaultProvider`	string		Provider used when none is chosen.
`defaultModel`	string		Model used when none is chosen.
`defaultThinkingLevel`	string		Thinking level applied to a new session.
`modelThinkingLevels`	object		Thinking level for a new session per model, keyed by `provider/modelId`. It overrides `defaultThinkingLevel`.
`enabledModels`	string[]	`all`	Models offered in the model selector.
`thinkingBudgets`	object		Token budget per thinking level: `minimal`, `low`, `medium`, `high`.
`transport`	string		HTTP transport used for provider calls.
`retry`	object		Retry policy: `enabled`, `maxRetries`, `baseDelayMs`, `maxAgentDelayMs` (the cap on each retry delay, default `60000`), and a per-`provider` override. An explicit `0` is kept.
`httpIdleTimeoutMs`	number	`300000`	Idle timeout for provider requests, in milliseconds. `0` or `"disabled"` turns it off.

Session behavior

Key	Type	Default	Meaning
`compaction`	object		Automatic compaction: `enabled`, `reserveTokens`, `keepRecentTokens`, and `modelOverrides` (per-model `reserveTokens` and `keepRecentTokens` keyed by exact `provider/modelId`).
`branchSummary`	object		Summary written when a session branches.
`defaultTools`	string[]	`read`, `bash`, `edit`, `write`	Built-in tools active in a new session.
`steeringMode`	string	`one-at-a-time`	How queued steering messages are dispatched.
`followUpMode`	string	`one-at-a-time`	How queued follow-up messages are dispatched.
`sessionDir`	string		Directory that holds session files.
`defaultProjectTrust`	string		Trust decision applied to a project that has none.

Interface

Key	Type	Default	Meaning
`theme`	string		Active theme name.
`tuiMode`	string	`regular`	`regular` or `fullscreen`.
`fullscreenScrollbar`	string		Scrollbar behavior in fullscreen mode.
`hideThinkingBlock`	boolean	`false`	Hide thinking blocks in the transcript.
`doubleEscapeAction`	string	`tree`	Action bound to pressing escape twice.
`treeFilterMode`	string	`default`	Filter `/tree` opens with.
`editorPaddingX`	number		Horizontal padding inside the editor.
`outputPad`	number		Padding around tool output.
`autocompleteMaxVisible`	number		Rows shown in the autocomplete list.
`showHardwareCursor`	boolean	`false`	Show the terminal's own cursor.
`markdown`	object		Markdown rendering: `codeBlockIndent`, `mermaid`.
`quietStartup`	boolean	`false`	Suppress the startup banner.
`collapseChangelog`	boolean	`false`	Show a condensed changelog.
`lastChangelogVersion`	string		Last changelog version shown. PiG writes this.

Images and terminal

Key	Type	Default	Meaning
`showImages`	boolean		Render images when the terminal accepts them.
`imageWidthCells`	number		Width of a rendered image, in terminal cells.
`imageAutoResize`	boolean		Resize an image to fit the width.
`blockImages`	boolean		Refuse images entirely.
`images`	object		Image settings group. The individual keys above override it.
`terminal`	object		Terminal capability overrides.
`clearOnShrink`	boolean	`false`	Repaint the screen when content shrinks.

Resources

Key	Type	Default	Meaning
`packages`	object[]		Packages to load. See packages.
`extensions`	string[]		Extension paths to load. See extensions.
`skills`	string[]		Skill paths to load. See skills.
`prompts`	string[]		Prompt paths to load.
`themes`	string[]		Theme paths to load.
`enableSkillCommands`	boolean	`true`	Offer skills as slash commands.

Shell and tools

Key	Type	Default	Meaning
`shellPath`	string		Shell used by the bash tool.
`shellCommandPrefix`	string		Prefix applied to every shell command.
`commandPrefix`	string		Former name of `shellCommandPrefix`. PiG still reads it.
`externalEditor`	string		Editor opened by `app.editor.external`.
`npmCommand`	string[]		Command used to run npm.

Notices

Key	Type	Default	Meaning
`warnings`	object		Which warnings are shown.
`showCacheMissNotices`	boolean		Report a prompt cache miss.
`enableInstallTelemetry`	boolean	`true`	Gate for the anonymous install/update ping and the pig-branded OpenRouter, NVIDIA, and Cloudflare attribution headers. The ping is not active yet: PiG has no endpoint to send it to. Override with `PI_TELEMETRY`.
`enableAnalytics`	boolean	`false`	Opt in to analytics data sharing. PiG stores the choice; nothing sends data.
`trackingId`	string		Analytics tracking identifier. PiG writes this on the first opt-in and keeps it when you toggle `enableAnalytics`. Bug reports omit it.

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

PiG Documentation