# Settings

> Set the default reviewer, model, effort and dashboard switches globally or per workspace, and see which value wins.

Settings decide what a review uses when you do not name a reviewer, model or effort. You can keep them in two files, or change them on the dashboard’s [Settings](https://cross-review.tlelabs.com/docs/guides/dashboard/#settings) page, which writes the same files.

## Where settings live

| File                                    | Applies to                                                      |
| --------------------------------------- | --------------------------------------------------------------- |
| `~/.cross-review/config.json`           | Every workspace (global)                                        |
| `<workspace>/.cross-review/config.json` | One workspace; git ignores it with the rest of `.cross-review/` |

Both files are optional. A missing file means no settings at that level.

## Keys

| Key              | Type                           | Where                        | Default                  | What it does                                                                                                                                                  |
| ---------------- | ------------------------------ | ---------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `reviewer`       | name of a reviewer             | global, workspace            | `codex`                  | Which reviewer CLI runs the review. Codex is the only one today.                                                                                              |
| `model`          | model name                     | global, workspace, per skill | the reviewer’s own model | The model the reviewer uses. Model names contain no spaces.                                                                                                   |
| `effort`         | lowercase word, such as `high` | global, workspace, per skill | `high`                   | How much effort the reviewer spends. Use a level the model supports.                                                                                          |
| `open_dashboard` | true or false                  | global, workspace            | false                    | When on, each new review opens in the dashboard in your browser. See [Dashboard](https://cross-review.tlelabs.com/docs/guides/dashboard/).                    |
| `open_plans`     | true or false                  | global, workspace            | false                    | When on, each plan that `loop-plan` finishes opens on its Plan tab. See [Plans](https://cross-review.tlelabs.com/docs/guides/plans/).                         |
| `track_plans`    | true or false                  | global, workspace            | false                    | When on, plans can be committed to git. See [Plans](https://cross-review.tlelabs.com/docs/guides/plans/).                                                     |
| `check_updates`  | true or false                  | global only                  | false                    | When on, the dashboard checks npm for a newer version at start. See [Dashboard](https://cross-review.tlelabs.com/docs/guides/dashboard/#updates).             |
| `skills`         | object                         | global, workspace            | none                     | Model and effort for one skill. Keys are the skill names `review-plan`, `review-impl`, `review-think` and `review-pr`; each takes `model`, `effort`, or both. |

Example workspace file that uses a lighter effort for `review-impl` only:

```json
{
  "open_dashboard": true,
  "skills": {
    "review-impl": { "effort": "medium" }
  }
}
```

Unknown keys and wrong values are errors. See [Troubleshooting](https://cross-review.tlelabs.com/docs/guides/troubleshooting/#settings-file-is-invalid) for what that looks like.

## Which value wins

Each key is resolved on its own. The first match wins:

1. The model or effort you name when you ask for a review, such as “use gpt-5-codex for this review”.
2. The workspace’s value for this skill (`skills` in the workspace file).
3. The workspace’s value.
4. The global value for this skill.
5. The global value.
6. The default.

The plan settings `open_dashboard`, `open_plans` and `track_plans` do not use the review order. A workspace value wins over the global one, and when neither sets it, the default is false.

> **Tip:**
>
> Name a model or effort only when you want to override the settings for one review. Otherwise the skill uses the resolved value above.

## Models and effort

- The model list on the dashboard comes from the reviewer CLI. With Codex it is `codex debug models`.
- The dashboard saves the last list in `~/.cross-review/models.json`, so the list is available at once. **refresh list** asks the reviewer again. A failed refresh keeps the saved list.
- The effort choices depend on the model. Only the levels the model supports are offered.

## Edit the files by hand

The files are plain JSON. Use the dashboard or edit them in a text editor, and keep to the keys above.

**Dashboard**

Open **Settings**, choose **Global** or a workspace, and change a field. The change is saved immediately. The page shows the value each skill gets and where it comes from.

**Text editor**

Edit `~/.cross-review/config.json` or `<workspace>/.cross-review/config.json`. Save the file. The next review reads it. A file that is not valid JSON, or has a wrong key or value, stops `begin` with `CONFIG_INVALID` before any session is created.

When you change the file on the dashboard, a broken file for that level is replaced by the saved one.