Plannotator environment variables

Use environment variables when a setting belongs to a shell, remote machine, or agent. Values set for one command affect only that run:

PLANNOTATOR_PORT=19432 plannotator review

Session and browser

Variable	Accepted value and behavior
`PLANNOTATOR_REMOTE`	Values: `1` or `true` forces remote mode. `0` or `false` forces local mode. Default: Detect SSH from `SSH_TTY` or `SSH_CONNECTION`.
`PLANNOTATOR_URL_HOST`	Values: A hostname, IPv4 address, bracketed IPv6 address, or `auto`. Effect: Changes the advertised remote URL without changing the server bind address. Auto: Uses the Tailscale MagicDNS name, then exactly one Tailscale IPv4 address. Precedence: The environment value overrides `urlHost` in `config.json`.
`PLANNOTATOR_PORT`	Values: A fixed port such as `19432`, or a range such as `19432-19463`. Default: A random available port locally and `19432` remotely.
`PLANNOTATOR_BROWSER`	Value: A browser app name or path on macOS, or an executable on Linux and Windows. Precedence: The CLI `--browser` flag wins.
`BROWSER`	Effect: Supplies the fallback browser command when `PLANNOTATOR_BROWSER` is unset. No browser: `none`, `false`, `0`, and `:` do not launch one.
`PLANNOTATOR_GLIMPSE`	Values: `1` or `true` enables the Glimpse window when available. Other values disable it. Default: Enabled.
`PLANNOTATOR_GLIMPSE_WIDTH`	Effect: Sets the initial Glimpse window width. Default: `1280`.
`PLANNOTATOR_GLIMPSE_HEIGHT`	Effect: Sets the initial Glimpse window height. Default: `900`.

Remote mode binds the unauthenticated local server to 0.0.0.0. Forward it through SSH or your development environment and do not expose that port to an untrusted network. See Troubleshooting. Use Tailscale remote reviews for tailnet-only HTTPS access that keeps the server on 127.0.0.1. See Remote access for trusted private networks, SSH, development containers, and opening a session from another device.

Variable	Accepted value and behavior
`PLANNOTATOR_JINA`	Values: `1` or `true` uses Jina Reader. Other values use direct fetch and local conversion. Precedence: The `--no-jina` flag wins.
`JINA_API_KEY`	Optional bearer token sent to Jina Reader.
`PLANNOTATOR_ANNOTATE_HISTORY`	Values: `1` or `true` saves per-file annotation history. Other values disable it. Default: Enabled.
`PLANNOTATOR_GUIDE_HISTORY`	Values: `1` or `true` saves successful Guided Reviews. Other values disable new writes. Default: Enabled. Existing data: Saved guides remain readable.
`PLANNOTATOR_SHARE`	Values: `disabled` hides sharing. Any other value enables it. Precedence: Overrides `share` in `config.json` for integrations that use Plannotator’s shared configuration resolver. An explicit OpenCode `share` setting takes precedence over this variable.
`PLANNOTATOR_SHARE_URL`	Effect: Sets the share portal base URL. Default: `https://share.plannotator.ai`.
`PLANNOTATOR_PASTE_URL`	Paste API used for encrypted short links and raw HTML sharing.

The portal and paste-service deployment variables are documented in Self-host Plannotator’s deprecated share services.

Files, diagnostics, and local tools

Variable	Accepted value and behavior
`PLANNOTATOR_DATA_DIR`	Effect: Selects the data directory for configuration, plans, history, sessions, and installed runtime state. Path: Expands a leading `~`. Resolves a relative value from the launch working directory. Default: An existing `~/.plannotator`, then an absolute `$XDG_DATA_HOME/plannotator`, then `~/.plannotator`.
`PLANNOTATOR_FILE_BROWSER_MAX_FILES`	Value: A positive integer. Effect: Limits files returned by the file browser. Default: `5000`.
`PLANNOTATOR_SEM_PATH`	Explicit path to the optional `sem` semantic-diff binary.
`PLANNOTATOR_GIT_TIMEOUT_MS`	Value: A timeout in milliseconds. Use: Set it only when you diagnose an unusually slow repository.
`PLANNOTATOR_DEBUG`	Any non-empty value enables additional diagnostic output.
`PLANNOTATOR_AGENT_TERMINAL_REMOTE`	Values: `1`, `true`, or `yes` enables the embedded agent terminal in remote mode or a `--tailscale` session. Default: Disabled for both session types. Risk: The terminal can run commands on the remote machine.
`PLANNOTATOR_AI`	Value: `disabled` removes Ask AI, Review Agents, and Guided Review. It also disables their provider and job endpoints. Other features: Ordinary reviews remain available.
`PLANNOTATOR_CURSOR_SANDBOX`	Values: `0`, `false`, or `disabled` omits Cursor’s `--sandbox enabled` flag. Default: Enabled. Risk: Without the flag, write protection depends on Ask mode and Cursor configuration.

Relative XDG_DATA_HOME values are ignored. Plannotator does not apply the XDG specification’s implicit ~/.local/share default.

Agent setup

Most users should let the installer set these values for supported agents.

Variable	Accepted value and behavior
`PLANNOTATOR_ORIGIN`	Values: `claude-code`, `amp`, `droid`, `opencode`, `codex`, `copilot-cli`, `gemini-cli`, `kiro-cli`, or `pi`. Effect: Forces the calling agent. Invalid value: Falls back to detection.
`PLANNOTATOR_CWD`	Original project directory supplied by an integration wrapper.
`PLANNOTATOR_BIN`	Effect: Sets the Plannotator executable for integrations that launch the CLI. Default: `plannotator` from `PATH`.
`PLANNOTATOR_PLAN_TIMEOUT_SECONDS`	Effect: Sets the maximum wait for OpenCode `submit_plan`. Default: `345600`. No timeout: Set `0`.
`PLANNOTATOR_ALLOW_SUBAGENTS`	Value: `1` lets OpenCode subagents use `submit_plan`. Default: Off.

Other PLANNOTATOR_* values in the source tree coordinate child processes, tests, or packaged integrations. They are not stable user configuration.

Installer controls

Variable	Accepted value and behavior
`PLANNOTATOR_MINIMAL`	Values: `1`, `true`, or `yes` installs only the CLI binary. Omitted components: Hooks, skills, and sidecar tools.
`PLANNOTATOR_VERIFY_ATTESTATION`	Enable: `1`, `true`, or `yes` requires build-provenance verification. Disable: `0`, `false`, or `no`.
`PLANNOTATOR_SKIP_SEM_INSTALL`	Values: `1`, `true`, or `yes` skips the semantic-diff sidecar.
`PLANNOTATOR_SKIP_AGENT_TERMINAL_INSTALL`	Values: `1`, `true`, or `yes` skips the agent-terminal runtime.
`PLANNOTATOR_PROMPT_TIMEOUT`	Effect: Sets the wait for an interactive integration choice in seconds. Default: `30`. No timeout: Set `0`.

The installer reads PLANNOTATOR_DATA_DIR and PLANNOTATOR_VERIFY_ATTESTATION too. See Privacy and data flow for the network and storage consequences of these settings. 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

Plannotator environment variables

Session and browser

Files, diagnostics, and local tools

Agent setup

Installer controls

​Session and browser

​Annotation, history, and sharing

​Files, diagnostics, and local tools

​Agent setup

​Installer controls

Session and browser

Annotation, history, and sharing

Files, diagnostics, and local tools

Agent setup

Installer controls