Skip to main content
The standard installer adds the plannotator command, checks the downloaded binary, and installs the hooks, core skills, native command files, and local runtimes used by supported coding agents. Rerun the same installer to update those managed files.

​
Run the installer

The macOS and Linux installer supports x64 and Arm64. The Windows installers support x64 and Arm64 Windows. The full installer needs Git to fetch the current skills and command files. The optional integrated terminal also needs Node.js and npm. If that runtime cannot be installed, document annotation still works without the integrated terminal. The installer downloads the binary and checksum from GitHub Releases. A full install can also contact GitHub for agent files, Ataraxy-Labs/sem for the optional sem sidecar, and npm for Pi, selected extra skills, or the managed agent-terminal runtime. Pinning a version skips GitHub’s latest-release API lookup, but it still downloads that release’s binary and checksum.

​
Choose skills during installation

On the first interactive run, the full installer asks:
  1. Whether to install the extra plannotator-compound, plannotator-setup-goal, and plannotator-visual-explainer skills. The default is no.
  2. Whether the model may start any installed Claude Code or shared Agent Skill without an explicit skill command. The default keeps those skills user-started.
The installer saves these answers under the active Plannotator data directory and reuses them on later runs. Use --reconfigure on macOS, Linux, WSL, and Command Prompt, or -Reconfigure in PowerShell, to open the questions again. Runs without an interactive terminal do not prompt. They use explicit flags, then saved answers, then the defaults. Automation can use --extras, --no-extras, --model-invocable <comma-separated-list>, and --non-interactive. PowerShell uses -Extras, -NoExtras, -ModelInvocable, and -NonInteractive. See Install and Manage Plannotator Skills for the core and extra skill lists, specific-skill commands, host locations, updates, and removal.

​
Verify the command

Open a new terminal if the installer changed your PATH, then run:
The help output lists the user-facing commands supported by the installed version.

​
Finish your agent setup

Choose your coding agent. The table shows what to do after the standard installer.

​
Install only the binary

Use a minimal install when you want the command without agent hooks, skills, commands, the optional sem semantic-diff sidecar, or the managed agent-terminal runtime.
--binary-only is an alias for --minimal in the shell installer. -BinaryOnly is the PowerShell alias. You can also set PLANNOTATOR_MINIMAL=1. Minimal mode does not use the skills checkout, so Git is not required. Rerun the full installer later if you want core skills or agent setup.

​
Pin or verify a release

Pin a release when you need a repeatable install:
Every installer checks the binary against its SHA-256 checksum. SLSA provenance verification is optional and requires an installed and authenticated GitHub CLI:
Windows provenance verification supports stable releases from v0.17.2 onward. The Windows installers reject prerelease tags when verification is enabled.

​
Update Plannotator

Rerun the installer for your operating system. Without a version flag, it resolves the latest GitHub release and replaces the installed binary, core skills, OpenCode and Gemini command files, and installer-managed hook or policy files. It also runs Pi’s extension install when Pi is available. Your Plannotator data directory is not replaced. Saved plans, annotation history, drafts, configuration, and installer preferences remain available. Some host integrations have their own lifecycle:
  • Claude Code’s marketplace plugin is separate from the binary and skills. Run /plugin marketplace update in Claude Code after upgrading, then restart it.
  • OpenCode loads the separately configured @plannotator/opencode@latest plugin. The installer clears its Plannotator package cache; restart OpenCode after the update.
  • Pi can update its extension directly with pi install npm:@plannotator/pi-extension.
  • Copilot CLI, Droid, and Amp plugins remain under their host’s plugin or file-management flow.
  • Extra skills installed with npx skills update through that CLI. See Update skills.
Check the installed binary after an update:

​
Remove Plannotator

Close active Plannotator and agent sessions. Preview the recognized removal work without changing anything:
The safe default removes recognized Plannotator-installed components and preserves your local plans, history, drafts, guides, configuration, and installer preferences:
The confirmation defaults to no. For a non-interactive shell or automation, add --yes or -y; the command refuses to run without that flag when no terminal is available.

​
Delete local data too

Use --purge to remove known local Plannotator data with the installed components:
Interactive purge requires typing purge, not only y. The prompt explains that this data exists locally, is not stored on a Plannotator server, and cannot be recovered after deletion. --yes skips that prompt for automation. Purge uses the active data-directory resolution rules. It refuses filesystem roots, the home directory and its ancestors, the shared temporary directory, symlinked data directories, and non-directory paths. Existing targets are checked by filesystem identity, so case aliases, symlinks, hardlinks, bind mounts, and a directory swapped during host cleanup cannot bypass the safety boundary. Unknown or custom entries inside the data directory are preserved. If a recognized entry cannot be removed safely, uninstall reports the failure and keeps the command available for a retry.

​
Understand what the command removes

The uninstaller recognizes:
  • the conventional macOS, Linux, WSL, and Windows executable locations;
  • installer-managed sem and agent-terminal runtimes;
  • core skills, native command files, hooks, policies, scoped caches, and recognizable Amp and Kiro files;
  • detected Claude Code, Copilot CLI, Droid, Pi, and VS Code integrations through their host commands; and
  • installer-managed OpenCode, Gemini, Codex, and Windows PATH configuration.
Shared configuration files are edited surgically. Custom files, unrecognized skill layouts, separately installed optional skills, project-local integrations, external save locations, unrelated package caches, and editor-managed shared state are preserved. A host command or configuration that cannot be classified safely produces an error instead of guessing. The executable and its Windows PATH entry remain available when cleanup must be retried. The command cannot safely clear every browser profile or shared editor database. Browser cookies and storage remain scoped to each exact origin and port. The VS Code extension can also leave its Plannotator cookie jar in editor-managed globalState. Clear those records through the browser or editor only when you can distinguish them from unrelated application data.

​
Recover from a broken host integration

If a missing host command or malformed host configuration prevents completion, leave all host plugin managers and host configuration untouched while removing the other recognized components:
Use this as a recovery path, not as the normal uninstall. A preserved hook or command can still point to the removed Plannotator executable and fail when its host invokes it. The current command emits a general warning but does not list every preserved integration. Remove those host entries manually after the uninstall completes.

​
Read release notes

backnotprop/plannotator releases are the changelog for the OSS binary and its release assets. Each release page provides its tag and downloadable artifacts. Use --version vX.Y.Z when you need to reinstall a specific release. Continue with annotating your first plan. Last verified on August 1, 2026, using Plannotator product commit 93b66e0. Maintained by the Plannotator project.
Last modified on August 1, 2026