> ## 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

Plannotator chooses its data directory in this order:

1. `PLANNOTATOR_DATA_DIR`, with leading `~` expansion
2. An existing `~/.plannotator` directory
3. `$XDG_DATA_HOME/plannotator` when `XDG_DATA_HOME` is an absolute path
4. `~/.plannotator`

When `PLANNOTATOR_DATA_DIR` is relative, Plannotator resolves it from the process's launch working directory. The same value can select several directories when installers, agents, or shells start from different locations. Use an absolute value when several hosts share one configuration.

<Warning>
  Before you delete data, identify each working directory that launched Plannotator. Resolve `PLANNOTATOR_DATA_DIR` from each directory. Apply the deletion safety checks to every resulting absolute path.
</Warning>

It does not implicitly use `~/.local/share/plannotator` when `XDG_DATA_HOME` is unset. An existing `~/.plannotator` continues to win over XDG so an upgrade does not silently move your data.

The persistent runtime config is `<data-directory>/config.json`. At the default location, that 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 supported top-level config key. You only need to include values you want to change.

```json theme={null}
{
  "displayName": "Avery",
  "prompts": {},
  "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 }
  ],
  "verifyAttestation": false,
  "jina": true,
  "annotateHistory": true,
  "guideHistory": true,
  "pfmReminder": false,
  "glimpse": true,
  "share": "enabled",
  "cursorSandbox": true,
  "claudeCodeMod": true
}
```

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

`guideHistory` defaults to `true` and stores successful Guided Reviews and their section progress. Set it to `false` to stop new guide writes. Existing guides remain on disk.

`cursorSandbox` defaults to `true` and controls whether Plannotator passes `--sandbox enabled` to Cursor review jobs. Set it to `false` only when Cursor's sandbox cannot start on your system.

`claudeCodeMod` defaults to `true` and controls the [Plannotator mod](/open-source/agents/claude-code#the-plannotator-mod) on Claude Code 2.1.287 or later. Set it to `false` to turn the mod off, so Claude waits for your decision. `PLANNOTATOR_CLAUDE_MOD` overrides it. Claude Code reads it when it starts, so restart Claude Code after a change.

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

Some functional cookies do not use a `plannotator-` prefix. Current examples include `plannotator.agents`, `review-split-ratio`, and `update-dismissed-version`; Plannotator can also read the legacy `review-diff-style` cookie. Pull request review state uses other browser stores. Hidden artifact choices use `localStorage` keys named `plannotator-pr-artifacts:hidden:<PR URL>`, and review-submission recovery can use tab-scoped `sessionStorage`.

To remove browser state, close every Plannotator review and share tab first. In each browser profile, clear full site data for every exact Plannotator origin and port you used, including `http://localhost:<port>`, alternate local or remote origins, and `https://share.plannotator.ai` when applicable. If the browser groups cleanup by hostname, clearing `localhost` can also remove data for unrelated local applications. Browser cleanup does not delete `config.json`, saved plans, or annotation history from disk.

### Change the theme

Open the header menu, select **Settings**, then open **Theme**. Choose **Light**, **Dark**, or **System**, then choose a color theme. The mode and color theme are browser preferences, so they can differ between browsers.

When Plannotator opens inside the VS Code extension, it follows the current VS Code color theme. See [VS Code](/open-source/agents/vscode).

### Close the tab after a decision

Open **Settings > General > Auto-close Tab**. The default is **Off**, which keeps the completion page open after you send feedback, approve, or close a session. You can instead close it immediately, after three seconds, or after five seconds.

## 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).

`PLANNOTATOR_AI=disabled` is an environment-only kill switch. It removes Ask AI, Review Agents, and Guided Review from the UI and disables provider and review-job execution without disabling ordinary reviews.

Last verified on July 31, 2026, using Plannotator product commit `7cd023c`. Maintained by the Plannotator project.


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