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

# Plannotator environment variables

> Runtime, browser, remote-session, sharing, installer, and agent environment variables supported by Plannotator.

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

```bash theme={null}
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.<br />**Default:** Detect SSH from `SSH_TTY` or `SSH_CONNECTION`. |
| `PLANNOTATOR_URL_HOST` | **Values:** A hostname, IPv4 address, bracketed IPv6 address, or `auto`.<br />**Effect:** Changes the advertised remote URL without changing the server bind address.<br />**Auto:** Uses the Tailscale MagicDNS name, then exactly one Tailscale IPv4 address.<br />**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`.<br />**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.<br />**Precedence:** The CLI `--browser` flag wins. |
| `BROWSER` | **Effect:** Supplies the fallback browser command when `PLANNOTATOR_BROWSER` is unset.<br />**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.<br />**Default:** Enabled. |
| `PLANNOTATOR_GLIMPSE_WIDTH` | **Effect:** Sets the initial Glimpse window width.<br />**Default:** `1280`. |
| `PLANNOTATOR_GLIMPSE_HEIGHT` | **Effect:** Sets the initial Glimpse window height.<br />**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](/open-source/troubleshooting#remote-ssh-and-development-containers).

Use [Tailscale remote reviews](/open-source/tailscale) for tailnet-only HTTPS access that keeps the server on `127.0.0.1`.

See [Remote access](/open-source/remote-access) for trusted private networks, SSH, development containers, and opening a session from another device.

## Annotation, history, and sharing

| Variable | Accepted value and behavior |
| - | - |
| `PLANNOTATOR_JINA` | **Values:** `1` or `true` uses Jina Reader. Other values use direct fetch and local conversion.<br />**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.<br />**Default:** Enabled. |
| `PLANNOTATOR_GUIDE_HISTORY` | **Values:** `1` or `true` saves successful Guided Reviews. Other values disable new writes.<br />**Default:** Enabled.<br />**Existing data:** Saved guides remain readable. |
| `PLANNOTATOR_SHARE` | **Values:** `disabled` hides sharing. Any other value enables it.<br />**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.<br />**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](/open-source/self-hosting#deployment-variables).

## 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.<br />**Path:** Expands a leading `~`. Resolves a relative value from the launch working directory.<br />**Default:** An existing `~/.plannotator`, then an absolute `$XDG_DATA_HOME/plannotator`, then `~/.plannotator`. |
| `PLANNOTATOR_FILE_BROWSER_MAX_FILES` | **Value:** A positive integer.<br />**Effect:** Limits files returned by the file browser.<br />**Default:** `5000`. |
| `PLANNOTATOR_SEM_PATH` | Explicit path to the optional `sem` semantic-diff binary. |
| `PLANNOTATOR_GIT_TIMEOUT_MS` | **Value:** A timeout in milliseconds.<br />**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.<br />**Default:** Disabled for both session types.<br />**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.<br />**Other features:** Ordinary reviews remain available. |
| `PLANNOTATOR_CURSOR_SANDBOX` | **Values:** `0`, `false`, or `disabled` omits Cursor's `--sandbox enabled` flag.<br />**Default:** Enabled.<br />**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`.<br />**Effect:** Forces the calling agent.<br />**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.<br />**Default:** `plannotator` from `PATH`. |
| `PLANNOTATOR_PLAN_TIMEOUT_SECONDS` | **Effect:** Sets the maximum wait for OpenCode `submit_plan`.<br />**Default:** `345600`.<br />**No timeout:** Set `0`. |
| `PLANNOTATOR_ALLOW_SUBAGENTS` | **Value:** `1` lets OpenCode subagents use `submit_plan`.<br />**Default:** Off. |

## Claude Code

These apply to the [Plannotator mod](/open-source/agents/claude-code#the-plannotator-mod) on Claude Code 2.1.287 or later. Set them in the shell that starts Claude Code or in the `env` block of Claude Code's `settings.json`. Claude Code reads them when it starts, so restart it after a change.

| Variable | Accepted value and behavior |
| - | - |
| `PLANNOTATOR_CLAUDE_MOD` | **Off:** `0`, `false`, `off`, or `disabled` turns the mod off. Claude then waits for your decision, and Ask AI uses a provider you pick.<br />**On:** `1`, `true`, or `on`. An empty or other value counts as unset.<br />**Default:** On.<br />**Precedence:** Overrides `claudeCodeMod` in `config.json`.<br />**Always off:** In `claude -p` and SDK runs, and on Windows. |
| `PLANNOTATOR_MOD_DEBUG` | **Value:** `1` makes the mod write a debug log to `~/.plannotator/claude-code-mod/debug.log`, or under `PLANNOTATOR_DATA_DIR` when set.<br />**Default:** Off.<br />**Use:** Attach the log when you report a problem with the mod. |

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.<br />**Omitted components:** Hooks, skills, and sidecar tools. |
| `PLANNOTATOR_VERIFY_ATTESTATION` | **Enable:** `1`, `true`, or `yes` requires build-provenance verification.<br />**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.<br />**Default:** `30`.<br />**No timeout:** Set `0`. |

The installer reads `PLANNOTATOR_DATA_DIR` and `PLANNOTATOR_VERIFY_ATTESTATION` too.

See [Privacy and data flow](/open-source/reference/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.


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