Configuration reference

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

{
  "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:

{
  "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.