Configuration Scope

Overview

Qoder CLI configuration is divided into three scopes: personal, project, and local. Understanding what each scope is best suited for helps you place settings in the right location—ensuring you don’t inadvertently impose personal preferences on the team or scatter team conventions across individual machines.

The three scopes correspond to three different files:

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

For how configuration items are merged layer by layer and the order of precedence, see Configuration Files and Precedence.

Personal Configuration

Personal configuration is stored in ~/.qoder/settings.json under the User Configuration Directory and applies to every project you open. It is ideal for personal preferences that are unrelated to specific projects:

• UI preferences such as interface themes, status bar, and keyboard shortcuts.
• Personal default models and reasoning strength.
• User-level toggles such as auto-upgrade.

Personal configuration belongs solely to you and is not distributed to the team via the project repository.

Project Configuration

Project configuration is stored in <项目>/.qoder/settings.json at the project root directory. It applies only to this project and is suitable for committing to the version control repository to share with the team. It is ideal for conventions the team wishes to unify:

• Permission rules and Directory Trust Policies.
• Unified model selection or parameters for the project.
• Project-level extension configurations (MCP, Hooks, etc.).

Once these settings are committed to the repository, team members will automatically apply the same conventions when using Qoder CLI in this project.

Local Configuration

Local configuration is stored in <项目>/.qoder/settings.local.json at the project root directory. It applies only to this project and only on the current machine. It is ideal for private settings that you do not want to commit or affect others:

• Local service addresses and personal test data.
• Personal temporary overrides for project configuration.

Local configuration should not be committed to the version control repository. Typically, .qoder/settings.local.json should be added to .gitignore.

.qoder Directory Structure

In addition to configuration files, the .qoder/ directory at the project root directory also hosts various local data and extensions for Qoder CLI runtime. Common contents include:

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

Among them:

• Rule files split by topic under rules/, see Memory.
• Project-level Skills under skills/, see Skills.
• Isolated checkouts created by --worktree under worktrees/, see Using the CLI and Handling Multiple Tasks in Parallel.
• Scheduled tasks saved in scheduled_tasks.json, see Scheduled Execution Task.

User-level data (such as settings.json, authentication status, and plugins) is stored in the User Configuration Directory, which defaults to ~/.qoder.

The location of the User Configuration Directory can be customized via the QODER_CONFIG_DIR Environment Variable. The project-level .qoder directory is always located at the project root directory.

How to Choose

When placing configurations, consider the following sequence:

1. Is this a personal preference you want across all projects? → Put it in personal configuration.
2. Is this a project convention the team should unify? → Put it in project configuration and commit it to the repository.
3. Is this a project setting only on my machine that you don’t want to affect others? → Put it in local configuration and add it to .gitignore.

When the same configuration item appears in multiple scopes, it will be merged and overridden according to the precedence order. For detailed rules, see Configuration Files and Precedence.