> ## 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 | The plugin intercepts `ExitPlanMode` through a `PermissionRequest` hook. 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`. | | 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. ## Remote SSH and development containers Use a fixed forwarded port and force remote mode: ```bash theme={null} export PLANNOTATOR_REMOTE=1 export PLANNOTATOR_PORT=9999 plannotator review ``` For SSH, forward the same port to your machine: ```bash theme={null} ssh -L 9999:localhost:9999 user@host ``` Open `http://localhost:9999` locally while the review is running. For a development container, set the variables in `containerEnv` and include `9999` in `forwardPorts`. 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`. 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. The embedded agent terminal is disabled in remote mode by default. `PLANNOTATOR_AGENT_TERMINAL_REMOTE=1` enables command execution through the forwarded UI and should only be used on a trusted connection. ## 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 is the problem, try 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`. ## Sharing fails Check whether sharing is disabled: ```bash theme={null} env | grep '^PLANNOTATOR_SHARE=' ``` `PLANNOTATOR_SHARE=disabled` overrides `config.json` and hides sharing. Remove it or set an enabled value for a new session. 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 the active data directory: ```bash theme={null} printf '%s\n' "${PLANNOTATOR_DATA_DIR:-$HOME/.plannotator}/config.json" ``` 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. ## 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.23.1 on July 18, 2026. Maintained by the Plannotator project.