Plannotator

https://docs.plannotator.ai/
Admin
Plannotator is an open-source tool for reviewing and annotating AI agent plans and code, providing a...
Tokens:62,513
Snippets:1,023
Trust Score:4.6
Update:2 months ago
Show doc for...
Tokens:
Raw
### Document Setup and Build Commands

Source: https://docs.plannotator.ai/learn/ai-development/how-to-write-a-good-agents-md

List essential commands for installation, testing, and verification to guide the agent's workflow.

```markdown
## Commands

- Install dependencies with `pnpm install` from the repository root.
- Run focused tests with `pnpm test --filter <package>` while developing.
- Before finishing, run `pnpm lint`, `pnpm typecheck`, and the tests for every changed package.
```

--------------------------------

### Install and Run Artifact Server

Source: https://docs.plannotator.ai/open-source/artifact-server

Commands to clone, build, and start the server from the source repository.

```bash
git clone https://github.com/plannotator/artifact-server.git
cd artifact-server
pnpm install
pnpm build
pnpm start
```

--------------------------------

### Verify Plannotator installation

Source: https://docs.plannotator.ai/open-source/troubleshooting

Check the installed version and list active sessions.

```bash
plannotator --version
plannotator sessions
```

--------------------------------

### Install Plannotator via CLI

Source: https://docs.plannotator.ai/open-source/agents/claude-code

Execute this command to download and install the Plannotator script.

```bash
curl -fsSL https://plannotator.ai/install.sh | bash
```

--------------------------------

### Requirement and Verification Example

Source: https://docs.plannotator.ai/templates/technical-specification

An example demonstrating how to map specific requirements to their corresponding verification steps.

```markdown
## Requirements
- R1. An expired share link returns the same public response as an unknown link.

## Verification
- V1. Create one valid and one expired link against the real route harness.
- V2. Assert that both hidden cases return the documented status and body.
- V3. Assert that the expired request does not read document content.
```

--------------------------------

### Annotated AGENTS.md Example

Source: https://docs.plannotator.ai/templates/agents-md

A practical example demonstrating how to populate the AGENTS.md template with specific project commands and safety rules.

```markdown
# Project instructions

This repository builds a Node API and React web app.

## Setup and commands
- Install: `pnpm install`
- Test: `pnpm test`
- Typecheck: `pnpm typecheck`

## Safety boundaries
- Never place credentials in the repository.
- Do not edit files under `packages/api/generated/`; run `pnpm gen:api`.

## More specific guidance
- API changes: `docs/API.md`
- Web accessibility: `apps/web/AGENTS.md`
```

--------------------------------

### Install minimal binary

Source: https://docs.plannotator.ai/open-source/start/installation

Performs a minimal installation without agent hooks, skills, or the managed terminal runtime.

```bash
curl -fsSL https://plannotator.ai/install.sh | bash -s -- --minimal
```

```powershell
& ([scriptblock]::Create((irm https://plannotator.ai/install.ps1))) -Minimal
```

--------------------------------

### Verify Plannotator Installation

Source: https://docs.plannotator.ai/open-source/start/installation

Check that the installation was successful and view available commands by querying the version and help documentation.

```bash
plannotator --version
plannotator --help
```

--------------------------------

### Execute goal setup commands

Source: https://docs.plannotator.ai/open-source/reference/cli

Configures interview or facts workflows using a JSON bundle.

```bash
plannotator setup-goal <interview|facts> <bundle.json | -> [--json]
```

--------------------------------

### Annotated ADR Example

Source: https://docs.plannotator.ai/templates/architecture-decision-record

A practical example demonstrating how to document a specific database-related architectural decision.

```markdown
# 0012 Store job leases in the database

Status: Accepted

## Context
Two workers can claim the same queued job after a process restart. In-memory locks do not survive or coordinate across processes.

## Decision
We will acquire a time-bounded lease with one conditional database update before work begins.

## Consequences
- Workers can recover abandoned jobs after the lease expires.
- Lease duration and renewal become operational settings that require monitoring.

## Confirmation
An integration test starts two workers against one database and proves only one performs the job.
```

--------------------------------

### Start a local review

Source: https://docs.plannotator.ai/learn/local-diff-review-for-coding-agents

Execute this command in a repository to open the current change set in a browser for review.

```bash
plannotator review
```

--------------------------------

### Run Plannotator without installation

Source: https://docs.plannotator.ai/open-source/agents/pi

Executes the extension directly without a permanent installation.

```bash
pi -e npm:@plannotator/pi-extension
```

--------------------------------

### Install the compound skill

Source: https://docs.plannotator.ai/code-context/compound-with-plannotator

Use the Skills CLI to add the compound skill to your Plannotator environment.

```bash
npx skills add backnotprop/plannotator/apps/skills/extra
```

--------------------------------

### Install Plannotator plugin

Source: https://docs.plannotator.ai/open-source/agents/copilot-cli

Commands to add and install the Plannotator plugin within the Copilot CLI interface.

```text
/plugin marketplace add backnotprop/plannotator
/plugin install plannotator-copilot@plannotator
```

--------------------------------

### Install Plannotator Droid plugin

Source: https://docs.plannotator.ai/open-source/agents/droid

Commands to add and install the Plannotator plugin via the Droid marketplace.

```bash
droid plugin marketplace add https://github.com/backnotprop/plannotator
droid plugin install plannotator@plannotator
```

--------------------------------

### Configure runtime settings in config.json

Source: https://docs.plannotator.ai/open-source/reference/configuration

Example of all top-level runtime keys available in the configuration file. Only include keys that require modification from default values.

```json
{
  "displayName": "Avery",
  "diffOptions": {
    "diffStyle": "unified",
    "overflow": "wrap",
    "diffIndicators": "bars",
    "lineDiffType": "word-alt",
    "showLineNumbers": true,
    "showDiffBackground": true,
    "fontFamily": "monospace",
    "fontSize": "14px",
    "tabSize": 2,
    "hideWhitespace": false,
    "expandUnchanged": false,
    "defaultDiffType": "since-base",
    "lineBgIntensity": "normal"
  },
  "conventionalComments": true,
  "conventionalLabels": [
    { "label": "issue", "display": "Issue", "blocking": true },
    { "label": "suggestion", "display": "Suggestion", "blocking": false }
  ],
  "jina": true,
  "annotateHistory": true,
  "pfmReminder": false,
  "glimpse": true,
  "share": "enabled"
}
```

--------------------------------

### Run the Plannotator example agent

Source: https://docs.plannotator.ai/open-source/agents/kiro-cli

Executes the Plannotator agent within the Kiro CLI environment.

```bash
kiro-cli chat --agent plannotator
```

--------------------------------

### Annotated AI Coding Plan Example

Source: https://docs.plannotator.ai/templates/ai-coding-plan

A concrete example of the coding plan template applied to a specific task of rejecting expired export links.

```markdown
# Reject expired export links before object lookup

## Problem
Expired links still reach the storage lookup, which leaks timing and spends a request.

## Scope
- Validate expiry in the download route before calling the object store.
- Preserve the existing not-found response shape.

## Not in scope
- Changing link lifetime or token format.

## Implementation
1. Move expiry validation into the shared download gate.
2. Return the existing 404 response before storage access.
3. Add an integration test that proves the object store is not called.

## Risks and open questions
- Confirm clock-skew handling remains unchanged.

## Validation
- Run the route integration suite.
- Verify valid, expired, and malformed links return the documented responses.
```

--------------------------------

### Install Plannotator Pi extension

Source: https://docs.plannotator.ai/open-source/agents/pi

Requires Pi version 0.74.0 or later.

```bash
pi install npm:@plannotator/pi-extension
```

--------------------------------

### Install Plannotator Amp Plugin

Source: https://docs.plannotator.ai/open-source/agents/amp

Downloads the Plannotator plugin script to the global Amp plugins directory.

```bash
mkdir -p ~/.config/amp/plugins
curl -fsSL https://raw.githubusercontent.com/backnotprop/plannotator/main/apps/amp-plugin/plannotator.ts \
  -o ~/.config/amp/plugins/plannotator.ts
```

--------------------------------

### Start Pi in plan mode

Source: https://docs.plannotator.ai/open-source/agents/pi

Initiates plan mode, allowing the agent to generate and submit Markdown plans for approval.

```bash
pi --plan
```

--------------------------------

### Open a folder with approval gate

Source: https://docs.plannotator.ai/open-source/workflows/folders

Starts an annotation session that includes an approval action requirement.

```bash
plannotator annotate docs/ --gate
```

--------------------------------

### Initiate local review

Source: https://docs.plannotator.ai/open-source/workflows/local-changes

Commands to start a review session from the coding agent or the terminal.

```text
/plannotator-review
```

```bash
plannotator review
```

--------------------------------

### Pin a specific release version

Source: https://docs.plannotator.ai/open-source/start/installation

Ensures a repeatable installation by specifying a target version.

```bash
curl -fsSL https://plannotator.ai/install.sh | bash -s -- --version vX.Y.Z
```

```powershell
& ([scriptblock]::Create((irm https://plannotator.ai/install.ps1))) -Version vX.Y.Z
```

```bat
curl -fsSL https://plannotator.ai/install.cmd -o install.cmd
install.cmd --version vX.Y.Z
del install.cmd
```

```bat
install.cmd vX.Y.Z
```

--------------------------------

### Verify release with SLSA provenance

Source: https://docs.plannotator.ai/open-source/start/installation

Performs installation with optional SLSA provenance verification, requiring an authenticated GitHub CLI.

```bash
curl -fsSL https://plannotator.ai/install.sh | bash -s -- --version vX.Y.Z --verify-attestation
```

```powershell
& ([scriptblock]::Create((irm https://plannotator.ai/install.ps1))) -Version vX.Y.Z -VerifyAttestation
```

```bat
curl -fsSL https://plannotator.ai/install.cmd -o install.cmd
install.cmd --version vX.Y.Z --verify-attestation
del install.cmd
```

--------------------------------

### Product Requirements Document Example

Source: https://docs.plannotator.ai/templates/product-requirements-document

A template demonstrating the structure of a product requirements document using Markdown.

```markdown
# Expiring guest links product requirements document

Status: Draft
Owner: Sharing team
Last updated: 2026-07-18

## Answer
Workspace owners need optional expiry for guest links so temporary external
access ends without requiring them to remember a manual cleanup task.

## Problem and evidence
Three design partners share launch documents with contractors. They currently
revoke links by hand and cannot tell whether the intended access window ended.

## Goals
- G1. Let an owner choose an expiry when creating a guest link.
- G2. Make expired access predictable to the owner and guest.

## Non-goals
- Scheduled deletion of the document.
- Different expiry rules for individual files inside one shared folder.

## Users and journeys
### UJ-1: Owner shares a launch folder for one week
- User: A workspace owner working with an outside illustrator.
- Entry: The owner opens Share for the launch folder.
- Action: They choose guest-link access and a seven-day expiry.
- Outcome: The dialog shows the exact expiry before the link is copied.
- Failure: If the date is invalid, no link is created and the field explains why.

## Functional requirements
- FR-1. An owner can create a guest link with an expiry later than the current time.
  - Acceptance: Given an owned folder, when the owner chooses seven days, then
    the created link shows the same expiry in the Share dialog.
- FR-2. An expired guest link does not grant document access.
  - Acceptance: Given an expired link, when a guest opens it, then no document
    bytes or metadata are returned.

## Nonfunctional requirements
- NFR-1. Expired-link responses reveal no more document information than an
  unknown-link response.

## Constraints and dependencies
- Constraint: Existing non-expiring links keep their current behavior.
- Dependency: The access resolver must evaluate expiry before reading content.

## Success metrics
- SM-1. At least 80% of owners in the pilot who need temporary access choose an
  expiry instead of creating a permanent link.

## Counter-metrics
- CM-1. Failed guest opens caused by owners choosing the wrong date stay below 2%.

## Open questions
- OQ-1. Should owners receive a reminder before expiry? Owner: Product research.

## Acceptance criteria
- AC-1. Pilot owners can create, inspect, and revoke expiring links.
- AC-2. Security tests prove expired and unknown links have the same public shape.
```

--------------------------------

### Open Question Example

Source: https://docs.plannotator.ai/templates/software-rfc

An example of an open question that includes specific consequences to guide reviewer feedback.

```markdown
## Open questions
- Should anonymous links expire after inactivity, or remain valid until revoked?
  The choice affects recovery, abuse handling, and whether recipients can rely on an old link.
```

--------------------------------

### Open rendered HTML

Source: https://docs.plannotator.ai/open-source/workflows/html

Launches a local HTML file in the Plannotator annotation UI.

```bash
plannotator annotate report.html
```

--------------------------------

### Run additional entry points

Source: https://docs.plannotator.ai/open-source/start/quickstart

Use these commands for project reviews or to annotate the most recent assistant message.

```bash
plannotator review
plannotator annotate-last
```

--------------------------------

### Verify GitButler CLI installation

Source: https://docs.plannotator.ai/open-source/workflows/gitbutler

Check the installed version of the GitButler CLI to ensure it meets the minimum requirement of 0.21.0.

```bash
but --version
```

--------------------------------

### GET /api/external-annotations

Source: https://docs.plannotator.ai/open-source/reference/external-annotations

Retrieves all current external annotations.

```APIDOC
## GET /api/external-annotations

### Description
Retrieves the current list of annotations and the current version number.

### Method
GET

### Endpoint
/api/external-annotations

### Query Parameters
- **since** (integer) - Optional - If provided, returns 304 Not Modified if the version has not changed.
```

--------------------------------

### plannotator setup-goal

Source: https://docs.plannotator.ai/open-source/reference/cli

Opens goal interview questions or facts acceptance views.

```APIDOC
## plannotator setup-goal

### Description
Part of the goal workflow to manage interview questions or facts.

### Parameters
- **type** (string) - Required - Must be 'interview' or 'facts'.
- **bundle** (string) - Required - Path to a bundle.json file or '-' to read from stdin.
- **--json** (flag) - Optional - Output as JSON.
```

--------------------------------

### GET /api/config

Source: https://docs.plannotator.ai/open-source/reference/local-api

Retrieves settings shared with the server.

```APIDOC
## GET /api/config

### Description
Retrieves settings shared with the server.

### Method
GET

### Endpoint
/api/config
```

--------------------------------

### GET /api/external-annotations

Source: https://docs.plannotator.ai/open-source/reference/local-api

Retrieves the current external annotation snapshot.

```APIDOC
## GET /api/external-annotations

### Description
Retrieves the current external annotation snapshot.

### Method
GET

### Endpoint
/api/external-annotations
```

--------------------------------

### Access command-specific help

Source: https://docs.plannotator.ai/open-source/start/open-plannotator

Use these commands to view detailed help documentation for specific Plannotator operations before scripting workflows.

```bash
plannotator review --help
plannotator annotate --help
plannotator annotate-last --help
plannotator sessions --help
```

--------------------------------

### GET /api/external-annotations/stream

Source: https://docs.plannotator.ai/open-source/reference/local-api

Streams external annotation updates using server-sent events.

```APIDOC
## GET /api/external-annotations/stream

### Description
Streams external annotation updates with server-sent events.

### Method
GET

### Endpoint
/api/external-annotations/stream
```

--------------------------------

### GET /api/plan

Source: https://docs.plannotator.ai/open-source/reference/local-api

Retrieves the current plan or document payload along with session metadata.

```APIDOC
## GET /api/plan

### Description
Retrieves the current plan or document payload and session metadata.

### Method
GET

### Endpoint
/api/plan
```
Tokens:
Raw