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

# Troubleshoot Plannotator

> Fix installation, agent hooks, browser sessions, remote access, port conflicts, pull request review, HTML, URL, and sharing problems.

Start by checking the installed binary and live sessions:

```bash theme={null}
plannotator --version
plannotator sessions
```

Set `PLANNOTATOR_DEBUG=1` for additional terminal diagnostics while reproducing a problem.

## The command is not found

The macOS, Linux, and WSL installer writes the binary to `~/.local/bin/plannotator`. If that directory is not on `PATH`, add it to your shell configuration and start a new terminal:

```bash theme={null}
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
```

Use `~/.bashrc` instead for Bash. Confirm the result with:

```bash theme={null}
command -v plannotator
plannotator --version
```

On Windows, the PowerShell installer adds its install directory to your user `PATH`. Restart the terminal after installation. Desktop agent applications may not inherit the same `PATH` as your shell. Restart the application, or configure its hook with the absolute path to the executable.

A minimal install deliberately skips hooks, skills, slash commands, and sidecar tools. Run the full installer if you expected Plannotator to open from your agent.

## The browser did not open

The server may still be running. Read the terminal URL or reopen it:

```bash theme={null}
plannotator sessions
plannotator sessions --open
```

If the default browser command is wrong, select one for the current run:

```bash theme={null}
plannotator review --browser "Google Chrome"
```

You can also set `PLANNOTATOR_BROWSER`. On macOS it accepts an application name or path. On Linux and Windows, use an executable path. A `BROWSER` value such as `none`, `false`, `0`, or `:` intentionally suppresses browser opening.

If a stale session no longer responds, remove its record with `plannotator sessions --clean` and start a new review.

## Plan review does not trigger

First restart the agent after installing or changing a plugin, hook, policy, or config file. Then check the host-specific trigger:

| Agent | Current plan-review trigger |
| - | - |
| Claude Code | On Claude Code 2.1.287 or later, the plugin's Plannotator mod opens the review when Claude calls `ExitPlanMode`, and Claude does not wait. On older versions, in `claude -p` and SDK runs, on Windows, or with the mod off, the plugin intercepts `ExitPlanMode` through a `PermissionRequest` hook, and Claude waits. Install the marketplace plugin and restart Claude Code. |
| Codex | An experimental `Stop` hook opens the latest plan after the turn. The installer enables it on macOS, Linux, and WSL. Codex hooks are disabled on Windows. Restart Codex Desktop after changes. |
| Copilot CLI | The marketplace plugin intercepts `exit_plan_mode`. Restart after installing it and enter plan mode with `Shift` + `Tab`. |
| Gemini CLI | The installer adds the policy, hook, and commands. Gemini CLI 0.36.0 or later is required. |
| OpenCode | The `@plannotator/opencode` plugin gives `submit_plan` to the `plan` agent by default. The `build` agent cannot call it unless you choose a broader workflow. Restart after editing `opencode.json`. |
| Pi | Install `npm:@plannotator/pi-extension`, start Pi with `--plan`, or toggle with `/plannotator-plan-mode`. |
| Amp, Droid, Kiro CLI | Use the installed Plannotator command, skill, plugin workflow, or example agent. These agents do not transparently intercept every plan exit. |

Run a direct command such as `plannotator annotate path/to/plan.md` to separate a CLI/browser problem from a host-hook problem. If the direct command works, inspect the agent's hook log and verify that its process can find the binary.

## Claude Code still waits for my review

On Claude Code 2.1.287 or later, the [Plannotator mod](/open-source/agents/claude-code#the-plannotator-mod) lets Claude keep going while you review. If Claude still waits:

1. Update the plugin. In a terminal, run `claude plugin marketplace update plannotator`, then `claude plugin update plannotator@plannotator`, then restart Claude Code. Refreshing the marketplace alone does not update the plugin.
2. Update the `plannotator` binary by running the installer again. With an older binary, plan review falls back to the waiting flow.
3. Check that `PLANNOTATOR_CLAUDE_MOD` is not set to `0` and that `~/.plannotator/config.json` has no `"claudeCodeMod": false`.
4. The mod does not run in `claude -p` or SDK runs, or on Windows. Those always wait.
5. To report a problem, start Claude Code with `PLANNOTATOR_MOD_DEBUG=1` and attach `~/.plannotator/claude-code-mod/debug.log`.

## Remote SSH and development containers

Confirm that the agent process inherited both remote settings:

```bash theme={null}
env | grep '^PLANNOTATOR_REMOTE='
env | grep '^PLANNOTATOR_PORT='
```

With the default remote port, forward the session from your local machine:

```bash theme={null}
ssh -L 19432:127.0.0.1:19432 user@host
```

Setting `PLANNOTATOR_PORT` alone does not make a container session reachable. `PLANNOTATOR_REMOTE=1` changes the bind address from `127.0.0.1` to `0.0.0.0`.

<Warning>
  Remote mode exposes an unauthenticated HTTP server on `0.0.0.0`. Do not publish the port or bind it to an untrusted network. Use SSH forwarding or a trusted private development environment.
</Warning>

Follow [Remote access](/open-source/remote-access) for the SSH command, development-container configuration, direct private-network access, verification steps, and remote-sharing boundary.

The embedded agent terminal is disabled in remote mode by default.

<Warning>
  Set `PLANNOTATOR_AGENT_TERMINAL_REMOTE=1` only on a trusted connection. This setting enables command execution through the forwarded UI.
</Warning>

## A port is already in use

Local sessions normally choose a free random port. Remote sessions default to `19432`. Pick another fixed port or let Plannotator try a range:

```bash theme={null}
PLANNOTATOR_PORT=19433 plannotator review
PLANNOTATOR_PORT=19432-19463 plannotator review
```

A fixed port is retried five times for a transient conflict. A range advances immediately to the next available port. An invalid port value prints a warning and falls back to the normal default.

## GitHub pull request or GitLab merge request review fails

Plannotator uses the matching host CLI. Install and authenticate it before opening the review:

```bash theme={null}
gh auth login
gh auth status

glab auth login
glab auth status
```

Use `gh` for GitHub pull requests and `glab` for GitLab merge requests. For an enterprise host, authenticate the same hostname used in the URL.

By default, Plannotator prepares a local checkout for full file access. If cloning or checkout preparation fails, use diff-only mode:

```bash theme={null}
plannotator review --no-local PR_OR_MR_URL
```

Diff-only mode cannot provide every local file or repository operation. For local changes, run `plannotator review` from inside the repository and confirm that the working tree has a supported VCS.

## Local HTML does not render correctly

Local HTML renders raw by default. Do not add the old `--render-html` flag; it is retained only as a compatibility no-op.

Relative images, stylesheets, scripts, fonts, media, and other supported assets are served from the HTML file's directory. Plannotator refuses paths outside that directory, unsupported asset types, missing files, and files over the asset-size limit. Check the browser network panel for `403`, `404`, `413`, or `415` responses and make the document self-contained when practical.

To review the document's text instead of its rendered page, convert it to Markdown:

```bash theme={null}
plannotator annotate page.html --markdown
```

Raw HTML is rendered in a sandboxed iframe, but its scripts can still run inside that frame. Review only HTML you trust.

## URL annotation fails or shows poor content

Plannotator first accepts native Markdown when a site serves it, then uses Jina Reader by default for public HTML. If Jina fails, it warns and falls back to direct fetch and local conversion.

Force the direct path when a site works better without Jina:

```bash theme={null}
plannotator annotate https://example.com/page --no-jina
```

Local and private-network URLs skip Jina automatically. Public URLs that redirect to a private or local address are blocked. Fetches time out after 30 seconds and responses are limited to 10 MB. Authentication cookies from your browser are not sent, so save a protected page locally before annotating it.

If Jina rate limits the request, set `JINA_API_KEY` or use `--no-jina`.

## A local annotation file is too large

Single-file and folder annotation accept local files up to 2 MiB. A larger file fails with `File too large to annotate (max 2MB)`. Reduce or split the file before reopening it. In a strict `annotate --gate --json` workflow, this startup failure exits `2`.

## A large untracked file appears as binary

Code review loads and diffs untracked text files up to 5 MiB. An untracked file over that limit appears as a binary addition and Plannotator refuses to load its contents. Exclude, reduce, or commit the file if you need to inspect it through another comparison.

## Sharing fails

Check whether sharing is disabled:

```bash theme={null}
env | grep '^PLANNOTATOR_SHARE='
```

`PLANNOTATOR_SHARE=disabled` overrides `config.json` for integrations that use Plannotator's shared configuration resolver. OpenCode checks an explicit OpenCode `share` setting first, so set that value to `"disabled"` as well. For other integrations, remove the environment variable or set an enabled value for a new session when sharing is intended.

Markdown share links can carry compressed content in the URL fragment. Raw HTML sharing uses an encrypted paste service so local assets can be included. If raw HTML sharing fails:

* check network access to the paste service
* check `PLANNOTATOR_PASTE_URL` if you configured a custom service
* remove unnecessary assets or make the HTML smaller and self-contained

The decryption key remains in the URL fragment. Anyone with the complete link can open the shared content, so treat the link as sensitive.

## Config changes are ignored

Confirm that you edited `config.json` in the active data directory. Plannotator chooses that directory in this order:

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

An existing `~/.plannotator` wins over XDG. A relative `XDG_DATA_HOME` is ignored, and Plannotator does not implicitly use `~/.local/share`.

If `PLANNOTATOR_DATA_DIR` is relative, Plannotator resolves it from the working directory where that process launched. The installer, agents, and shells can use different directories for the same value. Make sure that you inspect every working directory, not only the environment variable.

Malformed JSON produces a warning and Plannotator uses defaults. Validate the file with a JSON parser. Remember that command flags and environment variables override `config.json` for the settings they control.

The Settings panel also uses a browser cookie. Server-synced fields prefer `config.json`; interface-only fields live only in the cookie. Clear site data for `localhost` if a cookie-only setting is stuck, but note that this resets other Plannotator UI preferences in that browser.

## Cursor review jobs fail to start

Cursor review jobs use Ask mode and pass `--sandbox enabled` by default. On systems where Cursor's sandbox cannot start, including some NixOS or AppArmor-restricted Linux setups, retry without the forced sandbox:

```bash theme={null}
PLANNOTATOR_CURSOR_SANDBOX=0 plannotator review
```

For a persistent setting, add `"cursorSandbox": false` to `config.json`. Plannotator then omits the sandbox flag and defers to your Cursor Agent configuration. Write protection depends on `--mode ask` and your Cursor settings in this mode.

## AI panels are missing

Check for an explicit kill switch:

```bash theme={null}
env | grep '^PLANNOTATOR_AI='
```

`PLANNOTATOR_AI=disabled` removes Ask AI, Review Agents, and Guided Review and disables their provider and job endpoints. Remove it or set another value, then start a new session. Ordinary reviews and external annotation submission still work.

## Ask for help

When reporting a reproducible OSS issue, include:

* `plannotator --version`
* operating system and agent name/version
* the command you ran, with secrets and private URLs removed
* terminal output with `PLANNOTATOR_DEBUG=1`
* whether the direct CLI command works outside the agent hook

Report issues at [github.com/backnotprop/plannotator/issues](https://github.com/backnotprop/plannotator/issues).

Last verified against Plannotator OSS v0.25.1 on July 31, 2026. Maintained by the Plannotator project.


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