Configuration Files and Application Order

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:

Level	Path	Description
User Level	`~/.qoder/settings.json`	Personal preferences that apply to all projects for the current user.
Project-Level	`<project>/.qoder/settings.json`	Shared project configuration, committed to the repository and shared among team members.
Local Level	`<project>/.qoder/settings.local.json`	Personal overrides within a project, typically not committed to the repository.

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:

Built-in defaults (Schema defaults)
User Level settings (~/.qoder/settings.json)
Project-Level settings (<project>/.qoder/settings.json)
Local Level settings (<project>/.qoder/settings.local.json)
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
  },
  "model": {
    "name": "auto",
    "maxSessionTurns": -1
  },
  "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 Item	Type	Default	Description
`outputStyle`	string	None	Name of the active Output Style (requires restart). Compatible with the `general.outputStyle` syntax, with top-level taking precedence. See Output Style.
`language`	string	None	Preferred language for AI responses (requires restart).
`agent`	string	None	Name of the Agent used for the main thread (requires restart).

ui (UI)

Configuration Item	Type	Default	Description
`ui.theme`	string	None	Color Theme name.
`ui.autoThemeSwitching`	boolean	`true`	Automatically switch between Light and Dark Themes based on the terminal background color.
`ui.customThemes`	object	`{}`	Custom theme definitions.
`ui.hideBanner`	boolean	`false`	Hide the Startup banner.
`ui.showLineNumbers`	boolean	`true`	Display line numbers in conversations.
`ui.loadingPhrases`	enum	`off`	Content to display during loading: `tips` / `witty` / `all` / `off`.
`ui.accessibility.screenReader`	boolean	`false`	Screen Reader Mode, outputs plain text (requires restart).

For more UI and Shortcuts configurations, see UI and Shortcuts.

model (Model)

Configuration Item	Type	Default	Description
`model.name`	string	None	Model used for conversations.
`model.reasoningEffort`	enum	None	Reasoning Effort Level: `low` / `medium` / `high`, etc.
`model.maxSessionTurns`	number	`-1`	Maximum number of conversation turns to retain, `-1` for unlimited.
`modelConfigs.customModels`	array	`[]`	Custom BYOK models (requires restart). See Custom Model.

tools (Tools)

Configuration Item	Type	Default	Description
`tools.sandbox`	string/boolean/object	None	Sandbox execution environment (requires restart). See Sandbox.
`tools.sandboxAllowedPaths`	string[]	`[]`	Additional paths accessible by the sandbox (requires restart).
`tools.sandboxNetworkAccess`	boolean	`false`	Whether the sandbox is allowed to access the network (requires restart).
`tools.useRipgrep`	boolean	`true`	Use ripgrep for content search.
`tools.shell.inactivityTimeout`	number	`300`	Timeout in seconds for shell commands with no output.
`tools.core`	string[]	None	Allowlist for built-in tools; only listed tools are permitted (requires restart).
`tools.exclude`	string[]	None	Tool names to exclude from discovery (requires restart).

security (Security)

Configuration Item	Type	Default	Description
`security.folderTrust.enabled`	boolean	`true`	Whether to enable Folder Trust (requires restart).
`security.toolSandboxing`	boolean	`false`	Tool-Level Sandbox isolation (requires restart).
`security.disableYoloMode`	boolean	`false`	Disable the `bypass_permissions` (YOLO) permission mode (requires restart).
`security.blockGitExtensions`	boolean	`false`	Block installing and loading extensions from Git (requires restart).
`security.environmentVariableRedaction.enabled`	boolean	`false`	Mask environment variables that may contain keys (requires restart).

mcp (MCP Servers)

Configuration Item	Type	Default	Description
`mcpServers`	object	`{}`	MCP server configurations (requires restart). See MCP.
`mcp.allowed`	string[]	None	Allowlist of MCP servers (requires restart).
`mcp.excluded`	string[]	None	Exclude list of MCP servers (requires restart).

statusLine (Status Bar)

Configuration Item	Type	Default	Description
`statusLine.type`	string	`command`	Status Bar type; currently only `command` is supported.
`statusLine.command`	string	`""`	Shell command to generate the Status Bar, receiving session data JSON via stdin.
`statusLine.padding`	number	`0`	Number of horizontal padding characters for the 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

View all configuration items and environment variables: Configuration Item Reference.
Configure custom models: Custom Model.
Customize UI and shortcuts: UI and Shortcuts.
Configure sandbox isolation: Sandbox.
Troubleshoot configuration issues: Configuration Troubleshooting.

​Configuration File Locations

​Merge Precedence

​Merge Behavior

​Impact of Folder Trust

​File Format

​Common Configuration Items

​Top-Level Configuration Items

​ui (UI)

​model (Model)

​tools (Tools)

​security (Security)

​mcp (MCP Servers)

​statusLine (Status Bar)

​Editing Configurations

​Next Steps