> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration Scope

<div id="overview">
  # Overview
</div>

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.

<div id="personal">
  # Personal Configuration
</div>

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.

<div id="project">
  # Project Configuration
</div>

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.

<div id="local">
  # Local Configuration
</div>

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`.

<div id="directory-structure">
  # .qoder Directory Structure
</div>

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:

```text theme={null}
<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](/en/cli/04-extending-qoder-cli/memory).
* Project-level Skills under `skills/`, see [Skills](/en/cli/04-extending-qoder-cli/Skills).
* Isolated checkouts created by `--worktree` under `worktrees/`, see [Using the CLI](/en/cli/03-using-qoder-cli/01-starting-a-task/using-cli) and [Handling Multiple Tasks in Parallel](/en/cli/03-using-qoder-cli/03-multitasking-and-collaboration/parallel).
* Scheduled tasks saved in `scheduled_tasks.json`, see [Scheduled Execution Task](/en/cli/03-using-qoder-cli/02-task-automation/scheduled).

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.

<div id="choose">
  # How to Choose
</div>

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.