PiLot Studio settings live in two places:

VS Code settings under the pi-agent.* namespace, editable from the Settings UI or settings.json.
The Preferences tab inside PiLot Studio, which exposes the settings people change most often and opens PI's configuration files.

Settings that affect the PI runtime usually take effect on the next session, or rebuild the current session with its transcript preserved. The panel tells you when a change applies only to new sessions.

Settings read by PiLot Studio 3.0.0

Setting	Default	What it controls
`pi-agent.binaryPath`	`"pi"`	Command name or absolute path for the `pi` executable.
`pi-agent.agentDir`	`""` (uses `~/.pi/agent`)	PI's data directory for auth, models, settings, sessions, MCP, and trust. Reload the window after changing it.
`pi-agent.sessionDir`	`""`	Optional subdirectory inside the agent directory for sessions.
`pi-agent.offline`	`false`	Skips PiLot's background update and package checks. Model requests still use the network.
`pi-agent.autoUpdate`	`false`	Opens a terminal and runs `pi update` when a newer PI release is detected.
`pi-agent.thinkingLevel`	`"medium"`	Initial reasoning level for new sessions. The header controls the live session.
`pi-agent.toolPreset`	`"default"`	`default`, `review` (read-only), `none`, or `custom`.
`pi-agent.customTools`	`[]`	Tool names used when the preset is `custom`. An empty list means no tools.
`pi-agent.disableContextFiles`	`false`	Starts PI with `--no-context-files` (no `AGENTS.md`/`CLAUDE.md` discovery).
`pi-agent.systemPrompt`	`null`	Replaces PI's default system prompt for new runs.
`pi-agent.appendSystemPrompts`	`[]`	Appends text to the system prompt, in order.
`pi-agent.extraExtensions`	`[]`	Additional extension files or directories, passed as `--extension` values.
`pi-agent.extraSkills`	`[]`	Additional skill files or directories, passed as `--skill` values.
`pi-agent.extraPromptTemplates`	`[]`	Additional prompt template paths.
`pi-agent.disableExtensionDiscovery`	`false`	Starts PI with `--no-extensions`; explicit extra paths still load.
`pi-agent.disableSkillDiscovery`	`false`	Starts PI with `--no-skills`.
`pi-agent.disablePromptTemplateDiscovery`	`false`	Starts PI with `--no-prompt-templates`.
`pi-agent.lightMode`	`false`	Reduced runtime for local models; see Light Mode.
`pi-agent.disabledSkills`	`[]`	Skill keys disabled from the Skills panel.
`pi-agent.disabledPackages`	`[]`	Package sources disabled from the Packages panel.
`pi-agent.context.autoAttach`	`true`	Prepends the project preamble (root, package name, version) to prompts. Forced off in Light Mode.
`pi-agent.voice.enabled`	`true`	Shows the microphone and enables local dictation.
`pi-agent.voice.model`	`"tiny-q5_1"`	Local whisper model.
`pi-agent.diagnostics.enabled`	`false`	Writes the local diagnostics output channel.
`pi-agent.git.commitMessageModel`	`""`	Model for commit-message drafts; empty uses the standard PI model.

Settings read but not applied in 3.0.0

PiLot Studio reads these values into its provider configuration, but 3.0.0 never applies them to a session. They look supported in VS Code settings, so changing them has no effect in the sidebar.

Setting	Default	Intended purpose
`pi-agent.defaultModel`	`"anthropic/claude-sonnet-4-5"`	Intended default model for new sessions. Use the model picker instead; PI's own default is authoritative.
`pi-agent.defaultProvider`	`"anthropic"`	Intended default provider.
`pi-agent.maxTokens`	`8192`	Intended response-token cap. Configure the model/provider instead.

Settings declared but not read in 3.0.0

The extension manifest also declares the settings below. PiLot Studio 3.0.0 accepts them in VS Code settings, but the runtime never reads them, so changing them has no effect in the sidebar. They are listed here so you do not spend time tuning a value that is not applied.

Setting	Default	Intended purpose
`pi-agent.autoCompact`	`true`	Intended automatic compaction toggle. The live state comes from the PI session; use the context indicator or `/compact`.
`pi-agent.autoRetry`	`true`	Intended transient-error retry toggle.
`pi-agent.restoreLastSession`	`true`	Intended automatic resume. Open the session from History instead.
`pi-agent.messageHistory.enabled`	`true`	Intended prompt-history recall.
`pi-agent.autoExpandSmallEdits`	`true`	Intended automatic expansion of small edit blocks.
`pi-agent.autoExpandEditLineThreshold`	`15`	Intended line threshold for the above.
`pi-agent.context.includeEditor`	`true`	Intended active-editor context. Auto Context currently adds project metadata only.
`pi-agent.context.includeSelection`	`true`	Intended selected-text context. Use an `@` mention or the editor command instead.
`pi-agent.context.includeDiagnostics`	`true`	Intended diagnostics context.
`pi-agent.context.includeGit`	`false`	Intended Git branch/status context.
`pi-agent.fontSize`	`null`	Intended panel font size.
`pi-agent.fontFamily`	`null`	Intended panel font family.
`pi-agent.fontWeight`	`null`	Intended panel font weight.
`pi-agent.fontStyle`	`null`	Intended panel font style.

This distinction reflects the 3.0.0 source. If a setting starts working in a later release, this page should be updated with that release.

The Preferences tab

Open Preferences with the gear icon or press 9.

Agent Behavior

Auto Context — include the project preamble (root, package name, version) with each prompt.
Light Mode (local LLMs) — reduced runtime; disables discovery and Auto Context, and restricts the default tool set.
Cache Warming — PI's Streaming, Idle, or Off cache-warming mode. Applies to new sessions and updates the live session.
Cache Miss Notices — show PI's cache-miss notices in replies.

MCP & Codemode

Auto-enable Codemode — activate codemode when a codemode-exposed server connects.
Enable Codemode by default — add +codemode to the global defaultTools.
Codemode mode — on or only.
Inline tool budget — tokens available for inline tool declarations.

Each value shows a Project, Global, or Default badge. Project values from a trusted .pi/settings.json or .pi/mcp.json win over the global file. Saving in the panel always writes the global file; the note below the setting tells you when a project override will still apply.

Thinking Level

The same levels as the header: off, minimal, low, medium, high, xhigh, max. The control is clamped to the selected model's supported levels.

Commit Messages

Choose the model used by Generate Commit Message. Leave it on the standard PI model to reuse the chat model, or pin a cheaper model.

Configuration Files

Buttons open PI's files in editor tabs, creating them when missing:

Button	File	Purpose
Open settings.json	`<agentDir>/settings.json`	PI settings, including codemode.
Open auth.json	`<agentDir>/auth.json`	Provider credentials.
Open models.json	`<agentDir>/models.json`	Custom providers and models.
Open mcp.json	`<agentDir>/mcp.json`	Global MCP servers.
Open SYSTEM.md	`<agentDir>/SYSTEM.md`	Replaces PI's default system prompt.
Open APPEND_SYSTEM.md	`<agentDir>/APPEND_SYSTEM.md`	Appends to the system prompt.

SYSTEM.md and APPEND_SYSTEM.md apply to new sessions. If pi-agent.systemPrompt or pi-agent.appendSystemPrompts is set, the panel warns that the files are overridden until those settings are cleared.

Keyboard Shortcuts

A reference list for the main shortcuts. See Commands and keyboard shortcuts for the full set.

About

The installed PiLot Studio version, the PI SDK package, and links to the PI docs and the GitHub repository.

Configuration precedence

Runtime resources accumulate rather than replacing one another:

PI's built-in defaults.
Global PI files under <agentDir>.
Project files under <workspace>/.pi/ — only when the workspace is trusted.
Explicit CLI-style paths from pi-agent.extra* settings.
Session-level choices made in the UI (model, thinking level, tools, codemode).

For codemode values, a project value overrides the matching global value; omitted project keys keep the global value. The Preferences panel labels the effective source.

A project is only asked about trust when it actually contains project-local .pi settings, MCP servers, packages, or extensions. A plain repository loads without a prompt.

Where to edit what

You want to change…	Edit…
Provider keys or OAuth	Providers tab or `auth.json`
Custom provider/model list	Providers tab or `models.json`
MCP servers	MCP tab or `mcp.json`
Codemode behavior	Preferences → MCP & Codemode or `settings.json`
System prompt	Preferences → Configuration Files or `pi-agent.systemPrompt`
Tools	Capabilities tab or `pi-agent.toolPreset` / `customTools`
Packages and skills	Packages and Skills tabs
Session storage	`pi-agent.agentDir` / `pi-agent.sessionDir`

Changing a setting

Open VS Code Settings and search for pi-agent, or open the Preferences tab.
Change the value.
If the change affects resource discovery or Light Mode, PiLot Studio rebuilds the current session while preserving the transcript.
If the change affects the agent directory, reload the window.

If a setting appears to do nothing, check the two not-applied lists above before assuming a bug. The Troubleshooting page covers the runtime settings that can prevent a session from starting.