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

# Settings

> Where Orchestra's settings live, which one wins when they disagree, and every key there is

Orchestra reads settings the way Claude Code does: a file for you, a file
checked into the repository, and a file in the repository that is yours alone.
Like Codex, any setting can also be set for one run on the command line.

| Where | Scope |
| - | - |
| `~/.orchestra/settings.json` | You, in every repository on this machine |
| `.orchestra/settings.json` | Everyone working in this repository. Check it in |
| `.orchestra/settings.local.json` | You, in this repository only. Add it to `.gitignore` |

The repository files are found at the root of the git repository you run
`orchestra` in, from any folder inside it. Outside a repository, they are read
from the current folder.

## Which one wins

When the same key is set in more than one place, the first of these wins:

1. A flag: `orchestra -c diffs.maxLines=80`
2. The environment: `ORCHESTRA_DIFFS_MAX_LINES=80`
3. `.orchestra/settings.local.json`
4. `.orchestra/settings.json`
5. `~/.orchestra/settings.json`
6. The default

Each key is decided on its own, so a project file can set one key and your
own file another.

**Flags.** `-c key=value` (or `--config key=value`) goes anywhere on the
command line before a `--`, and can be given more than once. The value is
read as JSON when it is valid JSON, and as plain text when it is not, so
`-c diffs.show=false` is the boolean and `-c marks=plain` is the text.

**The environment.** Every key has a variable: `ORCHESTRA_`, then the key in
capitals with each dot and each new word marked by an underscore.
`diffs.maxLines` is `ORCHESTRA_DIFFS_MAX_LINES`, and `marks` is
`ORCHESTRA_MARKS`. Values are read as flags' are. An empty variable counts as
unset.

## The keys

```json theme={null}
{
  "diffs": {
    "show": true,
    "maxLines": 40
  },
  "marks": "icons"
}
```

| Key | Default | What it does |
| - | - | - |
| `diffs.show` | `true` | An edit shows the lines it removed and added, under the edit, without a keypress. `false` shows only the edit's summary line (`⎿ Edit texture.py +12 −3`) until you press `ctrl+o` |
| `diffs.maxLines` | `40` | Rows of diff an edit shows before the rest waits for `ctrl+o`. Under the cut, a line says how many lines are left and that `ctrl+o` shows them. A whole number from 1 up |
| `marks` | guessed | How each agent's mark is drawn: `icons` (its logo), `glyphs` (a character) or `plain` (the name alone). When unset, the terminal client shows logos where the Orchestra Symbols font is installed and characters where it is not. See [Agent logos](https://docs.orchestrahq.ai/terminal-client.md#agent-logos) |

Why 40 rows: in a sample of 1,116 real Claude Code edits, 40 rows shows 88% of
them whole (the median edit is 11 rows), and 40 rows still fits on one screen
of a 50-row terminal with the input below it. A new file written whole is
usually longer than that, and is cut; `ctrl+o` shows the rest. Once you press
`ctrl+o`, an edit shows up to 400 rows, and the web app's Changes view has the
whole diff.

## Mistakes in a settings file

Settings files are edited by hand, so a mistake never stops Orchestra:

* **An unknown key** is ignored, with a warning that names the key and the
  file, and the closest key when there is one: `unknown setting
  diffs.maxLine in ~/.orchestra/settings.json, ignored (did you mean
  diffs.maxLines?)`.
* **A value a key does not take** (`"maxLines": "lots"`) is ignored with a
  warning, and the key's next place in the list above decides it.
* **A file that is not valid JSON** is ignored whole, with a warning naming
  the file and the parse error. The other files and the defaults still apply.

The terminal client shows the warning when it opens, and `orchestra doctor`
lists every one.

## Which files were read

`orchestra doctor` ends with the files it read, highest first, and where each
key's value came from:

```text theme={null}
✓ settings: 1 of 3 file(s) read

Settings, highest precedence first:
    flags (-c key=value), then the environment (ORCHESTRA_...)
    local    /work/app/.orchestra/settings.local.json  (not present)
    project  /work/app/.orchestra/settings.json  (read)
    user     ~/.orchestra/settings.json  (not present)
    diffs.show     = true  (default)
    diffs.maxLines = 80  (project: /work/app/.orchestra/settings.json)
    marks          = "plain"  (environment: ORCHESTRA_MARKS)
```

## Nothing secret

A settings file is the thing you paste into an issue, so nothing secret goes
in one. `orchestra login` keeps credentials in `~/.orchestra/credentials.json`,
and settings have no key for one. A key that looks like a credential is
ignored like any unknown key, and its warning says where credentials go,
without repeating the value.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.