Positron Settings

When running inside Positron, Posit Assistant is configured through VS Code settings in addition to the shared config file. These settings are accessed via Settings (Cmd+, / Ctrl+,) and use the assistant.* prefix.

Settings Reference

Key	Type	Default	Description
`ai.enabled`	`boolean`	`true`	Positron 2026.07+ only. Positron's main switch for all AI features. When off, Posit Assistant is unavailable regardless of assistant.enabled. To use the assistant, both ai.enabled and assistant.enabled must be on. Not consulted on older Positron versions.
`assistant.enabled`	`boolean`	`true`	Enable Posit Assistant chat and AI features. When disabled, the sidebar icon is hidden and editor panel commands are unavailable. Has no effect when ai.enabled is off (Positron 2026.07+). On older Positron versions (< 2026.07), explicit assistant.enabled overrides the legacy positron.assistant.enable setting.
`positron.assistant.enable`	`boolean`	`false`	Legacy (Positron < 2026.07 only). Enables Posit Assistant on older Positron versions where ai.enabled does not exist. Overridden by explicit assistant.enabled workspace or user settings. Not present on Positron 2026.07+.
`assistant.preferredModel.id`	`string`	`""`	The preferred language model ID to use by default. If specified and available, this model is selected automatically when Posit Assistant starts.
`assistant.preferredModel.provider`	`string`	`""`	The preferred model provider. Used with preferredModel.id to disambiguate when the same model ID is available from multiple providers.
`assistant.preferredModel.thinkingEffort`	`string`	`""`	Default thinking effort level for models that support adaptive thinking (e.g., 'low', 'medium', 'high').
`assistant.preferredModel.webSearch`	`boolean`	`false`	Whether web search is enabled by default.
`assistant.mcpServers`	`object`	`{}`	MCP server configuration. Same format as the mcpServers key in the config file.
`assistant.aiExcludes`	`string[]`	`[]`	Glob patterns for files excluded from AI access. For example, [".env", "secrets/*"] blocks matching files from being read, written, or edited. Patterns without a `/` match filenames in any directory. Admin policies can enforce non-overridable patterns.

📝 ai.enabled is the main switch (Positron 2026.07+)

ai.enabled is a Positron setting (not an assistant.* setting) that gates all of Positron’s AI features. It takes precedence over assistant.enabled: when ai.enabled is off, Posit Assistant is disabled even if assistant.enabled is on (including when an admin policy enforces assistant.enabled to true). When ai.enabled is on (the default), the assistant follows its own assistant.enabled setting.

ai.enabled is available starting in Positron 2026.07. On older versions (< 2026.07), enablement is governed by the positron.assistant.enable setting instead, and ai.enabled is not consulted.

MCP Servers in Positron

MCP servers can be configured either in the VS Code settings (assistant.mcpServers) or in the shared config file (mcpServers key). The format is the same in both locations. See the MCP Servers guide for configuration details.

Custom Base URLs and Headers

Posit Assistant respects custom base URLs and custom HTTP headers configured in Positron’s language model provider settings. These are useful for enterprise proxies, custom API gateways, or local development servers — including gateways like Databricks that require extra tenancy or routing markers on every request.

These are Positron authentication settings (authentication.*), not assistant.* settings — they live in the same namespace as the provider’s credentials and apply to all extensions that use the provider. The base URL can be set through the model provider configuration UI; customHeaders is set directly in settings.json.

The supported settings are:

Provider	Base URL	Custom Headers
Anthropic	`authentication.anthropic.baseUrl`	`authentication.anthropic.customHeaders`
OpenAI	`authentication.openai-api.baseUrl`	`authentication.openai-api.customHeaders`
OpenAI Compatible	`authentication.openai-compatible.baseUrl`	`authentication.openai-compatible.customHeaders`
Microsoft Foundry	`authentication.foundry.baseUrl`	`authentication.foundry.customHeaders`
Snowflake	derived from `authentication.snowflake.credentials`	`authentication.snowflake.customHeaders`

customHeaders is an object mapping header name to value, attached to every model-discovery and chat request for the provider:

{
  "authentication.openai-api.customHeaders": {
    "x-gateway-tenant": "team-42"
  }
}

📝 Ignored header names

The following SDK-managed header names are ignored if set in customHeaders: Accept, anthropic-version, Authorization, Content-Type, x-api-key.

Advanced Settings

These settings cover experimental features and lower-level routing controls. Most users don’t need to change them.

Key	Type	Default	Description
`assistant.modelRouting`	`string`	`"prefer-direct"`	Controls how Posit Assistant accesses language models. See Model Routing below for the available options.
`assistant.enableCopilotSdk`	`boolean`	`false`	Experimental. When enabled, Copilot models can be accessed through the direct Copilot SDK provider and participate in the modelRouting preference. When disabled (default), Copilot is only available through Positron's built-in language model API — Copilot models will not appear when modelRouting is set to direct.
`assistant.experimentalFeatures`	`boolean`	`false`	Enable experimental in-development features, such as additional assistant personas. Behavior may change between releases. Not exposed in the Settings UI — edit settings.json directly.
`assistant.showTips`	`boolean`	`true`	Show helpful tips above the input after assistant turns and on startup. Disabling hides tips immediately without restarting.
`assistant.cacheKeepalive`	`boolean`	`false`	Keep the Anthropic prompt cache warm while idle by sending lightweight pings after each turn. Reduces latency and cost for follow-up messages sent within a few minutes. Claude models only.
`assistant.cacheKeepalivePingCount`	`integer`	`3`	Number of cache-keepalive pings to send after a turn (0–10). Each ping extends cache warmth by about 4.5 minutes. Only applies when assistant.cacheKeepalive is enabled and using a Claude model.

Model Routing

The assistant.modelRouting setting controls how the assistant connects to language models:

Value	Description
`prefer-direct`	(Default) Use direct API access when available, fill in remaining providers from Positron’s language model API.
`direct`	Only use direct API access via configured credentials.
`vscode-lm`	Only use Positron’s built-in language model API.
`prefer-vscode-lm`	Prefer Positron’s language model API, fill in remaining providers from direct access.

💡 When to change model routing

Most users should leave this at the default (prefer-direct).

Relationship to Config File

Positron reads settings from both VS Code settings and the shared config file (~/.posit/assistant/settings.json and project-level .posit/assistant/settings.json). Some settings live in only one place, while others can be set in either:

Positron-only — Model routing, sidebar visibility, and Copilot SDK are VS Code settings with no config-file equivalent.
Config-file-only — Runtime paths, permissions, storage, and logging are shared across all platforms and have no VS Code setting.
Both — Feature settings like tips, cache keepalive, compaction thresholds, and experimental features can be set in either location and are merged together.

How Feature Settings Are Merged

When a feature setting (tips, cache keepalive, compaction, experimental features) exists in both VS Code settings and the config file, Positron resolves them using a 5-tier priority — the first defined value wins:

Positron workspace setting — assistant.<key> set at the workspace level in Positron
Project config file — features.<key> in .posit/assistant/settings.json in your project
Positron user setting — assistant.<key> set at the user level in Positron
Global config file — features.<key> in ~/.posit/assistant/settings.json
Declared default — the built-in default value

This means a project-level config file overrides your Positron user settings, and a Positron workspace setting overrides everything. Settings that aren’t declared in Positron’s Settings UI (like compaction thresholds) are effectively read from the config file only — tiers 2 and 4.

Model preferences like thinking effort and web search are set as defaults in the config file (model.thinkingEffort, model.webSearch) and applied when starting new conversations. During a conversation, these preferences are adjusted via the UI and stored per-conversation — they are not written back to the config file.