Configuration and Settings

Neon Pilot has several configuration stores. Do not treat config.json as the whole settings system: machine config, runtime agent settings, extension settings, provider definitions, credentials, desktop preferences, and browser-local UI state each have different owners.

Neon Pilot no longer has user-selectable profiles. Some storage paths and compatibility APIs still use the legacy word profile; treat those as the single shared runtime scope, not a product concept.

Path roots

Machine config

<config-root>/config.json is machine-local configuration. It is not a layered settings file and there is no active <config-root>/local/config.json overlay.

Current machine config keys:

Example:

{
  "knowledgeBaseRepoUrl": "[email protected]:user/neon-pilot-kb.git",
  "knowledgeBaseBranch": "main",
  "instructionFiles": ["/Users/me/agent/extra-AGENTS.md"],
  "skillDirs": ["/Users/me/agent/skills"]
}

Machine config augments the built-in machine-local defaults. Neon Pilot always checks ~/.config/agents/AGENTS.md as the canonical secondary instruction file and ~/.config/agents/skill plus ~/.config/agents/skills as canonical secondary skill roots. The knowledge base remains the primary durable source; use the machine agent dir for personal files that should stay local to this machine.

Runtime agent settings

The active agent/runtime settings file is:

<state-root>/neon-pilot-runtime/settings.json

This file is materialized from resolved runtime resources and is also where app-level runtime preferences are written. The desktop Settings page writes through APIs that preserve existing settings and mirror writes to the legacy local settings path where needed.

Common runtime settings include:

Do not put arbitrary product feature state here. Product features should own state through their extension storage, daemon/runtime DB tables, or a deliberate extension API.

Extension settings

Extensions have two settings mechanisms:

1. Scalar settings declared in extension.json under contributes.settings. These are exposed through /api/settings, merged with manifest defaults, and persisted as overrides in:

``text <state-root>/settings.json ``

1. Component-backed settings UI declared by an extension as contributes.settingsComponent. The component renders inside the Settings page and should read/write through extension backend actions or stable SDK APIs.

The Settings page has an Extension Settings section for scalar manifest settings. Rich first-party panels, such as Dictation or Knowledge, should live in their owning system extension and use stable extension APIs rather than app-shell special cases.

Models, providers, and credentials

Model/provider configuration is split on purpose:

Provider credentials should be managed through Settings. New provider API-key saves use the shared secrets backend and remove the legacy plaintext auth.json API-key entry. Manual edits to auth.json are possible but discouraged; the runtime still reads legacy API keys and OAuth tokens as compatibility fallbacks. New extension secrets should use contributes.secrets; the active backend is configured by secrets.provider (keychain, file, or env-only). Stored secrets take precedence over declared environment variables; the environment variable is a fallback when no stored secret exists.

Changing secrets.provider migrates indexed persisted secrets between durable backends (keychain and file) before the setting is saved. env-only has no persistence target, so switching to it leaves existing stored secrets in place but inactive until the provider is switched back.

Enabled extensions may contribute modelProfiles that match provider/model refs with simple globs over <provider>/<model>, for example openai-codex/* or */gpt-5.5. These are model compatibility profiles, not user-selectable app profiles. The owning extension implements runtime behavior through normal extension hooks and tools; disabled extensions do not participate, and models do not declare profiles.

If no enabled profile extension matches, Neon Pilot uses the normal default runtime behavior. Explicit per-run allowed tool lists still take precedence.

Knowledge base resolution

The effective knowledge base root resolves in this order:

1. NEON_PILOT_KNOWLEDGE_ROOT
2. Managed knowledge-base mirror at <state-root>/knowledge-base/repo when knowledgeBaseRepoUrl is configured
3. knowledgeRoot from machine config
4. ~/Documents/neon-pilot

Knowledge UI and sync behavior live in the Knowledge system extension. Machine config only stores the machine-level root/sync inputs.

Agent file discovery

Global agent files use a primary/secondary model:

Runtime discovery also includes explicitly configured instruction files, explicitly configured skill dirs, project instruction files found from the working directory, local overlays, extension-contributed skills, and compatibility skill roots such as ~/.claude/skills and ~/.codex/skills.

Runtime prompt layers

The runtime may materialize both generated prompt defaults and discovered instruction files. They are different layers:

Treat APPEND_SYSTEM.md as generated runtime context, not as a repo instruction file. Treat AGENTS.md files as editable instruction sources with explicit scope. Model profiles that need smaller prompts, such as local/constrained model extensions, may replace instruction files or skills with file pointers while keeping generated global system defaults embedded.

Desktop, daemon, and local UI state

Not every Settings-page control writes to the same JSON file:

Rule of thumb

Use machine config for machine-wide roots and discovery inputs. Use runtime settings for active agent defaults. Use extension settings/storage for product features. If an extension needs a new kind of configuration, add a reusable extension API instead of hiding feature-specific config in core.

Edit this page on GitHub →