pi/packages/coding-agent/docs/settings.md

Settings Reference

This reference lists user-configurable settings, their types, defaults, and purposes. Project settings override agent-directory settings. Resource lists are combined. See Configuration for file locations and trust behavior.

Model and thinking

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.
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.
hideThinkingBlock	boolean	false	Hide thinking blocks in the transcript.
showCacheMissNotices	boolean	false	Show notices for significant cache misses, successful cache warming, compaction usage, and provider recovery.
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 Pi 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. See Prompt Cache Lifetimes.

See Choose a Model for model selection and thinking controls.

Interaction

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.

Tools

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.
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 searchTools(). 0 lists only namespaces.

Available 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, and other extension tools registered inactive.

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

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

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; --tools does not accept +name or -name. See Command Line.

Sessions and context

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

Compaction

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. Each value resolves independently from the matching model override, then the ordinary compaction setting, then the built-in default. Project and user objects merge before model lookup.

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

Branch summaries

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.

Terminal and display

Setting	Type	Default	Description
theme	string	"system"	Built-in or custom theme name. system derives colors from the terminal theme.
quietStartup	boolean	false	Hide the startup header.
tuiMode	"regular" | "fullscreen"	"regular"	Interactive terminal UI mode.
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 Pi 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.

Network and retries

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 applied as HTTP_PROXY and HTTPS_PROXY for Pi-managed HTTP clients. Can only be set in agent-directory settings.
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 Pi from handling quota and usage-limit errors itself.

Shell

Setting	Type	Default	Description
shellPath	string	Platform default	Custom shell executable path. Supports a leading ~.
shellCommandPrefix	string	None	Prefix prepended to every shell command.
npmCommand	string[]	npm	Command and arguments used for npm package lookup and installation.

See Shell aliases for shell setup and Pi Packages for package-manager behavior.

Resources

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

Setting	Type	Default	Description
packages	array	[]	npm, git, or local Pi package sources. See Pi Packages.
extensions	string[]	[]	Extension files or directories.
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.

Resource arrays support glob exclusions with !pattern, exact inclusion with +path, and exact exclusion with -path. Pi loads resources listed in both user-level and project settings.

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. pi config lists them under Built-in. --no-extensions disables them too, and -e builtin:<name> loads one explicitly.

Updates, telemetry, and warnings

Setting	Type	Default	Description
collapseChangelog	boolean	false	Show a condensed changelog after an update.
enableInstallTelemetry	boolean	true	Enable anonymous install/update reporting and selected provider attribution headers. Does not control update checks.
enableAnalytics	boolean	false	Opt in to analytics data sharing. Currently used only by the experimental first-run setup.
warnings.anthropicExtraUsage	boolean	true	Warn when Anthropic subscription authentication may use paid extra usage.