Configuration Scopes

Overview

Qoder CLI CN's configuration is divided into three scopes: personal, project, and local. Understanding what each is best suited for helps you put settings in the right place — neither wrongly imposing personal preferences on the team, nor scattering team conventions across individual machines. The three scopes correspond to three different files:

Scope	File	Best for	Committed with the project
Personal	`~/.qoder-cn/settings.json`	Personal preferences across all projects, such as theme, UI, personal default model	No
Project	`<project>/.qoder/settings.json`	Team-shared project conventions, such as permission rules and project-level model selection	Yes
Local	`<project>/.qoder/settings.local.json`	Project-private settings on the current machine, such as local service addresses and temporary personal overrides	No

For how settings merge layer by layer and the override order, see Settings Files and Precedence.

Personal configuration

Personal configuration lives at ~/.qoder-cn/settings.json under the user config directory and applies to every project you open. It is best for personal preferences unrelated to any specific project:

UI preferences such as theme, status line, and shortcuts.
Your personal default model and reasoning effort.
Personal-level switches such as auto-update.

Personal configuration belongs to you alone and is not distributed to the team with the project repository.

Project configuration

Project configuration lives at <project>/.qoder/settings.json in the project root, applies only to that project, and is suitable for committing to version control to share with the team. It is best for conventions the team wants to unify:

Permission rules and directory trust policies.
A project-wide model choice or parameters.
Project-level extension configuration (MCP, Hooks, etc.).

Once these settings are committed to the repository, team members using Qoder CLI CN in the project automatically get the same conventions.

Local configuration

Local configuration lives at <project>/.qoder/settings.local.json in the project root, and applies only to that project and only on the current machine. It is best for private settings you neither want to commit nor want to affect others:

Local service addresses and personal test data.
Temporary personal overrides of the project configuration.

Local configuration should not be committed to version control. You should usually add .qoder/settings.local.json to .gitignore.

The .qoder directory structure

Beyond settings files, the .qoder/ directory in the project root also holds various local data and extensions used by Qoder CLI CN at runtime. Common contents include:

<project>/.qoder/
├── settings.json          # Project-level settings (committable)
├── settings.local.json    # Local project settings (do not commit)
├── rules/                 # Project-level rule files (*.md)
├── skills/                # Project-level Skills
├── worktrees/             # Isolated worktrees created by --worktree
└── scheduled_tasks.json   # Scheduled task definitions

Where:

Rule files under rules/, split by topic — see Memory.
Project-level Skills under skills/ — see Skills.
Isolated checkouts created by --worktree under worktrees/ — see Running Tasks and Parallel Tasks.
scheduled_tasks.json stores scheduled tasks — see Scheduled Tasks.

User-level data (such as settings.json, authentication state, and plugins) lives under the user config directory, ~/.qoder-cn by default.

The user config directory location can be customized with the QODERCN_CONFIG_DIR environment variable. The project-level .qoder directory always sits in the project root.

How to choose

When placing a setting, think in this order:

Is this a personal preference you want across all projects? → Personal configuration.
Is this a project convention the team should unify on? → Project configuration, committed to the repository.
Is this a project setting only for this machine that shouldn't affect others? → Local configuration, added to .gitignore.

When the same setting appears in multiple scopes, it is merged and overridden in precedence order. For the detailed rules, see Settings Files and Precedence.

​Overview

​Personal configuration

​Project configuration

​Local configuration