Configure Plannotator

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:

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

A command flag, when the command supports one
An environment variable
A value in config.json
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.

{
  "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 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. Last verified against Plannotator OSS v0.23.1 on July 18, 2026. Maintained by the Plannotator project.

Start

Plans and documents

Code review

Reference

Agents

Editors and notes

Troubleshooting

Related project

Configure Plannotator

Where settings live

Precedence

Runtime config file

Supported diff values

Browser UI settings

Prompt customization

Environment variables

​Where settings live

​Precedence

​Runtime config file

​Supported diff values

​Browser UI settings

​Prompt customization

​Environment variables

Where settings live

Precedence

Runtime config file

Supported diff values

Browser UI settings

Prompt customization

Environment variables