### Install Plannotator CLI

Source: https://plannotator.ai/docs/getting-started/installation

Installs the Plannotator command-line interface for macOS, Linux, WSL, and Windows environments. This is a prerequisite for all agent integrations.

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

```powershell
irm https://plannotator.ai/install.ps1 | iex
```

```cmd
curl -fsSL https://plannotator.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
```

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

### Install Plannotator CLI

Source: https://plannotator.ai/docs/guides/opencode

Installs the Plannotator CLI tool, which is required to enable slash command functionality within the OpenCode environment.

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

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

### Install Plannotator Plugin

Source: https://plannotator.ai/docs/guides/troubleshooting

This command installs the Plannotator plugin, which is necessary for certain functionalities like the `ExitPlanMode` hook to trigger correctly. Ensure you have the correct version specified.

```bash
/plugin install plannotator@plannotator
```

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

### Configure OpenCode Plugin

Source: https://plannotator.ai/docs/getting-started/installation

Configures the Plannotator plugin within the opencode.json file and ensures slash commands are enabled via the installation script.

```json
{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@plannotator/opencode@latest"]
}
```

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

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

### Plannotator Plugin Installation Commands

Source: https://plannotator.ai/docs/guides/claude-code

These shell commands are used to install the Plannotator plugin from the marketplace within a Claude Code environment. A restart is required for the hooks to become active.

```shell
/plugin marketplace add backnotprop/plannotator
/plugin install plannotator@plannotator
```

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

### Build and Deploy Share Portal

Source: https://plannotator.ai/docs/guides/self-hosting

Commands to build the static share portal application using Bun and configuration examples for Nginx and AWS S3 deployment.

```bash
bun install
bun run build:portal
```

```nginx
server {
    listen 80;
    server_name plannotator.internal.example.com;
    root /var/www/plannotator;
    try_files $uri /index.html;
}
```

```bash
aws s3 sync apps/portal/dist/ s3://your-bucket/ --delete
```

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

### Execute Codex Commands

Source: https://plannotator.ai/docs/getting-started/installation

Direct usage of the Plannotator binary within the Codex environment for code reviews and file annotation.

```bash
!plannotator review
!plannotator annotate file.md
```

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

### Example Share URL Format

Source: https://plannotator.ai/docs/guides/sharing-and-collaboration

Displays the structure of a standard Plannotator share URL, where the plan data is encoded within the hash fragment.

```text
https://share.plannotator.ai/#eNqrVkrOz0nV...
```

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

### GET /api/plan

Source: https://plannotator.ai/docs/commands/plan-review

Retrieves the current plan and its origin source.

```APIDOC
## GET /api/plan

### Description
Fetches the current plan data and the origin of the request.

### Method
GET

### Endpoint
/api/plan

### Response
#### Success Response (200)
- **plan** (object) - The current plan content
- **origin** (string) - The source of the plan

#### Response Example
{
  "plan": { "steps": [] },
  "origin": "ClaudeCode"
}
```

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

### Override browser via CLI flags

Source: https://plannotator.ai/docs/getting-started/configuration

Provides examples of using the --browser flag to specify a browser for one-off Plannotator commands.

```bash
plannotator review --browser "Safari"
plannotator annotate plan.md --browser "Firefox"
```

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

### Verify Plannotator Installation

Source: https://plannotator.ai/docs/guides/troubleshooting

This command checks if the 'plannotator' executable is available in your system's PATH. This is a prerequisite for using Plannotator commands and ensuring hooks can be found and executed.

```bash
which plannotator
```

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

### Set Custom Browser for Plannotator AI

Source: https://plannotator.ai/docs/reference/environment-variables

Examples demonstrating how to set the PLANNOTATOR_BROWSER environment variable to specify a custom browser for opening the Plannotator UI. This includes examples for macOS, Linux, and custom scripts.

```shell
# macOS: open in Chrome
export PLANNOTATOR_BROWSER="Google Chrome"

# macOS: open in specific app
export PLANNOTATOR_BROWSER="/Applications/Firefox.app"

# Linux: open in Firefox
export PLANNOTATOR_BROWSER="/usr/bin/firefox"

# Custom script for remote URL handling
export PLANNOTATOR_BROWSER="/path/to/my-open-script.sh"
```

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

### Obsidian Saved Plan Format

Source: https://plannotator.ai/docs/guides/obsidian-integration

Example of the markdown file structure generated by Plannotator for Obsidian. It includes YAML frontmatter for metadata, a backlink for graph connectivity, and the plan content.

```markdown
---
created: 2026-01-02T14:30:00.000Z
source: plannotator
tags: [plannotator, my-project, authentication, typescript, sql]
---

[[Plannotator Plans]]

# Implementation Plan: User Authentication
...
```

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

### Configure Claude Code Plugin

Source: https://plannotator.ai/docs/getting-started/installation

Methods to integrate Plannotator into Claude Code via the plugin marketplace, manual settings configuration, or local development directory.

```bash
/plugin marketplace add backnotprop/plannotator
/plugin install plannotator@plannotator
```

```json
{
  "hooks": {
    "PermissionRequest": [
      {
        "matcher": "ExitPlanMode",
        "hooks": [
          {
            "type": "command",
            "command": "plannotator",
            "timeout": 345600
          }
        ]
      }
    ]
  }
}
```

```bash
claude --plugin-dir ./apps/hook
```

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

### Run Plannotator Annotate CLI Command

Source: https://plannotator.ai/docs/commands/annotate

Executes the plannotator annotate command with a specified markdown file path. This command starts a local server, opens the annotation UI in a browser, and blocks until the user submits feedback, which is then printed to stdout.

```bash
plannotator annotate path/to/file.md
```

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

### Configure Remote Mode via Environment Variables

Source: https://plannotator.ai/docs/guides/remote-and-devcontainers

Sets the required environment variables to enable remote mode and define a static port for Plannotator. This prevents automatic browser launching and ensures a consistent port for forwarding.

```bash
export PLANNOTATOR_REMOTE=1
export PLANNOTATOR_PORT=9999
```

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

### GET /api/diff

Source: https://plannotator.ai/docs/commands/code-review

Retrieves the current git diff information for the uncommitted changes in the session.

```APIDOC
## GET /api/diff

### Description
Returns the raw patch data, git reference, and origin information for the current uncommitted changes.

### Method
GET

### Endpoint
/api/diff

### Response
#### Success Response (200)
- **rawPatch** (string) - The git diff patch content
- **gitRef** (string) - The current git reference
- **origin** (string) - The origin context of the changes

#### Response Example
{
  "rawPatch": "--- a/file.txt\n+++ b/file.txt",
  "gitRef": "main",
  "origin": "local"
}
```

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

### Configure Docker for Plannotator

Source: https://plannotator.ai/docs/guides/remote-and-devcontainers

Exposes the Plannotator port and sets environment variables within a Docker container. Can be applied via Dockerfile instructions or runtime flags.

```dockerfile
ENV PLANNOTATOR_REMOTE=1
ENV PLANNOTATOR_PORT=9999
EXPOSE 9999
```

```bash
docker run -e PLANNOTATOR_REMOTE=1 -e PLANNOTATOR_PORT=9999 -p 9999:9999 your-image
```

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

### Set Custom Browser for Plannotator

Source: https://plannotator.ai/docs/guides/remote-and-devcontainers

Defines the browser or script used to open the Plannotator UI by setting the PLANNOTATOR_BROWSER environment variable. Supports platform-specific paths and executable names.

```bash
# macOS
export PLANNOTATOR_BROWSER="Google Chrome"

# Linux
export PLANNOTATOR_BROWSER="/usr/bin/firefox"

# Windows / WSL
export PLANNOTATOR_BROWSER="chrome.exe"
```

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

### Configure SSH Port Forwarding

Source: https://plannotator.ai/docs/guides/remote-and-devcontainers

Methods for forwarding traffic from a local machine to a remote server running Plannotator. Use the SSH config file for persistent settings or command-line flags for ad-hoc connections.

```ssh-config
Host your-server
    LocalForward 9999 localhost:9999
```

```bash
ssh -L 9999:localhost:9999 your-server
```

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

### GET /api/image

Source: https://plannotator.ai/docs/commands/code-review

Retrieves an image attachment by its file path.

```APIDOC
## GET /api/image

### Description
Serves an image file requested by the review UI.

### Method
GET

### Endpoint
/api/image

### Query Parameters
- **path** (string) - Required - The file system path to the image

### Response
#### Success Response (200)
- **image** (binary) - The image file content
```

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

### Run Paste Service Binary

Source: https://plannotator.ai/docs/guides/self-hosting

Instructions for executing the paste service binary on Unix-like systems to enable storage for large shared plans.

```bash
chmod +x plannotator-paste-*
./plannotator-paste-darwin-arm64
```

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

### Configure OpenCode Plugin

Source: https://plannotator.ai/docs/guides/opencode

Registers the Plannotator plugin by adding it to the opencode.json configuration file.

```json
{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@plannotator/opencode@latest"]
}
```

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

### Structured Markdown Feedback Format

Source: https://plannotator.ai/docs/commands/annotate

Illustrates the structured markdown format used for submitting annotations. This format includes sections for different types of feedback, such as deletions, replacements, and comments, allowing agents to process them effectively.

```markdown
# Plan Feedback

I've reviewed this plan and have 2 pieces of feedback:

## 1. Remove this
` ` `
the selected text
` ` `
> I don't want this in the plan.

## 2. Feedback on: "some highlighted text"
> This needs more detail about error handling.

---

```

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

### POST /api/approve

Source: https://plannotator.ai/docs/commands/plan-review

Approves the current plan and allows the agent to proceed with implementation.

```APIDOC
## POST /api/approve

### Description
Approves the plan. Optionally saves the plan to disk or integrated tools like Obsidian/Bear.

### Method
POST

### Endpoint
/api/approve

### Request Body
- **annotations** (array) - Optional list of annotations to include with approval (if supported by agent)

### Response
#### Success Response (200)
- **status** (string) - Confirmation message
```

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

### Configure Remote Environment

Source: https://plannotator.ai/docs/guides/opencode

Sets up environment variables and port forwarding for running Plannotator within a Devcontainer or Docker environment.

```json
{
  "containerEnv": {
    "PLANNOTATOR_REMOTE": "1",
    "PLANNOTATOR_PORT": "9999"
  },
  "forwardPorts": [9999]
}
```

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

### Manage Plannotator sessions via CLI

Source: https://plannotator.ai/docs/getting-started/configuration

Commands to list, reopen, or clean up active Plannotator sessions.

```bash
plannotator sessions              # list active sessions
plannotator sessions --open       # reopen most recent session
plannotator sessions --open 2     # reopen a specific session
plannotator sessions --clean      # remove stale session files
```

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

### Configure Component Environment Variables

Source: https://plannotator.ai/docs/guides/self-hosting

Setting environment variables to link the Plannotator hook with the custom Share Portal and Paste Service endpoints.

```bash
export PLANNOTATOR_SHARE_URL=https://your-portal.example.com
export PLANNOTATOR_PASTE_URL=https://your-paste.example.com
```

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

### POST /api/deny

Source: https://plannotator.ai/docs/commands/plan-review

Denies the current plan and sends structured feedback back to the agent.

```APIDOC
## POST /api/deny

### Description
Rejects the plan and sends structured feedback (annotations) to the agent for revision.

### Method
POST

### Endpoint
/api/deny

### Request Body
- **feedback** (array) - List of annotations (Deletion, Replacement, Comment, Insertion, Global comment)

### Response
#### Success Response (200)
- **status** (string) - Confirmation of feedback submission
```

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

### List and Reopen Plannotator Sessions

Source: https://plannotator.ai/docs/guides/troubleshooting

This command lists all active Plannotator sessions, including their mode, project, URL, and runtime. It also provides options to reopen the most recent session or a specific session by its number.

```bash
plannotator sessions
plannotator sessions --open
plannotator sessions --open 2
```

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

### POST /api/upload

Source: https://plannotator.ai/docs/commands/plan-review

Uploads an image attachment to be associated with plan annotations.

```APIDOC
## POST /api/upload

### Description
Uploads an image file to be used as an attachment in the plan review process.

### Method
POST

### Endpoint
/api/upload

### Request Body
- **file** (binary) - The image file to upload
- **name** (string) - Human-readable name for the image

### Response
#### Success Response (200)
- **path** (string) - The temporary path to the uploaded image
```

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

### Review Server API

Source: https://plannotator.ai/docs/reference/api-endpoints

Endpoints for handling code review diffs and feedback submission.

```APIDOC
## GET /api/diff

### Description
Returns the diff and session information for code review.

### Method
GET

### Endpoint
/api/diff

### Response
#### Success Response (200)
- **rawPatch** (string) - Git diff patch
- **gitRef** (string) - Git reference hash
- **origin** (string) - Source origin

### Response Example
{
  "rawPatch": "diff --git a/file.ts...",
  "gitRef": "abc1234",
  "origin": "claude-code"
}
```

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

### Paste Service API

Source: https://plannotator.ai/docs/reference/api-endpoints

Service for storing and retrieving compressed plan data for sharing.

```APIDOC
## POST /api/paste

### Description
Stores compressed plan data and returns a unique ID.

### Method
POST

### Endpoint
/api/paste

### Request Body
- **data** (string) - Compressed base64 string (max 512KB)

### Response
#### Success Response (201)
- **id** (string) - Unique identifier for the paste

### Response Example
{
  "id": "aBcDeFgH"
}
```

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

### Plan Server API Endpoints

Source: https://plannotator.ai/docs/reference/api-endpoints

Endpoints for managing plan review sessions, including approval, denial, and Obsidian/Bear integration. These endpoints handle session state and user feedback for implementation plans.

```json
GET /api/plan
{
  "plan": "# Implementation Plan...",
  "origin": "claude-code",
  "sharingEnabled": true,
  "shareBaseUrl": "https://share.plannotator.ai",
  "repoInfo": { "display": "my-project", "branch": "main" }
}
```

```json
POST /api/approve
{
  "permissionMode": "bypassPermissions",
  "agentSwitch": "claude-3-5-sonnet",
  "planSave": { "enabled": true, "customPath": null },
  "obsidian": { "vaultPath": "/path/to/vault", "folder": "plannotator", "plan": "..." },
  "bear": { "plan": "..." },
  "feedback": "optional annotations if present"
}
```

```json
POST /api/deny
{
  "feedback": "# Plan Feedback\n\nI've reviewed this plan...",
  "planSave": { "enabled": true }
}
```

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

### POST /api/upload

Source: https://plannotator.ai/docs/commands/code-review

Uploads an image attachment to the review session.

```APIDOC
## POST /api/upload

### Description
Uploads an image attachment associated with the current review feedback.

### Method
POST

### Endpoint
/api/upload

### Request Body
- **file** (binary) - Required - The image file to upload

### Response
#### Success Response (200)
- **url** (string) - The accessible URL for the uploaded image
```

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

### Plan Server API

Source: https://plannotator.ai/docs/reference/api-endpoints

Endpoints used during the plan review phase to manage session state, approvals, and integrations.

```APIDOC
## GET /api/plan

### Description
Retrieves the current plan and session information.

### Method
GET

### Endpoint
/api/plan

### Response
#### Success Response (200)
- **plan** (string) - The implementation plan content
- **origin** (string) - The source of the plan
- **sharingEnabled** (boolean) - Whether sharing is enabled
- **shareBaseUrl** (string) - Base URL for sharing
- **repoInfo** (object) - Repository display and branch info

### Response Example
{
  "plan": "# Implementation Plan...",
  "origin": "claude-code",
  "sharingEnabled": true,
  "shareBaseUrl": "https://share.plannotator.ai",
  "repoInfo": { "display": "my-project", "branch": "main" }
}
```

```APIDOC
## POST /api/approve

### Description
Approves the current plan and optionally configures integrations.

### Method
POST

### Endpoint
/api/approve

### Request Body
- **permissionMode** (string) - Mode of operation
- **agentSwitch** (string) - Agent to switch to
- **planSave** (object) - Save configuration
- **obsidian** (object) - Obsidian integration settings
- **bear** (object) - Bear integration settings
- **feedback** (string) - Optional annotations

### Request Example
{
  "permissionMode": "bypassPermissions",
  "agentSwitch": "claude-3-5-sonnet",
  "planSave": { "enabled": true, "customPath": null },
  "obsidian": { "vaultPath": "/path/to/vault", "folder": "plannotator", "plan": "..." },
  "bear": { "plan": "..." },
  "feedback": "optional annotations if present"
}
```

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

### POST /api/feedback

Source: https://plannotator.ai/docs/commands/code-review

Submits structured feedback or approval status from the review UI to the agent.

```APIDOC
## POST /api/feedback

### Description
Submits annotations or approval status (LGTM) back to the agent for processing.

### Method
POST

### Endpoint
/api/feedback

### Request Body
- **feedback** (object) - Structured feedback data including annotations or approval status

### Request Example
{
  "feedback": {
    "type": "comment",
    "content": "Please refactor this function",
    "file": "src/index.js",
    "line": 10
  }
}

### Response
#### Success Response (200)
- **status** (string) - Confirmation of feedback receipt
```

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

### Configure Claude Code hooks

Source: https://plannotator.ai/docs/getting-started/configuration

Defines the permission request hook in the Claude Code settings file to trigger the plannotator command when exiting plan mode.

```json
{
  "hooks": {
    "PermissionRequest": [
      {
        "matcher": "ExitPlanMode",
        "hooks": [
          {
            "type": "command",
            "command": "plannotator",
            "timeout": 345600
          }
        ]
      }
    ]
  }
}
```

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

### Review Server API Endpoints

Source: https://plannotator.ai/docs/reference/api-endpoints

Endpoints for code review functionality, allowing retrieval of diffs and submission of review feedback. Used primarily via the /plannotator-review route.

```json
GET /api/diff
{
  "rawPatch": "diff --git a/file.ts...",
  "gitRef": "abc1234",
  "origin": "claude-code"
}
```

```json
POST /api/feedback
{
  "feedback": "formatted review feedback",
  "annotations": [],
  "agentSwitch": "optional-agent-name"
}
```

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

### Plannotator Annotation API Endpoints

Source: https://plannotator.ai/docs/commands/annotate

This section details the available API endpoints for the Plannotator annotation feature, including their methods, purposes, and expected request/response formats.

```APIDOC
## GET /api/plan

### Description
Retrieves the plan content, annotation mode, and file path for the current annotation session.

### Method
GET

### Endpoint
/api/plan

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **plan** (string) - The markdown content of the plan.
- **mode** (string) - The current mode, expected to be "annotate".
- **filePath** (string) - The path to the file being annotated.

#### Response Example
```json
{
  "plan": "# My Plan\nThis is the plan content.",
  "mode": "annotate",
  "filePath": "path/to/file.md"
}
```

## POST /api/feedback

### Description
Submits the user's annotations and feedback for the current plan.

### Method
POST

### Endpoint
/api/feedback

### Parameters
#### Request Body
- **feedback** (string) - The structured markdown feedback containing annotations.

### Request Example
```json
{
  "feedback": "# Plan Feedback\n\nI have reviewed this plan and have 1 piece of feedback:\n\n## 1. Remove this\n` ` `\nthe selected text` ` `\n> I don't want this in the plan."
}
```

### Response
#### Success Response (200)
Indicates that the feedback was successfully submitted. The response body may be empty or contain a confirmation message.

#### Response Example
```json
{
  "message": "Feedback submitted successfully."
}
```

## GET /api/image

### Description
Serves an image file based on its path. This is used for displaying image attachments within the annotation UI.

### Method
GET

### Endpoint
/api/image

### Parameters
#### Query Parameters
- **path** (string) - Required - The path to the image file to be served.

### Request Example
```
GET /api/image?path=path/to/your/image.png
```

### Response
#### Success Response (200)
- The response body contains the image data.

#### Response Example
(Binary image data)

## POST /api/upload

### Description
Uploads an image attachment to be used within the annotation session.

### Method
POST

### Endpoint
/api/upload

### Parameters
#### Request Body
- **file** (file) - Required - The image file to upload.

### Request Example
(Multipart form data containing the image file)

### Response
#### Success Response (200)
- **url** (string) - The URL or path where the uploaded image can be accessed.

#### Response Example
```json
{
  "url": "/api/image?path=uploads/uploaded_image.png"
}
```
```

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

### Plannotator Annotate API Endpoints

Source: https://plannotator.ai/docs/commands/annotate

Defines the API endpoints for the Plannotator annotation server. These include endpoints for retrieving the plan, submitting feedback, serving images, and uploading image attachments.

```markdown
Endpoint| Method| Purpose  
---|---|---  
`/api/plan`| GET| Returns `{ plan, mode: "annotate", filePath }`  
`/api/feedback`| POST| Submit annotations  
`/api/image`| GET| Serve image by path  
`/api/upload`| POST| Upload image attachment  
```

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

### Annotate Server API Endpoints

Source: https://plannotator.ai/docs/reference/api-endpoints

Endpoints for file annotation mode, providing file content access and feedback submission. Used via the /plannotator-annotate route.

```json
GET /api/plan
{
  "plan": "# File contents...",
  "origin": "claude-code",
  "mode": "annotate",
  "filePath": "/absolute/path/to/file.md"
}
```

```json
POST /api/feedback
{
  "feedback": "formatted annotation feedback",
  "annotations": []
}
```

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

### Configure Sharing Environment Variable

Source: https://plannotator.ai/docs/guides/sharing-and-collaboration

Disables the sharing functionality within the Plannotator application by setting an environment variable. This removes UI elements related to sharing and importing reviews.

```bash
export PLANNOTATOR_SHARE=disabled
```

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

### Paste Service API Endpoints

Source: https://plannotator.ai/docs/reference/api-endpoints

A standalone service for storing and retrieving compressed plan data for URL sharing. Supports a 512KB payload limit and automatic TTL-based expiration.

```json
POST /api/paste
{
  "data": "<compressed base64 string>"
}
```

```json
GET /api/paste/:id
{
  "data": "<compressed base64 string>"
}
```

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

### Clean Up Stale Plannotator Sessions

Source: https://plannotator.ai/docs/guides/troubleshooting

This command forces the cleanup of stale Plannotator sessions that may result from crashed processes. This helps maintain a clean state of active sessions.

```bash
plannotator sessions --clean
```

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

### Plannotator Denial Response with Feedback for Claude Code Hook

Source: https://plannotator.ai/docs/guides/claude-code

This JSON object is returned to Claude Code when a user denies a plan and provides feedback via the Plannotator UI. The feedback message is included, allowing Claude Code to revise the plan.

```json
{"hookSpecificOutput":{"decision":{"behavior":"deny","message":"<feedback>"}}}
```

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

### Plannotator Approval Response for Claude Code Hook

Source: https://plannotator.ai/docs/guides/claude-code

This JSON object represents the response sent back to Claude Code when a user approves a plan through the Plannotator UI. It signals to Claude Code to proceed with the plan.

```json
{"hookSpecificOutput":{"decision":{"behavior":"allow"}}}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.