# Configuration guide
Parent: [source guide](../AGENTS.md).
Effective settings and storage paths; provider credentials belong to `../auth/`.
## Where to look
| Effective settings data/defaults | `../config.rs`; runtime auth/selection: `../auth/runtime.rs` |
| Home/project paths and scoped JSON | `paths.rs`, `settings_storage.rs` |
| Private settings modules/crate-private reexports | `settings.rs` |
| Models/defaults/validation/wire shape | `settings/{core,agent,providers,services,tools,psm,validation,wire}.rs` |
| Unknown-field-preserving writes and editor batches | `settings/{mutations,persistence,json,editor}.rs` |
| MCP definitions and approvals | `settings/mcp.rs` |
| Hooks/custom endpoints/release-note seen state | `hooks.rs`, `custom_provider_config.rs`, `release_notes.rs` |
| Credential readiness/refresh | `../auth/readiness.rs`, `../auth/codex_oauth.rs` |
| Checked-in schema | `../../state/settings.schema.json` |
## Local contracts
- Settings implementations stay private behind `settings.rs`. Keep checked-in schema aligned with `schemars::schema_for!(Settings)` in `settings/persistence.rs`.
- Import provider identity from `../provider_ids.rs` and credential data from `../credentials.rs`. Never import auth or sessions; callers prepare the protected session root after `McPaths::ensure_runtime_dirs`.
- Tool-name validation uses only `crate::tools::names::canonical_disabled_key`, not tool runtime construction.
- `settings.json` is non-secret. Readiness inspection must not unexpectedly refresh credentials. Mutation helpers preserve unknown JSON fields rather than reserialize typed settings over files.
- `/settings` patches allowed changed paths into latest scoped JSON under locks, validating complete merged result. Image provider/model edits save together. Global editing excludes project overrides; project editing includes inherited values.
- `agent.side.provider` and `agent.side.model` are both set or both unset and saved together. Unset inherits at side creation, not each turn; edits require restart and side reset does not reload settings.
- `sessions.psm` defaults disabled with threshold 20 (1 through 1000). Provider/model must both be set or omitted; omitted selection/reasoning inherits the active conversation. PSM settings never alter compaction policy.
- All providers share `agent.compaction.auto`, active-model inheritance, context reserve and prompt-border policy. Claude subscription only adds model-specific input ceilings from `../providers.rs`; no separate compaction settings or required alternative model. Contract: `../../docs/features/sessions-context-cache.md`.
- Model availability defaults off and uses scoped `providers.catalog.enabled` drafts; preserve explicit empty project lists, unknown catalog fields and enabled IDs missing from current catalog. Legacy `providers.catalog.disabled` is ignored, not migrated; startup selection and CLI `--model` remain independent.
- `capabilities.tools.code_mode.disabled` is independent of direct exclusions. Nested Code Mode picker reuses tool modal with separate target; preserve scope and explicit empty project overrides.
- `agent.fast`, `interface.appearance` and `interface.tui.panel_layout` are global-only. Panel layout has no Settings controls; save only open order/pin flags without discarding nested unknowns. Other `interface.tui` Appearance edits may be project-scoped; consult `settings/persistence.rs`.
- `/fast` and `/ultrafast` share global `agent.fast.{enabled,ultrafast}` and one persistence worker. Enable selects one mode; off clears both. Ultrafast requires catalog-advertised Codex `ultrafast`, never model-name inference or automatic Fast fallback.
- Load MCP definitions from root `.mcp.json` then exact-cwd `.mcp.json`; same-name project entries replace whole servers. Parse all structural fields; expand enabled entries' environment variables/defaults once before runtime validation. Disabled missing variables cannot block loading, structural errors can. Do not migrate old settings definitions automatically.
- MCP defaults disabled. Global `capabilities.mcp_approvals[canonical_source_path][name]` binds approval to a versioned HMAC of the normalized unexpanded definition; `false` revokes. Project settings/definition `enabled` cannot approve. Recheck displayed identity under the settings lock before saving; expand the same validated snapshot for runtime. Keep the private `mcp-approval.key` separate from settings. Changes apply next launch; ambient environment and executable contents are not pinned.
- Auth owns coordinated refresh; distinguish built-in credentials, custom environment references and explicit no-auth readiness. Fresh login cannot inherit another account's refresh token. Local login cancellation takes commit's in-process auth lock before setting flag.
- Long-lived preparation rereads Anthropic credentials after logout; environment-backed credentials stay process-owned.