# Configuration reference

> Every key in a cross-review settings file, where it can appear, its default, how values resolve, and the CONFIG_INVALID error.

Settings are plain JSON files. The dashboard’s Settings page reads and writes them. `begin` reads them when a call leaves out the reviewer, model or effort. Unknown keys are errors.

## Files

| File                                      | Scope                              |
| ----------------------------------------- | ---------------------------------- |
| `~/.cross-review/config.json`             | Global: used by every workspace.   |
| `<working_dir>/.cross-review/config.json` | Workspace: used by one repository. |

When the dashboard saves a file with no settings left, it deletes the file.

## Keys

| Key              | Type                                       | Where it can appear    | Default                    | Meaning                                                                                                                       |
| ---------------- | ------------------------------------------ | ---------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `reviewer`       | `codex`                                    | Top level              | `codex`                    | Reviewer CLI. Only `codex` today.                                                                                             |
| `model`          | Model name: no spaces, 1 to 200 characters | Top level or per skill | The reviewer’s own default | Model the reviewer runs.                                                                                                      |
| `effort`         | A lowercase word, such as `high`           | Top level or per skill | `high`                     | Reasoning effort. It is passed to the reviewer as is.                                                                         |
| `open_dashboard` | true or false                              | Top level              | `false`                    | When true, `begin` opens each new review in the dashboard.                                                                    |
| `track_plans`    | true or false                              | Top level              | `false`                    | When true, plans in `.cross-review/plans/` are kept in git. See [plans](https://cross-review.tlelabs.com/docs/guides/plans/). |
| `open_plans`     | true or false                              | Top level              | `false`                    | When true, a plan that finishes opens in the dashboard’s Plan tab.                                                            |
| `check_updates`  | true or false                              | Global file only       | Off                        | When true, the dashboard checks npm for a newer version. A value in a workspace file is accepted and ignored.                 |
| `skills`         | Object keyed by skill                      | Top level              | None                       | Per-skill `model` and `effort`.                                                                                               |

The skill names allowed under `skills` are `review-plan`, `review-impl`, `review-think` and `review-pr`. Each entry takes only `model` and `effort`.

### Example

A global file that follows reviews in the dashboard and uses a higher effort for implementation reviews:

```json
{
  "reviewer": "codex",
  "effort": "high",
  "open_dashboard": true,
  "skills": {
    "review-impl": { "effort": "high" }
  }
}
```

A workspace file that keeps its plans in git and opens finished plans:

```json
{
  "track_plans": true,
  "open_plans": true
}
```

## Resolution order

Each key resolves on its own, and the first match wins.

For `model` and `effort`:

1. The value passed in the call (the `review_begin` parameter or the `begin` flag).
2. The workspace file, per skill.
3. The workspace file, top level.
4. The global file, per skill.
5. The global file, top level.
6. The default: the reviewer’s own model, and `high` for effort.

For `reviewer`, the per-skill steps (2 and 4) do not apply. For `open_dashboard`, `track_plans` and `open_plans`, the value comes from the workspace file, then the global file, then the default (`false`). A call cannot pass these keys.

The skill’s settings are stored in the session when it starts. Later rounds use the stored values unless the call passes new ones.

## Errors

A broken file stops the call before a session is created. The error code is `CONFIG_INVALID`, and the message names the file and the problem, for example:

- the file is not valid JSON;
- a key is not in the list above, such as an unknown key;
- a value has the wrong type, such as a text value for a true or false key;
- an unknown reviewer name, or an unknown skill under `skills`.

Fix the named file and call again. Nothing is written to the session folder.

> **Note:**
>
> Only the global file is read for `check_updates`. The dashboard’s update check is described in the [dashboard guide](https://cross-review.tlelabs.com/docs/guides/dashboard/).