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

Plannotator chooses its data directory in this order:

PLANNOTATOR_DATA_DIR, with leading ~ expansion
An existing ~/.plannotator directory
$XDG_DATA_HOME/plannotator when XDG_DATA_HOME is an absolute path
~/.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.

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.

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:

~/.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 supported top-level config key. You only need to include values you want to change.

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

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

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

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

Change the theme

Close the tab after a decision

Prompt customization

Environment variables

​Where settings live

​Precedence

​Runtime config file

​Supported diff values

​Browser UI settings

​Change the theme

​Close the tab after a decision

​Prompt customization

​Environment variables

Where settings live

Precedence

Runtime config file

Supported diff values

Browser UI settings

Change the theme

Close the tab after a decision

Prompt customization

Environment variables