Configuration Files and Application Order - Qoder
Skip to main content
Configuration and Security

Configuration Files and Application Order

Three-tier configuration files, merge priority, and common configuration items in Qoder CLI

The behavior of Qoder CLI can be customized through JSON configuration files (settings.json). The configuration uses a hierarchical design: the same setting can be defined at different levels and is ultimately merged into an effective value based on a fixed precedence. Understanding this hierarchy and merging rules is fundamental to managing personal preferences and team conventions. This page covers the locations of configuration files, merge precedence, and common configuration items. For a complete list of configuration items and environment variables, see Configuration Item Reference.

Configuration File Locations

Qoder CLI reads configuration files from three levels:
The default configuration directory is ~/.qoder, which can be modified via the environment variable QODER_CONFIG_DIR. For the complete structure of the .qoder/ directory, see .qoder directory.

Merge Precedence

When the same configuration item appears at multiple levels, Qoder CLI merges them in the following order of precedence from lowest to highest, where higher precedence overrides lower precedence:
  1. Built-in defaults (Schema defaults)
  2. User Level settings (~/.qoder/settings.json)
  3. Project-Level settings (<project>/.qoder/settings.json)
  4. Local Level settings (<project>/.qoder/settings.local.json)
  5. Configurations specified via command-line --settings (Highest precedence)
In other words: Local Level overrides Project-Level, Project-Level overrides User Level, and configurations explicitly passed via the command line take precedence over all files.

Merge Behavior

Configurations use deep merge rather than wholesale replacement:
  • Objects: Recursively merged field by field; only present fields are overridden, while the rest retain lower-precedence values.
  • Single values (strings, numbers, booleans): Directly overridden by higher precedence.
  • Arrays: Some configuration items (such as disable lists and exclude lists) use "union merge" to combine and deduplicate values across levels; other arrays are overridden by default.
Therefore, at the Project-Level, you only need to specify the fields you want to override, without copying the entire user configuration.

Impact of Folder Trust

For security reasons, Project-Level and Local Level configurations are only applied when the current working directory is trusted. If the working directory is not trusted, Qoder CLI only loads User Level configurations and ignores settings.json and settings.local.json within the project. Folder Trust is controlled by security.folderTrust.enabled (enabled by default).

File Format

Configuration files are in JSON format (supporting // comments, see below). The top level is an object, and most configuration items are nested by group, with a few items located directly at the top level (such as outputStyle, language, and agent). For example: 
{
  "outputStyle": "concise",
  "ui": {
    "theme": "Tokyo Night",
    "autoThemeSwitching": true,
    "maxTurns": 2000
  },
  "model": {
    "name": "auto"
  },
  "tools": {
    "useRipgrep": true
  }
}
Notes:
  • Configuration files can contain comments (ignored during parsing), making it easy to add explanations for team conventions.
  • Environment variables can be referenced in values and will be resolved and replaced at runtime.
  • Modifying certain configuration items requires restarting Qoder CLI to take effect (see notes below).

Common Configuration Items

The following lists the most frequently adjusted configuration items, organized by group. Items marked with "requires restart" require a restart to take effect after modification.

Top-Level Configuration Items

The following configuration items are written directly at the top level of the configuration file and do not belong to any group:
Configuration ItemTypeDefaultDescription
outputStylestringNoneName of the active Output Style (requires restart). Compatible with the general.outputStyle syntax, with top-level taking precedence. See Output Style.
languagestringNonePreferred language for AI responses (requires restart).
agentstringNoneName of the Agent used for the main thread (requires restart).

ui (UI)

Configuration ItemTypeDefaultDescription
ui.languageenumenInteractive interface language: auto / zh-CN / en. Takes effect immediately; see UI and Shortcuts.
ui.themestringNoneColor Theme name.
ui.autoThemeSwitchingbooleantrueAutomatically switch between Light and Dark Themes based on the terminal background color.
ui.maxTurnsenum1000Maximum model/tool-loop turns for one submitted prompt in the interactive TUI: 1000 / 2000 / 3000 / unlimited. Does not affect -p/--print.
ui.customThemesobject{}Custom theme definitions.
ui.hideBannerbooleanfalseHide the Startup banner.
ui.showLineNumbersbooleantrueDisplay line numbers in conversations.
ui.loadingPhrasesenumoffContent to display during loading: tips / witty / all / off.
ui.accessibility.screenReaderbooleanfalseScreen Reader Mode, outputs plain text (requires restart).
For more UI and Shortcuts configurations, see UI and Shortcuts.

model (Model)

Configuration ItemTypeDefaultDescription
model.namestringNoneModel used for conversations.
model.reasoningEffortenumNoneReasoning Effort Level: low / medium / high, etc.

tools (Tools)

Configuration ItemTypeDefaultDescription
tools.useRipgrepbooleantrueUse ripgrep for content search.
tools.shell.inactivityTimeoutnumber300Timeout in seconds for shell commands with no output.
tools.corestring[]NoneAllowlist for built-in tools; only listed tools are permitted (requires restart).
tools.excludestring[]NoneTool names to exclude from discovery (requires restart).

security (Security)

Configuration ItemTypeDefaultDescription
security.folderTrust.enabledbooleantrueWhether to enable Folder Trust (requires restart).
security.disableYoloModebooleanfalseDisable the bypass_permissions (YOLO) permission mode (requires restart).
security.blockGitExtensionsbooleanfalseBlock installing and loading extensions from Git (requires restart).
security.environmentVariableRedaction.enabledbooleanfalseMask environment variables that may contain keys (requires restart).

mcp (MCP Servers)

Configuration ItemTypeDefaultDescription
mcpServersobject{}MCP server configurations (requires restart). See MCP.
mcp.allowedstring[]NoneAllowlist of MCP servers (requires restart).
mcp.excludedstring[]NoneExclude list of MCP servers (requires restart).

statusLine (Status Bar)

Editing Configurations

There are two ways to modify configurations:
  • In the Interactive interface: Run /settings to open the Settings Panel to directly view and adjust common configuration items.
  • Manually editing files: Open the settings.json for the corresponding level in an editor, and add or modify fields according to the tables above.
After modification, items not marked with "requires restart" usually take effect immediately; items marked with "requires restart" require restarting Qoder CLI.

Next Steps