Configuration schema
packages/coding-agent/src/config/settings-schema.ts defines every recognized settings key with its type, default, and validation. It evolves with the executable, so read the key namespaces here and the values from your own installation.
Which key namespaces exist?
Section titled “Which key namespaces exist?”| Area | Namespaces |
|---|---|
| Appearance | theme, statusLine, display, tui, terminal, images, media |
| Model and routing | routing, retry, thinkingBudgets, providers, exa |
| Interaction | startup, keybindings, completion, ask, stt, marketplace |
| Context and session | context, contextPromotion, compaction, branchSummary, memories, ttsr, power |
| Editing | edit, read, lsp, bashInterceptor, python |
| Tools | tools, todo, find, grep, astGrep, astEdit, notebook, fetch, browser, web_search, calc, checkpoint, debug, inspect_image, generate_image, renderMermaid, bash, async, mcp |
| Tasks and capabilities | task, tasks, skills, commands |
| Security | secrets, sandbox, xcsh |
| Repository workflows | commit, dev |
A key is namespace.name, as in compaction.thresholdPercent or sandbox.allowRead. Nested groups extend that form, as in todo.reminders.max.
How do I control session sleep prevention?
Section titled “How do I control session sleep prevention?”power.sleepPrevention defaults to idle. Set it to off, idle, display, or system; each
level is cumulative and applies only while an agent session is active. xcsh maps the setting to
IOKit on macOS, login1 and ScreenSaver on Linux, and thread-affine execution state on Windows.
How do I inspect the effective schema-backed values?
Section titled “How do I inspect the effective schema-backed values?”xcsh config list --jsonxcsh config get <KEY>Use xcsh config set <KEY> <VALUE> only for a key present in the installed schema. Reset one key with xcsh config reset <KEY> rather than copying defaults from another release.
Which source defines a setting?
Section titled “Which source defines a setting?”The settings schema and its tests in the matching source release define type, default, and validation. xcsh config list --json reports the value after user, project, environment, and command-line precedence is applied. When the two disagree, the schema describes what is legal and the effective output describes what is active.
Unknown keys and wrong value types are configuration errors, even when a nearby subsystem has a
similarly named option. Consult the generated schema for the installed version, place the key under
its documented namespace, and restart the process after editing. Use /settings to inspect
effective interactive values. When diagnosing precedence, remove the highest-priority override and
relaunch rather than editing several layers at once.