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

# Configure Plannotator

> How Plannotator combines command flags, environment variables, config.json, and browser UI settings.

Plannotator has four settings layers. Use command flags for one run, environment variables for a shell or host integration, `config.json` for persistent runtime behavior, and the Settings panel for review UI preferences.

## Where settings live

The default data directory is `~/.plannotator`. Set `PLANNOTATOR_DATA_DIR` to move Plannotator's config, session records, history, plans, and related state together.

The persistent runtime config is:

```text theme={null}
~/.plannotator/config.json
```

Plannotator treats a missing file as an empty config. If the JSON is malformed, it prints a warning and uses defaults.

## Precedence

The narrowest setting wins:

1. A command flag, when the command supports one
2. An environment variable
3. A value in `config.json`
4. The built-in default

For example, URL conversion resolves in this order: `--no-jina`, `PLANNOTATOR_JINA`, `jina` in `config.json`, then the default of enabled.

The Settings panel uses a related but separate rule. Settings that Plannotator syncs to the server prefer `config.json`, then the browser cookie, then the built-in default. Changes in the panel update the cookie immediately and write the supported fields back to `config.json`.

## Runtime config file

This example shows every top-level runtime key. You only need to include values you want to change.

```json theme={null}
{
  "displayName": "Avery",
  "diffOptions": {
    "diffStyle": "unified",
    "overflow": "wrap",
    "diffIndicators": "bars",
    "lineDiffType": "word-alt",
    "showLineNumbers": true,
    "showDiffBackground": true,
    "fontFamily": "monospace",
    "fontSize": "14px",
    "tabSize": 2,
    "hideWhitespace": false,
    "expandUnchanged": false,
    "defaultDiffType": "since-base",
    "lineBgIntensity": "normal"
  },
  "conventionalComments": true,
  "conventionalLabels": [
    { "label": "issue", "display": "Issue", "blocking": true },
    { "label": "suggestion", "display": "Suggestion", "blocking": false }
  ],
  "jina": true,
  "annotateHistory": true,
  "pfmReminder": false,
  "glimpse": true,
  "share": "enabled"
}
```

### Supported diff values

| Setting           | Values                                                                 |
| ----------------- | ---------------------------------------------------------------------- |
| `diffStyle`       | `split`, `unified`                                                     |
| `overflow`        | `scroll`, `wrap`                                                       |
| `diffIndicators`  | `bars`, `classic`, `none`                                              |
| `lineDiffType`    | `word-alt`, `word`, `char`, `none`                                     |
| `defaultDiffType` | `since-base`, `uncommitted`, `unstaged`, `staged`, `merge-base`, `all` |
| `lineBgIntensity` | `subtle`, `normal`, `strong`                                           |

`conventionalLabels` replaces the built-in comment labels. Set it to `null` to restore the defaults.

`annotateHistory` stores a copy of each annotated local file under the data directory so later sessions can show a version diff. Set it to `false` if you do not want that history written.

`verifyAttestation` is also a valid config key, but only the installer reads it. When enabled, installation requires an authenticated GitHub CLI and verifies build provenance after the checksum.

## Browser UI settings

The Settings panel stores UI preferences in a browser cookie because Plannotator sessions use changing local ports. The cookie can be shared across those ports on the same host.

The server-synced settings are your display name, diff options, conventional comments, and custom comment labels. Other interface choices, such as theme, layout, panel state, and file browser preferences, remain in the browser cookie.

Clearing site data for `localhost` resets cookie-only settings. It does not delete `config.json`, saved plans, or annotation history.

## Prompt customization

The `prompts` object in `config.json` changes supported feedback messages returned to the calling agent after a decision. It does not replace the instructions used by launched AI review jobs. See [Customize Feedback](/open-source/reference/custom-feedback) for supported paths, keys, placeholders, defaults, and precedence.

## Environment variables

Environment variables are the right layer for remote mode, a fixed port, a browser choice, or behavior set by an agent host. See [Environment variables](/open-source/reference/environment-variables).

Last verified against Plannotator OSS v0.23.1 on July 18, 2026. Maintained by the Plannotator project.