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

# Install Plannotator

> Install, update, or remove Plannotator on macOS, Linux, WSL, or Windows, then finish setup for your coding agent.

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

<Tabs>
  <Tab title="macOS, Linux, or WSL">
    ```bash theme={null}
    curl -fsSL https://plannotator.ai/install.sh | bash
    ```
  </Tab>

  <Tab title="Windows PowerShell">
    ```powershell theme={null}
    irm https://plannotator.ai/install.ps1 | iex
    ```
  </Tab>

  <Tab title="Windows Command Prompt">
    ```bat theme={null}
    curl -fsSL https://plannotator.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
    ```
  </Tab>
</Tabs>

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](/open-source/start/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:

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

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.

| Host | Next step |
| - | - |
| [Claude Code](/open-source/agents/claude-code) | Install the separate Claude Code marketplace plugin and restart Claude Code. |
| [Codex](/open-source/agents/codex) | The installer always adds the shared core skills. When it detects Codex on macOS, Linux, or WSL, it also enables the experimental plan-review hook. Restart Codex Desktop. Hooks remain disabled on Windows. |
| [OpenCode](/open-source/agents/opencode) | Add `@plannotator/opencode@latest` to `opencode.json`, then restart OpenCode. |
| [Copilot CLI](/open-source/agents/copilot-cli) | Install the Copilot CLI marketplace plugin, then restart Copilot CLI. |
| [Gemini CLI](/open-source/agents/gemini-cli) | The standard installer adds the policy, plan-review hook, and commands when it detects `~/.gemini`. Restart Gemini CLI. |
| [Amp](/open-source/agents/amp) | Copy the Amp plugin into the user or project plugin directory. |
| [Droid](/open-source/agents/droid) | Add the Plannotator marketplace and install its Droid plugin. |
| [Kiro CLI](/open-source/agents/kiro-cli) | The standard installer adds review skills and an example agent when it detects Kiro CLI. Rerun the installer if you installed Kiro later. |
| [Pi](/open-source/agents/pi) | Install `@plannotator/pi-extension` through Pi. The standard installer is not required. |

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

<Tabs>
  <Tab title="macOS, Linux, or WSL">
    ```bash theme={null}
    curl -fsSL https://plannotator.ai/install.sh | bash -s -- --minimal
    ```
  </Tab>

  <Tab title="Windows PowerShell">
    ```powershell theme={null}
    & ([scriptblock]::Create((irm https://plannotator.ai/install.ps1))) -Minimal
    ```
  </Tab>
</Tabs>

`--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:

<Tabs>
  <Tab title="macOS, Linux, or WSL">
    ```bash theme={null}
    curl -fsSL https://plannotator.ai/install.sh | bash -s -- --version vX.Y.Z
    ```
  </Tab>

  <Tab title="Windows PowerShell">
    ```powershell theme={null}
    & ([scriptblock]::Create((irm https://plannotator.ai/install.ps1))) -Version vX.Y.Z
    ```
  </Tab>

  <Tab title="Windows Command Prompt">
    ```bat theme={null}
    curl -fsSL https://plannotator.ai/install.cmd -o install.cmd
    install.cmd --version vX.Y.Z
    del install.cmd
    ```

    The positional form is also supported after you download the script:

    ```bat theme={null}
    install.cmd vX.Y.Z
    ```
  </Tab>
</Tabs>

Every installer verifies the binary against its SHA-256 checksum. Optional SLSA provenance verification requires the [GitHub CLI](https://cli.github.com/). The installer first uses GitHub's public attestations API. It uses authenticated GitHub CLI access only if the public request fails.

<Tabs>
  <Tab title="macOS, Linux, or WSL">
    ```bash theme={null}
    curl -fsSL https://plannotator.ai/install.sh | bash -s -- --version vX.Y.Z --verify-attestation
    ```
  </Tab>

  <Tab title="Windows PowerShell">
    ```powershell theme={null}
    & ([scriptblock]::Create((irm https://plannotator.ai/install.ps1))) -Version vX.Y.Z -VerifyAttestation
    ```
  </Tab>

  <Tab title="Windows Command Prompt">
    ```bat theme={null}
    curl -fsSL https://plannotator.ai/install.cmd -o install.cmd
    install.cmd --version vX.Y.Z --verify-attestation
    del install.cmd
    ```
  </Tab>
</Tabs>

Windows provenance verification supports stable releases from v0.17.2 onward. The Windows installers reject prerelease tags when verification is enabled.

### Download and verify the release evidence

Each release from v0.27.3 includes a release-wide CycloneDX SBOM and a matching checksum. Replace `vX.Y.Z` with a released tag. The following commands download and verify the Linux x64 binary and its SBOM:

```bash theme={null}
tag=vX.Y.Z
version="${tag#v}"
mkdir -p /tmp/plannotator-release-verify
gh release download "$tag" --repo backnotprop/plannotator \
  --pattern 'plannotator-linux-x64*' \
  --pattern "plannotator-${version}-release-sbom.cdx.json*" \
  --dir /tmp/plannotator-release-verify

(cd /tmp/plannotator-release-verify && sha256sum --check plannotator-linux-x64.sha256)
(cd /tmp/plannotator-release-verify && sha256sum --check "plannotator-${version}-release-sbom.cdx.json.sha256")

gh attestation verify /tmp/plannotator-release-verify/plannotator-linux-x64 \
  --repo backnotprop/plannotator --source-ref "refs/tags/$tag" \
  --signer-workflow backnotprop/plannotator/.github/workflows/release.yml \
  --predicate-type https://slsa.dev/provenance/v1

gh attestation verify /tmp/plannotator-release-verify/plannotator-linux-x64 \
  --repo backnotprop/plannotator --source-ref "refs/tags/$tag" \
  --signer-workflow backnotprop/plannotator/.github/workflows/release.yml \
  --predicate-type https://cyclonedx.org/bom
```

The two attestation commands verify separate claims for the same binary. The SLSA predicate identifies the source and release workflow. The CycloneDX predicate contains the release-wide SBOM.

Bun standalone binaries do not expose their bundled JavaScript package metadata to Syft. The SBOM is not an exact runtime inventory for each binary.

Use the matching release filename to verify another platform. On macOS, use `shasum -a 256 -c` instead of `sha256sum --check`.

## 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 updates the Pi extension when `pi` is on your `PATH`.

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. Refreshing the marketplace alone does not update it. In a terminal, run `claude plugin marketplace update plannotator`, then `claude plugin update plannotator@plannotator`, then restart Claude Code. See [Update](/open-source/agents/claude-code#update) for the steps inside Claude Code.
* OpenCode loads the separately configured `@plannotator/opencode@latest` plugin. The installer clears its cached Plannotator plugin packages for OpenCode 1 and OpenCode 2. Restart OpenCode after the update.
* The installer updates the Pi extension only when `pi` is on your `PATH`. Otherwise, run `pi update --extensions`. A plain `pi update` updates only Pi itself.
* 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](/open-source/start/skills#update-skills).

Check the installed binary after an update:

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

## Remove Plannotator

Use this safety checklist:

1. Close active Plannotator and agent sessions.
2. Preview the recognized removal work:

```bash theme={null}
plannotator uninstall --dry-run
```

3. Read the preview. Then run the safe default:

```bash theme={null}
plannotator uninstall
```

The safe default removes recognized Plannotator-installed components. It preserves 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

<Warning>
  Use `--purge` only when you intend to delete known local Plannotator data. The deleted data cannot be recovered.
</Warning>

Run:

```bash theme={null}
plannotator uninstall --purge
```

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](/open-source/reference/configuration#where-settings-live). 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 these components:

* 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
* 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:

```bash theme={null}
plannotator uninstall --skip-hosts
```

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](https://github.com/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](/open-source/start/quickstart).

Last verified on August 13, 2026, using Plannotator product commit `aa0bf86`. Maintained by the Plannotator project.


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