Instruction scope
Put each instruction as close as possible to the work it governs
Global
\~/.codex/AGENTS.md
Personal defaults that apply across repositories.
Repository
/AGENTS.md
Shared tooling, boundaries, and completion checks.
Package
/apps/web/AGENTS.md
Only the rules that change for this package.
A nested file should narrow or override broader guidance, not repeat it.
Choose the right surface
Instructions guide judgment. Tools enforce invariants.
Put in AGENTS.md
- Use the repository's focused test command.
- Read the API contract before changing routes.
- Ask before adding a production dependency.
Enforce elsewhere
- Code formatting belongs in a formatter.
- Forbidden imports belong in a linter.
- Protected paths belong in permissions or hooks.
Task structure
Two kinds of long-running work
Long-running batch
Many separate outputs
- Independent units
- No shared state required
- Failures stay local
Long-horizon task
One definition of done
- Dependent stages
- Decisions carry forward
- Recovery uses saved state
Eight-stage agent-native delivery loop
Each stage produces an inspectable input for the next. Learn feeds the next Signal, Intent, Context, or gate.
-
1. Signal
Capture a user need, incident, support pattern, obligation, or measured opportunity.
-
2. Intent
State the desired result, scope, constraints, owner, and observable acceptance criteria.
-
3. Context
Select current code, data, decisions, examples, conflicts, and freshness notes.
-
4. Plan
Order the changes, dependencies, risks, verification steps, and stop conditions.
-
5. Execute
Let agents and people make the bounded changes with least-privilege tools and checkpoints.
-
6. Prove
Run tests and scenarios, capture receipts, and expose failures instead of summarizing them away.
-
7. Judge and ship
Apply policy and risk-based judgment, then release, revise, reject, or hold.
-
8. Learn
Turn outcomes into better tests, context, instructions, templates, policies, and signals.
Context-window capacity
From 2,048 tokens to today's million-token frontier
2020 · GPT-3
2,048
tokens
2023 · Claude
100K
tokens
2024 · Gemini 1.5 Pro
1M
tokens
2026 · Fable 5 and GPT-5.6
1M+
tokens
Advertised capacity grew more than 500 times between GPT-3 and GPT-5.6. Useful attention did not become uniform by the same factor.
` elements may look like a comparison table while giving a screen reader none of the row and column relationships.
Ask for semantic headings, landmarks, tables, labels, alternative text, and native controls. W3C guidance explains why [headings must convey a meaningful hierarchy](https://www.w3.org/WAI/tips/writing/) and why [data tables need programmatic header relationships](https://www.w3.org/WAI/tutorials/tables/). Interactive pages also need a complete keyboard path; native HTML controls provide behavior that custom clickable elements do not get for free.
Test the result at the viewport sizes the team supports, with keyboard-only navigation, and with the team’s normal accessibility checks. If the page cannot provide an equivalent linear explanation, it is a poor replacement for Markdown.
### Presentation quality and accuracy
Agents can create crowded dashboards, ornamental diagrams, inconsistent controls, and charts that exaggerate weak differences. Review the information design, not only the prose.
Verify every claim against the repository, tests, or source data. An elegant architecture map can be wrong, and polished presentation can make a weak claim more persuasive.
## A practical request for an HTML artifact
When HTML is justified, give the coding agent a small contract:
* state the review question the page must help answer;
* make one self-contained, unminified file;
* identify source files, data, and the repository revision;
* use semantic HTML and a complete keyboard path;
* avoid external network requests and third-party scripts;
* keep important conclusions available in a linear text view;
* export any user-made choice as Markdown, JSON, or a copyable prompt;
* label assumptions, missing evidence, and generated examples;
* exclude secrets and customer data.
Then include the artifact in the agent’s completion package rather than leaving it in a temporary chat. The companion guide to [AI coding agent handoffs](/learn/code-context/ai-coding-agent-handoff) explains what else the team should receive after implementation.
## Limitations
No format guarantees understanding. A short Markdown plan can omit the decisive constraint. An interactive HTML explainer can guide reviewers toward the agent’s preferred conclusion. Either can become stale after the implementation changes.
Some teams cannot host or share active HTML safely. Markdown plus committed SVG, screenshots, or reports may provide most of the value with fewer assumptions.
Choose the format as one part of the review path. Teams still need to connect the requested change, approved context, implementation, validation evidence, and final decision. See [how teams understand AI-generated code before shipping it](/learn/code-context/understand-ai-generated-code-before-shipping) for that complete workflow.
## Frequently asked questions
### Is HTML better than Markdown for AI coding agents?
Not generally. Markdown is better for most editable plans, decisions, and handoffs. HTML is better when the task depends on spatial comparison, visualization, interaction, or direct manipulation.
### Should an implementation plan be HTML or Markdown?
Use Markdown for the authoritative plan. Add an HTML explainer when a system map, prototype, or multi-option comparison materially helps reviewers test the proposal. Link the two and identify which file carries the approved decision.
### Can I attach an HTML artifact to a GitHub pull request?
Yes. GitHub supports HTML file attachments in pull-request conversations. Repository visibility controls who can access the uploaded file. Treat attached HTML as untrusted active content and use a safe viewer rather than opening it with privileged application access.
### How do I make an AI-generated HTML artifact safe to review?
Remove secrets, external dependencies, and unnecessary scripts. Render it in an isolated sandbox with a restrictive Content Security Policy. Do not give it access to review-application credentials, local development secrets, or a trusted same-origin context.
### How do I keep an HTML artifact reviewable in Git?
Keep it unminified and deterministically formatted, avoid unrelated style churn, separate content data from presentation where practical, and export durable decisions to a simpler text format. Always record which code revision and source data the page represents.
## Which format should an agent use?
Use Markdown when the team needs to **read, edit, diff, and preserve a document**. Use HTML when the team needs to **compare, explore, manipulate, or see relationships**.
When a workflow needs both, Markdown holds the durable decision while HTML provides a focused interface for understanding it.
Open documents and folders in Plannotator, or use the HTML guide when the rendered page is part of the review.
*Last reviewed July 29, 2026. Maintained by the Plannotator project.*
# What Should an AI Coding Agent Hand Back After It Changes Code?
Source: https://docs.plannotator.ai/learn/code-context/ai-coding-agent-handoff
A practical team handoff contract for AI-generated code: the request, exact revision, change map, validation evidence, risks, and documentation impact.
After changing code, an AI coding agent should hand back a compact index to the request, patch, and evidence. Use a short handoff for a reversible edit and add evidence when the change affects more systems or carries more risk.
For a small, reversible edit, those facts may fit in six lines. A cross-cutting authorization change may need an approved plan, migration output, screenshots, and rollout notes. Choose evidence based on the consequences of the change, not the amount of AI used to produce it.
![An AI coding agent hands a team one versioned evidence folio containing the code diff, decision context, validation, risks, review artifact, and follow-up work.]()
![An AI coding agent hands a team one versioned evidence folio containing the code diff, decision context, validation, risks, review artifact, and follow-up work.]()
## What the patch and summary leave out
The Git diff is the implementation record. It does not say which request authorized the work, which paths the agent exercised, which assumptions remain unresolved, or whether a polished screenshot belongs to the current revision.
A prose summary helps a reviewer get oriented, but it is still an interpretation of the patch. GitHub recommends that pull request authors provide the purpose, an overview, links to context, and guidance about where to begin reviewing. Authors should also review, build, and test their changes before requesting review. See [GitHub's guidance for making changes easier to review](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/getting-started/helping-others-review-your-changes).
GitHub and Codex already expose parts of this record. GitHub lets reviewers query a Copilot-created pull request's session logs to ask what changed, what was validated, and why. OpenAI's Codex reports citations, terminal logs, and test results. See [GitHub's pull request exploration guide](https://docs.github.com/en/copilot/tutorials/explore-pull-requests) and [OpenAI's introduction to Codex](https://openai.com/index/introducing-codex/). Both vendors still instruct users to review agent-created code before integration. GitHub says to [review Copilot's pull requests thoroughly](https://docs.github.com/en/copilot/how-tos/copilot-on-github/use-copilot-agents/review-copilot-output).
Use the handoff as a stable index into the request, code, and evidence a reviewer needs to decide. The diff, CI results, and agent logs remain the source records.
## The compact agent handoff contract
Use six required fields. Add conditional evidence only when it applies.
| Field | What the agent must provide |
| - | - |
| **Request** | The issue, request, or [reviewed plan](/learn/code-context/approve-ai-coding-plan-before-execution) that authorized the work, including its revision or date when relevant. State material deviations. |
| **Revision** | The repository, branch or pull request, and exact head commit SHA being handed over. |
| **Change map** | The user-visible behavior and affected components, with a suggested review order for a multi-file change. |
| **Validation** | The exact checks run, their results, and anything skipped, unavailable, or still failing. |
| **Open questions and risks** | Unresolved decisions, assumptions, known failure modes, and any follow-up that must happen before or after merge. Say **none identified** when appropriate; do not omit the field. |
| **Documentation impact** | The maintained product or technical documents updated by the change, or a brief reason that no durable documentation changed. |
Add these fields only when they apply:
* **Review artifacts:** screenshots, recordings, HTML walkthroughs, traces, benchmark results, or migration evidence that make behavior inspectable. Explain which claim each artifact supports.
* **Data and rollout:** schema changes, compatibility window, backfill, deployment order, feature flag, rollback trigger, and operator ownership.
* **Security and privacy:** changed trust boundaries, permissions, secrets, customer data, threat assumptions, and the responsible reviewer.
* **Follow-up work:** deferred cleanup or monitoring with an owner and a concrete issue, not vague “future improvements.”
Use this template:
```text theme={null}
Request:
Revision:
Changed:
Validated:
Open questions / risks:
Documentation:
Conditional evidence:
Rollout / rollback:
Follow-up:
```
Put the fields in a pull request template if that makes them easier to complete. The agent can populate them, but the person or team presenting the change for review owns their accuracy.
## Make validation evidence specific and revision-bound
“Tests pass” is not useful evidence without scope. A reviewer needs to know whether the agent ran one targeted unit test, the repository's complete test suite, a browser flow, or only a type-check. Record the command or named CI job and its result:
* `pnpm test --filter authorization`: 42 passed;
* `pnpm typecheck`: passed;
* checkout browser flow at mobile and desktop widths: passed, screenshots attached;
* production-like migration rehearsal: not run; staging database unavailable.
Tie that evidence to the handed-off SHA. GitHub status checks are reported against commits, and its Checks view can display results for different commits in the same pull request. See [GitHub's status-check documentation](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/about-status-checks).
When the agent pushes another commit, the code under review changes. The handoff and any manually produced evidence may need to change with it. A [revision diff](/learn/code-review/what-is-a-revision-diff) helps a returning reviewer isolate what moved since the last checkpoint instead of assuming an earlier test report or screenshot still applies.
Do not paste every successful log into the pull request. Link to full CI output and surface the evidence that changes the decision. State plainly when a check failed, was skipped, or cannot reproduce the target environment.
## Use artifacts to show behavior the diff cannot show
Visual and operational changes often need more than textual test output. A UI change may need before-and-after screenshots and a short recording. A parser change may need a table of difficult inputs and outputs. A data migration may need rehearsal counts, timing, and rejected-row samples.
These [code review artifacts](/learn/code-review/what-are-code-review-artifacts) provide evidence beside the patch. Claude Code, for example, can publish session artifacts such as pull request walkthroughs, system explainers, and release checklists. Anthropic describes them as pages built from the codebase, connected tools, and session context. See [Anthropic's Claude Code artifacts announcement](https://claude.com/blog/artifacts-in-claude-code).
An artifact is not proof merely because it looks complete. Identify its source, revision, and supported claim. Reviewers must still inspect the underlying behavior and code. For format guidance, read [When Should AI Coding Agents Produce HTML Instead of Markdown?](/learn/code-context/ai-agent-html-vs-markdown).
## Small-change fast path
Suppose an agent fixes an off-by-one error in pagination, changes one implementation file, and adds one regression test. No API contract, customer-visible workflow, or maintained architecture document changes.
The handoff can stay compact:
> **Request:** Fix issue #184: page 2 repeats the final item from page 1.
> **Revision:** PR #219 at `71be993`.
> **Changed:** Corrected the cursor offset in `pagination.ts`; added the boundary case in `pagination.test.ts`.
> **Validated:** Targeted test file, 18 passed; type-check passed.
> **Open questions / risks:** None identified.
> **Documentation:** None; the public behavior now matches the existing API documentation. These six lines identify the request, code, and validation claim. A formal planning package or long session transcript would not help the reviewer decide whether to merge this fix. ## Use the full handoff for a cross-cutting change Now suppose a team replaces a synchronous customer-data export endpoint with a queued export service. The implementation touches the public API, a jobs table, a background worker, encrypted object storage, download authorization, the account UI, audit events, retention cleanup, and operator documentation. A useful handoff might say: * **Request:** Export-service plan version 6, approved by product, data, and security. The agent deviated from emailing export files after the security review required a short-lived authenticated download. * **Revision:** Pull request head `c4a912e` in the API repository plus `7b21d0a` in the web repository. * **Change map:** Read the export state machine first, then the jobs migration, worker, object-storage adapter, download authorization, account UI, and retention cleanup. * **Validation:** Unit and integration suites passed; the migration was rehearsed against a sanitized production-shape snapshot; expired and cross-organization download links were rejected; the browser flow passed with screenshots attached. Queue-saturation testing was not run because the staging capacity was unavailable. * **Open questions and risks:** Download links expire after 24 hours. Rollback disables new export requests but allows already queued jobs to finish. Security review and an alert on failed retention cleanup remain required before launch. * **Documentation:** Updated `PRODUCT.md` with the customer-visible lifecycle, `TECH.md` with the storage and authorization boundaries, and the operator runbook with rollout, rollback, queue recovery, and retention steps. Several teams must verify different claims and operate the export service, so the handoff needs more evidence. It remains a map, not an agent transcript. The project's issue, plan, or review system records what was authorized; the handoff records what the agent produced and any deviations. Plannotator's [local plan review loop](/learn/code-context/approve-ai-coding-plan-before-execution) can help refine the plan before that external record is made. After merge, durable decisions should enter [living codebase documentation](/learn/code-context/living-documentation-for-ai-agents). For the complete path from request through team decision, implementation evidence, and shipping, read [How Teams Understand AI-Generated Code Before Shipping It](/learn/code-context/understand-ai-generated-code-before-shipping). ## What a handoff cannot establish * It is authored by the same agent that may have misunderstood the request or missed a failure. Treat its claims as review leads, not independent verification. * Passing tests demonstrate only the paths and assertions they cover. They do not prove the change satisfies the product decision. * A commit SHA identifies code, not every external dependency, service response, or mutable artifact used during validation. * Logs and artifacts can expose secrets or customer data. Redact and retain them according to the repository's access rules. * A large handoff cannot rescue a pull request that is too broad to review. Split the implementation when reviewers cannot form a reliable mental model. Anthropic's long-running agent harnesses used structured updates alongside Git history so the next session could resume the work. A team handoff uses the same practice to prepare an implementation for review. See [Anthropic's long-running agent harness research](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents). ## Frequently asked questions ### What should an AI coding agent include in a pull request? Include the authorizing request, exact head revision, a change map, validation commands and results, unresolved questions and risks, and documentation impact. Add screenshots, HTML, migration evidence, rollout instructions, or security notes only when the change requires them. ### How detailed should an AI coding agent handoff be? Use the smallest handoff that lets another engineer verify the work without reconstructing the agent session. A local fix may need six short lines; a cross-service migration needs more evidence. ### Should the agent include every command and log? No. Include decision-relevant commands and results, note anything skipped or failing, and link to complete logs when useful. Large pasted logs hide signal and can leak sensitive data. ### How can a reviewer verify an agent's handoff? Confirm the request and revision, inspect the diff in the suggested order, open the linked evidence, check that CI belongs to the current commit, and rerun consequential validation when appropriate. Resolve discrepancies against the code and executable behavior, not the agent's prose. ### Who owns the accuracy of an AI coding agent handoff? The person or team delegating the change owns the handoff presented for review. The agent can draft and update it, but it should not certify its own work as correct or ready to merge. ## Check the handoff A reviewer should be able to identify the exact request and revision, inspect the supporting evidence, see what remains uncertain, and find any documentation impact without reopening the private agent session.
Open the current local changes in Plannotator and compare the handoff with the actual diff and validation evidence.
*Last reviewed July 18, 2026. Maintained by the Plannotator project.*
# How to Approve AI Coding Plans Before Execution
Source: https://docs.plannotator.ai/learn/code-context/approve-ai-coding-plan-before-execution
Review an AI coding plan in local open-source Plannotator, send precise feedback, compare revisions with Plan Diff, and approve only the current plan.
Approve an AI coding plan only when it states the intended outcome, boundaries, important implementation choices, risks, and validation well enough for the agent to proceed. Open-source Plannotator can show a supported coding agent's plan in your browser and return **Approve** or **Send Feedback** to that local session. Some agents wait for your decision. On Claude Code 2.1.287 or later and on Pi, the agent ends its turn and your decision arrives later as a message.
**Approve** answers only the active local agent session. It does not record reviewer identity or authorization.
![A conceptual software workflow moves from a change request through a team decision and planning context to agent execution, verified code, and maintained documentation.]()
![A conceptual software workflow moves from a change request through a team decision and planning context to agent execution, verified code, and maintained documentation.]()
Keep a shared authorizing record in Git, an issue, a pull request, or another document system when the decision must be available to the team.
## Decide how much review the change deserves
| Change | Useful planning record |
| - | - |
| Small, reversible correction | A short plan in the agent conversation may be enough |
| Cross-cutting feature | A reviewed coding plan with scope, dependencies, and validation |
| Durable behavior or protocol | A technical specification plus a current implementation plan |
| Significant architecture choice | An ADR linked from the specification or plan |
| Broad proposal needing discussion | An RFC before implementation planning |
Start with the [AI coding plan template](/templates/ai-coding-plan). If the document needs to stay current after implementation, use the [technical specification template](/templates/technical-specification) as a separate maintained record.
If the request still contains major unknowns, use the [iterative planning workflow](/learn/planning/how-to-plan-with-ai-coding-agents) to explore the codebase, interview the human, and test the riskiest assumption before submitting a plan for approval.
## What happens during plan review
For agents that support automatic plan review, the plan-mode hook starts Plannotator and opens the proposed Markdown in your browser. You can:
* select text and add a comment;
* mark text for deletion;
* edit the Markdown directly;
* add overall feedback;
* approve the current plan; or
* send feedback to the agent.
Choose **Approve** when the current plan needs no changes. Plannotator returns an approval result to the agent session so the agent can continue.
Choose **Send Feedback** when you added comments, deletions, edits, or overall feedback. Plannotator formats that feedback and returns it to the agent. The agent can then revise and submit another plan.
Approving with unsent annotations does not turn those annotations into implementation instructions. Use **Send Feedback** when you want the agent to act on them.
## Review the plan before you approve it
A useful plan gives you enough information to find a wrong assumption before the agent changes code. Check the parts that could change the implementation:
* intended behavior and explicit non-goals;
* affected files, services, data, or APIs;
* security and compatibility constraints;
* migration, rollout, and rollback steps where relevant;
* tests and other evidence the agent should produce;
* unresolved questions that require a decision.
Small, reversible changes may need only a short plan. Security, data, migration, infrastructure, and public API changes usually need more detail because an incorrect direction is expensive to undo.
The Rust project's [RFC process](https://rust-lang.github.io/rfcs/) is a useful source of review questions for consequential design changes. Warp's public [APP-2527 specification](https://github.com/warpdotdev/warp/tree/master/specs/APP-2527) shows one way to separate product behavior from technical implementation. You do not need to copy either structure. Use only the sections that help you verify the proposed work.
## Use Plan Diff for revised plans
Plannotator saves each arriving plan to local version history before opening the review. When the agent submits a revision, select the `+N/-M` badge to compare it with the previous version.
Use the rendered view to inspect changed sections in context. Use the raw view when the exact Markdown matters. The Version Browser lets you choose an older stored version as the comparison base.
Before approving a revision, check that it:
1. addresses the feedback you sent;
2. keeps decisions that were already correct;
3. does not introduce a new unsupported assumption; and
4. still describes the version the agent is about to implement.
If other people need to review the plan or cite the decision later, commit the exact Markdown to Git or review it in the issue, pull request, or document system your project already uses.
The [Workspaces plan and technical-decision workflow](https://help.plannotator.ai/workspaces/review-plans-and-technical-decisions) covers the separate job of sharing one plan or specification with several people and agents. Its versions record document change, not named approval.
## Keep the reviewed plan tied to the implementation
An agent may discover that the plan cannot work as written. Ask it to stop and return to plan review when new evidence changes a consequential decision, such as:
* an incompatible API client;
* an unsafe migration path;
* a missing authorization boundary;
* a requirement that conflicts with current behavior; or
* validation that cannot demonstrate the promised result.
Review the revised plan with Plan Diff, then approve the current version or send another round of feedback. Do not rely on an earlier approval after the plan has materially changed.
Plan review also does not replace code review. After implementation, inspect the actual diff, run the relevant checks, and compare the result with the plan.
## A practical review loop
1. Let the supported agent enter plan mode and open Plannotator.
2. Read the proposed behavior, scope, constraints, and validation steps.
3. Add comments or edit the plan where it is incomplete or incorrect.
4. Select **Send Feedback**.
5. When the agent resubmits, open Plan Diff and inspect the changes.
6. Select **Approve** only when the current plan is ready for implementation.
7. Review the resulting code separately.
See supported agents, plan history, feedback controls, and Plan Diff behavior.
## Frequently asked questions
### What happens when the plan changes after I approve it?
Treat the changed plan as a new proposal. Review its diff and decide again before the agent implements the new direction.
### Can the agent review its own plan?
The agent can critique the plan, investigate the repository, and surface uncertainty. You still choose **Approve** or **Send Feedback** in the local review.
### Should every task use plan review?
No. Use it when reviewing the direction will reduce meaningful implementation risk. A small, reversible edit may be faster to verify in the code diff.
*Last reviewed July 18, 2026. Maintained by the Plannotator project.*
# HTML Wireframes and Prototypes for Coding Agents
Source: https://docs.plannotator.ai/learn/code-context/html-wireframes-and-prototypes-for-coding-agents
Design the interface yourself and iterate in the browser before anyone writes production code. Use a coding agent and one HTML file to test structure, visual direction, and interaction.
You do not have to wait for a designer or a Figma pass to make the idea visible. A coding agent can turn the brief into an HTML interface, revise it with you in the browser, and keep iterating until the team knows what to build.
Plannotator packages this workflow for coding agents in [Effective HTML](https://github.com/plannotator/effective-html), its open-source skill repository.
An **HTML wireframe** is a low-fidelity web page used to test structure, content, and task order. Make one when a coding agent and reviewer still need to decide what belongs on the screen.
An **HTML mockup** applies visual hierarchy, spacing, color, typography, and responsive layout to the agreed structure. Make one when the team needs to judge appearance before it spends time on behavior.
An **HTML prototype** adds the smallest useful interactions and state changes. Make one when reviewers need to click through a flow, test a transition, or see how the interface responds to input.
![The same release-readiness interface progresses from a restrained HTML wireframe through a styled mockup to an interactive prototype whose state changes from blocked to ready.]()
![The same release-readiness interface progresses from a restrained HTML wireframe through a styled mockup to an interactive prototype whose state changes from blocked to ready.]()
## Design the interface before you code it
The browser becomes the design surface. Ask the agent to move a section, change the hierarchy, try another visual direction, or wire the critical interaction. You see each revision immediately, while changing course still means editing one HTML file.
For a bounded screen or flow, one HTML file can take the place of separate sketch, static mockup, and clickable-demo passes. Reviewers work against the actual hierarchy and behavior in the browser instead of waiting for the idea to be rebuilt in another tool. Move into a dedicated design tool when the work needs its component libraries, vector editing, multiplayer workflows, or formal design handoff.
Judge efficiency across the whole loop. HTML may use more tokens than a Markdown plan. It can still save tokens overall if the visible artifact prevents an implementation pass on the wrong structure or behavior. Stop when the artifact answers the current question. Many tasks need only a wireframe or a focused prototype.
Anthropic engineer Thariq Shihipar describes this working style in [The unreasonable effectiveness of HTML](https://claude.com/blog/using-claude-code-the-unreasonable-effectiveness-of-html). He uses HTML to compare options, expand ideas into mockups, and then write an implementation plan. The format is valuable because it keeps the human engaged with the choices instead of handing those choices to the agent.
[Geoffrey Litt argues that understanding is now the bottleneck](https://www.geoffreylitt.com/2026/07/02/understanding-is-the-new-bottleneck.html) when agents can produce code faster than people can follow it. He uses explainers, interactive figures, and shared Notion pages to help people build intuition and participate in the next decision. An HTML wireframe or prototype serves the same purpose before implementation: it gives a person, a team, and an agent one visible object to question together.
## How do an HTML wireframe, mockup, and prototype differ?
| Review question | HTML wireframe | HTML mockup | HTML prototype |
| - | - | - | - |
| **Purpose** | Decide what the interface contains and how the task is ordered | Decide how the agreed structure should look and respond to screen size | Test the important behavior, states, and transitions |
| **Fidelity** | Low. Real labels and content, restrained presentation | Medium to high. Representative visual system and responsive layout | Only as high as the tested flow requires |
| **Interaction** | Links or controls may be inert | Usually static, even if controls look finished | Working controls for the chosen scenario |
| **Time and cost** | Lowest. Usually the fastest way to test a bounded screen | More visual iteration and breakpoint work, but no production components yet | More state logic and testing, but only for the chosen flow |
| **Best review questions** | Is anything missing? Is the order right? Is the primary task clear? | Is the hierarchy clear? Is the layout readable and consistent? | Can a user complete the task? Are state changes and recovery paths clear? |
| **Do not decide yet** | Final color, typography, animation, component implementation | Production data flow, authorization, performance, final edge-case behavior | Production architecture or whether the shipped code passes its real checks |
Use only the stages that answer an open question. A team may stop at a wireframe because the structure is settled. It may jump from a sketch to a prototype when behavior is the main uncertainty.
## Start with one product brief
The brief is the first alignment boundary. Keep the same brief through all three stages. Changing the problem while increasing fidelity makes it hard to tell whether feedback concerns the product or the presentation.
This guide uses a fictional release-readiness page for Atlas Mobile 4.8:
* A release manager must decide whether one release candidate can go to production.
* The page must show the commit, owner, four required checks, supporting evidence, open risks, reviewer notes, and current decision.
* The page starts blocked because the iOS smoke test failed.
* A passing rerun changes the release from blocked to ready and enables the release action.
* The prototype must not start a real deployment, authenticate a user, or load live build data.
The exercise stops at the release decision. The agent does not need to invent authentication, live data, or deployment behavior to answer it.
## Keep the artifact structure visible
Store the brief, state model, HTML, and review notes together:
```text theme={null}
html-wireframes-prototypes/
├── brief.md
├── release-readiness.html
├── states.md
└── review-notes.md
```
The example uses one self-contained HTML file with `wireframe`, `mockup`, and `prototype` modes. Separate files also work, but shared content can drift unless the agent updates each copy deliberately.
The supporting files have distinct jobs:
* `brief.md` fixes the user, task, required information, behavior, and non-goals.
* `release-readiness.html` contains the visible artifact and the prototype logic.
* `states.md` names each state, its trigger, visible result, and available action.
* `review-notes.md` separates accepted decisions from open questions.
## Stage 1: make the HTML wireframe
Use real headings, labels, controls, and representative content. Low fidelity does not mean unlabeled gray boxes. Reviewers need enough detail to judge whether the screen supports the task.
The release wireframe includes:
* a header with the release candidate, commit, and owner;
* a summary of checks passed, open risks, and release state;
* four named checks with evidence;
* a reviewer-notes area;
* a blocked decision and its next action.
It leaves out the final palette, shadows, rounded corners, animation, and production components. The primary question is whether a release manager can find the information needed to decide.
The focused view below exposes grouping, measurement, and hierarchy without suggesting that the surface design is finished.
![A low-fidelity release-readiness wireframe fills the frame while an offset tracing-paper layer isolates its header, summary blocks, evidence rows, and reviewer notes column. Measurement marks and sparse review strokes show that the structure is under review.]()
![A low-fidelity release-readiness wireframe fills the frame while an offset tracing-paper layer isolates its header, summary blocks, evidence rows, and reviewer notes column. Measurement marks and sparse review strokes show that the structure is under review.]()
Give the agent a bounded instruction:
```text theme={null}
Read brief.md and states.md. Create one self-contained, responsive HTML wireframe.
Use semantic headings, sections, lists, and native controls. Use real copy from
the brief. Keep the presentation grayscale and restrained. Show the blocked
state, but do not implement interactions yet.
Review target: content, information hierarchy, task order, and missing states.
Do not choose final colors, typography, animation, or component architecture.
```
Review the wireframe with questions that can change its structure:
* Does the page answer “Can this build go to production?” without another screen?
* Are machine results and reviewer notes visibly separate?
* Is the failed check specific enough to investigate?
* Is the next action clear while release remains blocked?
* What information could be removed without weakening the decision?
If the structure is still open, ask the agent for two or three materially different wireframes in one HTML file. Compare them in one review, choose one, and discard the rest. This is faster than styling the first plausible idea and learning later that its structure was wrong.
## Stage 2: turn it into an HTML mockup
Freeze the structure before styling it. The mockup should preserve the same information, order, and states unless the visual pass exposes a structural problem.
For the release example, the mockup adds:
* Plannotator-adjacent violet, blue, and orange accents;
* a stronger visual distinction between evidence, notes, and the decision;
* readable spacing and type hierarchy;
* a compact desktop summary that becomes a single column on narrow screens;
* visible pass, fail, blocked, and ready colors with text labels.
Keep the release logic out of the mockup. Its controls can remain inert because the review question is visual.
```text theme={null}
Use the approved wireframe as the source. Preserve its content, DOM order,
labels, and states.
Apply the product's existing color, type, spacing, border, and focus tokens.
Create a responsive layout for wide desktop and narrow mobile widths. Keep pass,
fail, blocked, and ready understandable without color alone.
Review target: hierarchy, scanability, contrast, responsive behavior, and fit
with the existing design system. Do not add new product behavior.
```
Compare the mockup with the wireframe rather than reviewing it in isolation. Any missing field or changed task order should be an explicit decision, not a side effect of styling.
This is the cheapest point to reject a visual direction. The next pass should change CSS and layout, not rewrite production components.
## Stage 3: make the interactive HTML prototype
Add only the behavior needed to answer the unresolved interaction question. For Atlas Mobile, that question is: what changes after a reviewer records a passing smoke-test rerun?
The prototype implements one flow:
1. The page starts with 3 of 4 checks passed and the release blocked.
2. The reviewer records a passing iOS smoke test.
3. The failed check changes to pass.
4. The summary changes to 4 of 4.
5. The decision announces that the release is ready.
6. The production-release action becomes available.
Keep authorization, live data, persistence, audit history, real network requests, and deployment behavior out of this prototype. The local save flow simulates an evidence-service failure and retry so reviewers can test error feedback and recovery without calling a real service.
Once reviewers accept the transition, the artifact becomes a concrete reference for implementation. The coding agent can inspect the state names, visible results, and accepted interaction instead of inferring them again from prose.
The focused prototype view keeps one interaction path in frame: the blocked state, the action and its keyboard focus, the visible feedback, and the ready result.
![A blocked release-readiness screen with one failed and three passed checks connects through a focused action to a raised ready-state overlay where all four checks pass. One orange trace links the trigger, visible feedback, and enabled result.]()
![A blocked release-readiness screen with one failed and three passed checks connects through a focused action to a raised ready-state overlay where all four checks pass. One orange trace links the trigger, visible feedback, and enabled result.]()
```text theme={null}
Preserve the approved mockup. Implement only the blocked-to-ready flow in
states.md.
Use native buttons and a complete keyboard path. Announce the decision change
through an aria-live status. Keep the release action disabled until all four
checks pass. Make the final action explain that this is a prototype rather than
starting a real release.
Review target: trigger, state transition, feedback, focus behavior, keyboard
operation, and the point where the real system would take over.
```
W3C's [WCAG 2.2 keyboard requirements](https://www.w3.org/TR/WCAG22/#keyboard-accessible) apply to prototypes too. A clickable mockup that cannot be operated from a keyboard may hide a problem the production team later has to undo.
## Why does HTML make this loop faster?
HTML combines the plan and the visible result in one inspectable file. A static picture can show appearance. A prose plan can describe behavior. HTML can show both, then let a reviewer test the transition that connects them.
That shortens the distance between an idea, evidence, and a revision:
* **Inspectable:** Browser developer tools expose the DOM, CSS, dimensions, roles, names, and focus behavior. Chrome documents how its [Inspect mode reveals element and accessibility properties](https://developer.chrome.com/docs/devtools/inspect-mode).
* **Editable:** Reviewers or agents can change the source with ordinary text tools and track those changes in Git.
* **Responsive:** One artifact can use flexible layout and media queries instead of maintaining separate desktop and mobile pictures. MDN explains the relevant [responsive-design techniques](https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/CSS_layout/Responsive_Design).
* **Runnable:** A browser can exercise controls, state changes, validation, and focus order without building the production application.
* **Reviewable:** A team can annotate the rendered page, inspect the source diff, and hand exact feedback back to a person or coding agent.
Use HTML when the reviewer needs to see structure and behavior together. Use a paper sketch, a short Markdown decision, or a static image when one of them answers the question with less work.
The existing [HTML versus Markdown guide](/learn/code-context/ai-agent-html-vs-markdown) explains when HTML earns its extra source and security cost.
## How should a person or coding agent review the artifact?
Name the stage before giving feedback. “The page feels wrong” does not tell the agent which decisions may change.
Use these targets:
| Stage | Exact feedback targets |
| - | - |
| Wireframe | Missing information, wrong grouping, task order, primary action, decision boundary, and failure paths |
| Mockup | Visual hierarchy, spacing, type scale, contrast, responsive reflow, design-system fit, and whether state meaning survives without color |
| Prototype | Trigger, state transition, loading and error behavior, keyboard path, focus movement, status announcements, reversibility, and handoff to the real system |
A useful comment names the location, observed problem, requested change, and acceptance check:
> Prototype, blocked-to-ready transition: the summary stays at 3 / 4 after the smoke test passes. Update it to 4 / 4, announce the ready state, and keep the release action disabled until both changes occur.
Another coding agent can review the same targets. Ask it to compare the artifact with `brief.md` and `states.md`, report contradictions, and test the named flow. Do not ask it whether the interface is “good.” Give it the same bounded questions a human reviewer receives.
End the review with explicit decisions:
* **Structure accepted:** required content, grouping, task order, and primary action are settled.
* **Visual direction accepted:** hierarchy, responsive behavior, and state treatment are settled.
* **Tested behavior accepted:** the named trigger, transition, feedback, and recovery path are settled.
* **Production questions recorded:** data, permissions, failures, performance, and implementation details remain visible rather than being guessed.
Implementation can now begin from an agreed reference. If one of those decisions is still open, revise the artifact first.
To review the rendered file with [Plannotator](https://plannotator.ai/):
```bash theme={null}
plannotator annotate release-readiness.html
```
Plannotator renders local HTML in a sandboxed iframe and can return selected-text or pinpoint feedback to the active coding-agent session. Its sandbox still permits the HTML to make outbound requests, so keep review artifacts self-contained and inspect untrusted scripts. See the current [open-source HTML annotation workflow](/open-source/workflows/html).
The broader [website and HTML annotation guide](/learn/annotate-any-web-page-or-html-file) covers URL imports, folders, and the separate live-page workflow.
## Where does Effective HTML fit?
[Effective HTML](https://github.com/plannotator/effective-html) is the companion skill repository for producing self-contained HTML artifacts. Its current [`html` skill](https://github.com/plannotator/effective-html/tree/main/skills/html) covers explainers, comparisons, decks, and prototypes, and its bundled examples include prototype animation and interaction.
Effective HTML now includes the dedicated [`html-wireframe`](https://github.com/plannotator/effective-html/tree/main/skills/html-wireframe) skill for low-fidelity structure and the [`html-prototype`](https://github.com/plannotator/effective-html/tree/main/skills/html-prototype) skill for styled mockups and working interaction. Together they package this progression directly, from restrained structural choices to focused interaction tests.
Use Effective HTML to give an agent a stronger visual starting point and a repeatable way to create the artifact. Pair it with the brief, state model, review questions, and acceptance checks so each revision answers an explicit product question.
## Choose the next tool by the unresolved question
Keep working in HTML while reviewers are deciding structure, visual direction, or a bounded interaction. Switch when the next question depends on a capability the artifact does not have.
* Move to Figma or another shared design tool when the work depends on its component libraries, vector editing, multiplayer design workflows, or formal handoff.
* Move to production code when the question depends on real data, framework components, permissions, performance, or integrations.
* Record the accepted decision in Markdown when it needs to remain readable and editable without the browser artifact.
* Start with paper or a whiteboard when drawing the first structure is faster than asking an agent to build it.
Choose the least expensive artifact that makes the current uncertainty testable.
## Frequently asked questions
### Is an HTML wireframe the same as an HTML mockup?
No. An HTML wireframe tests structure, content, and task order with restrained presentation. An HTML mockup applies a representative visual system to that structure so reviewers can judge hierarchy, spacing, color, typography, and responsive layout.
### What makes an HTML mockup a prototype?
The artifact becomes a prototype when its behavior is part of the review. Working controls, transitions, validation, loading, errors, or recovery paths let reviewers test what happens, not only how the screen looks.
### Should a coding agent start with a wireframe?
Start with a wireframe when the content, grouping, or flow is uncertain. Skip it when the product already has an approved structure and the open question is visual or interactive.
### Is this a hosted AI wireframe generator?
No. This is a file-based workflow for people and coding agents. Effective HTML provides skills and examples for creating HTML artifacts. Plannotator opens and annotates the resulting files. Neither is presented here as an online AI wireframe generator.
### Can a prototype become the production interface?
Sometimes. A prototype built with the production framework and components may be ready to integrate. A standalone HTML artifact is usually the reference for the accepted behavior, which the team then connects to the application's data, permissions, tests, security boundaries, and performance requirements.
*Published July 29, 2026, by the Plannotator documentation team. Last reviewed July 29, 2026. Maintained by the Plannotator project.*
# How to Keep Codebase Documentation Current When AI Agents Write Code
Source: https://docs.plannotator.ai/learn/code-context/living-documentation-for-ai-agents
A practical workflow for keeping codebase documentation current as AI coding agents plan, implement, test, and revise software.
To keep codebase documentation current when AI agents write code, update it as part of the same change as the implementation. Start from current repository context, approve the intended change, capture material discoveries while the agent works, verify the result against executable behavior, and merge the documentation update with the code. Keep the original RFC as history. Use the maintained product and technical documents to explain what is true now.
A large retrospective written after the pull request is less reliable. The agent may have to reconstruct intent from stale plans, partial chat history, and code it did not personally execute.
![An AI coding agent and a human reviewer update a living codebase handbook from the current code diff and validation while preserving an earlier RFC as history.]()
![An AI coding agent and a human reviewer update a living codebase handbook from the current code diff and validation while preserving an earlier RFC as history.]()
## Separate current documentation from historical records
Living documentation records the behavior and constraints that future engineers and agents should trust. It might include:
* a `PRODUCT.md` that explains user-visible behavior and product boundaries;
* a `TECH.md` that explains system components, data flow, and operational constraints;
* an API contract generated from, or checked against, the implementation;
* a searchable handbook under `docs/`;
* runbooks for deploying, observing, and recovering the system;
* repository instructions for coding agents.
It should not contain every discussion that produced the system. Review threads, RFCs, plans, and agent progress logs remain useful, but they answer historical questions: What did we propose? Which alternatives did we reject? What happened during execution?
Maintained documentation answers a different question:
> If I need to change or operate this system today, what should I believe?
A repository can accumulate detailed feature directories without identifying which one describes current behavior. Maintainers need to designate the current source.
GitHub's [Spec Kit persistence guidance](https://github.github.com/spec-kit/concepts/spec-persistence.html) makes this choice explicit. A team can keep feature artifacts as immutable history, continuously reconcile them with implementation discoveries, or treat a living specification as the contract. Whichever model a team chooses, contributors need to know which documents are historical and which are authoritative.
## Put documentation in the implementation loop
Spec-driven tools already create structured context before code. GitHub Spec Kit, for example, uses a [Spec → Plan → Tasks → Implement workflow](https://github.github.com/spec-kit/). Those artifacts help an agent avoid jumping directly from an issue to a patch.
Once implementation begins, code exposes details the plan could not know: an old client depends on undocumented behavior, a database invariant differs from the architecture diagram, or a browser interaction fails in a state the acceptance criteria missed.
Feed those discoveries back into the maintained documents without rewriting history:
Link the change request to the current product, technical, API, and operational documents. If those sources disagree before work starts, resolve the disagreement or name it as part of the requested change.
Review the consequential product and engineering decisions before broad agent execution. Pin the exact version in Git or the project system when other people need a durable record. [How to Approve AI Coding Plans Before Execution](/learn/code-context/approve-ai-coding-plan-before-execution) explains Plannotator's local feedback, Plan Diff, and Approve loop.
When an agent finds a material contradiction or missing decision, record it in the pull request or live draft while the evidence is available. Do not bury a changed product rule inside a code comment or an agent chat.
Run the relevant unit, integration, contract, migration, and end-to-end checks. Review the implementation and its [code review artifacts](/learn/code-review/what-are-code-review-artifacts), such as screenshots, browser traces, or test output. A generated explanation is a claim until executable behavior supports it.
Edit only the maintained pages affected by the accepted behavior. Link to the historical RFC for rationale instead of copying its entire narrative into the handbook.
Keep the approved request, important deviations, implementation revision, validation evidence, and final decision connected. Mark superseded documents clearly rather than deleting the evidence or leaving two sources that both appear current.
GitHub's guidance for [evolving Spec Kit artifacts](https://github.github.com/spec-kit/guides/evolving-specs.html) tells teams to decide whether an implementation discovery changes intended behavior, implementation strategy, task breakdown, or only code, then reconcile the artifacts that now disagree.
## A repository-based example
Consider a team replacing a single-request upload API with resumable uploads for large files. Its repository contains:
```text theme={null}
docs/
PRODUCT.md
TECH.md
uploads.md
operations/upload-recovery.md
specs/
017-resumable-uploads/
RFC.md
PLAN.md
VALIDATION.md
```
The RFC proposes multipart upload sessions, resumable offsets, a 24-hour cleanup rule, and compatibility for clients that still send one request. Product, API, storage, and operations owners record the accepted revision in their project system. A coding agent implements against that checkpoint.
During retry testing, the agent finds that the mobile client reuses an idempotency key after a network timeout, behavior absent from both the plan and `uploads.md`. The discovery changes the compatibility contract and the server state machine.
The team should not let the agent invent retry semantics or rewrite the documentation to match the easiest implementation. It should return the discovery for a decision and approve the new direction. The agent then implements the idempotency rule and provides a handoff naming the exact revision, tests, risks, and documentation impact. See [What Should an AI Coding Agent Hand Back After It Changes Code?](/learn/code-context/ai-coding-agent-handoff).
Before merge, reviewers check four things together:
1. Contract and retry tests demonstrate the accepted upload and resume behavior.
2. Expiration, cleanup, storage-failure, and rollback behavior match the reviewed plan.
3. `docs/PRODUCT.md`, `docs/TECH.md`, and `docs/uploads.md` describe the shipped system.
4. `specs/017-resumable-uploads/RFC.md` remains an immutable decision record and links to the final implementation.
The RFC explains how the team reached the result. The maintained documents explain how uploads work after it ships. Tests and running behavior determine whether either explanation is accurate.
Warp offers a concrete example of splitting feature intent from implementation detail: its public [APP-2527 specification](https://github.com/warpdotdev/warp/tree/master/specs/APP-2527) contains separate `PRODUCT.md` and `TECH.md` files. A team still needs a convention for carrying accepted behavior into whichever documentation future contributors read first.
## Repository files make the maintenance rule enforceable
Keeping documentation near code enables several maintenance checks:
* A pull request can show code and documentation changes together.
* `CODEOWNERS` or required reviewers can route affected documents to the right owners.
* CI can build the documentation, check links, validate schemas, and test code samples.
* Git history can show when an explanation changed and which implementation changed with it.
* Agent instructions can identify the maintained documents that must be read before a particular system is modified.
[mdBook](https://rust-lang.github.io/mdBook/) is one lightweight example: it turns repository Markdown into a navigable, searchable site. Its CLI can also [test Rust code samples](https://rust-lang.github.io/mdBook/cli/index.html), allowing teams to check some documentation claims automatically.
Repository placement also gives coding agents normal file access. Clear entry points are still required. A large `docs/` tree with contradictory pages gives an agent more material but no reliable source.
## Verify generated documentation
An agent can inventory changed files, draft release notes, update examples, and identify stale documents. It can also confidently describe behavior the program does not have.
Anthropic's work on [long-running coding-agent harnesses](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) found that progress files and Git history helped later sessions recover context, but it also found agents could mark work complete without proper end-to-end testing. Explicit browser testing exposed failures that code inspection and narrower checks missed.
Check generated documentation against:
* the approved request for intended behavior;
* the code diff for the mechanism;
* tests and runtime evidence for observed behavior;
* domain owners for product and operational meaning.
The agent's narrative is a draft, not independent proof.
For dense comparisons or interactive explanations, an agent may produce HTML alongside durable Markdown. [When Should AI Coding Agents Produce HTML Instead of Markdown?](/learn/code-context/ai-agent-html-vs-markdown) explains when that improves understanding and when it merely adds maintenance cost.
## Skip documentation updates when behavior does not change
Not every edit changes durable behavior. A typo fix, local refactor, dependency patch with no contract change, or test-only cleanup may require no handbook update.
Use one short question in the pull request or agent handoff:
> Does this change alter a user-visible behavior, public or internal contract, system constraint, operating procedure, or fact that future contributors rely on?
If the answer is no, record **no durable documentation impact** and continue. Do not make the agent perturb an unrelated page merely to satisfy a checklist.
If the answer is yes, name the exact maintained files and update them with the implementation. A small documentation impact field is enough to identify the required work without adding a separate approval process.
## Limitations
Living documentation cannot make every repository fact current automatically.
* Some behavior exists only at runtime or in external infrastructure.
* Tests can be incomplete or encode the wrong expectation.
* Generated API references may be accurate but still fail to explain intent.
* A document owner can approve prose without noticing a contradictory implementation.
* Fast-moving teams may accept temporary drift during incidents or migrations.
* Historical records can expose sensitive design or security details and may need access controls.
Readers should be able to identify which source is current, how the team verified it, and where to look when code and documentation disagree.
## Frequently asked questions
### What is living documentation for AI coding agents?
It is maintained product, technical, API, and operational context that changes with the system and is available to both people and agents. It describes current behavior rather than only preserving the plan for one completed feature.
### Should an RFC be updated after implementation?
Usually, preserve an approved RFC as decision history and update separate maintained documentation with the shipped behavior. If your team intentionally uses a living-spec model, revise the specification and keep its derived plan and tasks consistent. State the convention explicitly.
### Should an AI agent update documentation automatically?
It can draft the update and identify likely affected pages. A reviewer should compare the draft with the approved request, code, tests, and observed behavior before treating it as current documentation.
### How do you prevent codebase documentation from becoming stale?
Put a documentation-impact decision in the implementation and review workflow, update affected documents in the same pull request, assign owners, and add automated checks for build failures, broken links, schemas, and executable examples where those checks are possible.
### Does every AI-generated code change need a documentation update?
No. Changes that do not alter durable behavior, contracts, constraints, or operating procedures should use the fast path and record that there is no documentation impact.
### Are repository Markdown files enough for coding agents?
They work well as a default because they are portable, versioned, searchable, and easy for agents to read. They are not enough when the files conflict, lack clear ownership, omit runtime facts, or cannot express a comparison or interaction that would be clearer in another artifact.
## When a consequential change is complete
Treat a consequential change as complete when the code, executable evidence, and maintained explanation agree. If they do not agree, record the remaining disagreement.
The workflow in [How Teams Understand AI-Generated Code Before Shipping It](/learn/code-context/understand-ai-generated-code-before-shipping) shows how teams check that agreement. Future engineers and agents can start from the system the team operates while retaining the original request and decision trail for historical context.
Open Markdown, text, HTML, or a folder in Plannotator and return annotations to the active coding agent.
*Last reviewed July 18, 2026. Maintained by the Plannotator project.*
# How Teams Understand AI-Generated Code Before Shipping It
Source: https://docs.plannotator.ai/learn/code-context/understand-ai-generated-code-before-shipping
A practical workflow for understanding AI-generated code by connecting the approved request, implementation, evidence, review, and final team decision.
A team understands AI-generated code before shipping it when reviewers can connect the **requested change**, the **context the team approved**, the **actual implementation**, the **evidence that demonstrates its behavior**, and the **decision to ship**. An AI summary can help reviewers find those pieces, but it cannot establish that they agree.
Product, engineering, and operations each inspect the part they own, then explain what they accepted.
Small, reversible changes do not need a formal process merely because an AI agent wrote them. A developer can often work conversationally with a capable model, inspect the patch, run focused tests, and use an ordinary review. Add more structure when several people need the same context, the change is consequential, or the implementation is too large for one person to hold comfortably.
![Two teammates and the Plannotator mascot trace one AI-generated change from its request and system behavior through the code diff to passing validation evidence.]()
![Two teammates and the Plannotator mascot trace one AI-generated change from its request and system behavior through the code diff to passing validation evidence.]()
## What an AI summary can and cannot establish
GitHub Copilot can [summarize a pull request and explain changes in specific files or lines](https://docs.github.com/en/copilot/tutorials/explore-pull-requests). For an agent-created pull request, it can also use the agent's session logs to explain what changed, what was validated, and why.
A reviewer can use that summary to identify affected subsystems, important files, claimed behavior, and validation performed.
The summary may still omit a risky edge case, describe intended rather than actual behavior, or accurately describe code that implements the wrong decision. GitHub's own guidance tells authors to include purpose, additional context, requested review depth, and a useful reading order. See [Helping others review your changes](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/getting-started/helping-others-review-your-changes).
Use the summary to decide where to look. Use the request, code, tests, runtime behavior, and discussion to decide whether the change is correct.
## Treat understanding as one inspectable chain
A team can inspect six concrete objects:
| Object | The question it answers |
| - | - |
| Request for change | What outcome does the team want, and why? |
| Approved context | Which exact decisions, constraints, and validation requirements may the agent act on? |
| Implementation | What code, data, APIs, and operational behavior changed? |
| Review artifacts | What screenshots, recordings, HTML, test output, or other evidence demonstrate the result? |
| Current revision | Which exact version has each reviewer inspected? |
| Team decision | What did the responsible reviewers accept, reject, or record as a known risk? |
Code that implements an obsolete plan is still wrong for the current request. A screenshot from an earlier revision does not demonstrate the code being approved. A reviewer who read revision 3 has not reviewed revision 5. The team needs shared, versioned context instead of one developer's private agent conversation.
## A worked example: changing account deletion
Suppose a company currently deletes customer accounts immediately. The team wants a 30-day recovery period without weakening the promise that a deleted user loses access at once.
This touches authentication, stored data, background work, and support operations. “Add recoverable account deletion” is not enough context to authorize an implementation.
### 1. The team approves the behavior before code exists
Product, identity, and data owners review a shared plan. Version 4 says:
* `DELETE /v1/account` returns `202 Accepted` and marks the account `pending_deletion`;
* all browser sessions, API keys, and refresh tokens stop working immediately;
* a deletion worker permanently removes eligible records after 30 days;
* support can restore the account during that window, with an audit event;
* retained payment records stay inaccessible to the user;
* migration, rollback, and queue-failure tests are required.
The project records the named owners' decision on version 4 in its normal system. The coding agent receives that exact checkpoint, not whichever draft happens to be newest. Plannotator can help [review and compare the local plan drafts](/learn/code-context/approve-ai-coding-plan-before-execution), but it does not create the identity or authorization record.
### 2. The agent produces a change map
The agent's pull request changes the account route, token validation, account table, deletion worker, OpenAPI file, and support tooling. Its handoff names the approved plan and current commit, then points reviewers to the important paths:
```text theme={null}
apps/api/routes/delete-account.ts
packages/auth/validate-session.ts
workers/account-deletion.ts
db/migrations/0142_pending_deletion.sql
openapi/account.yaml
```
The identity owner can begin at token invalidation while the data owner traces retention and deletion. Not every reviewer must read every file in the same order.
Use the reusable completion format in [What Should an AI Coding Agent Hand Back After It Changes Code?](/learn/code-context/ai-coding-agent-handoff).
### 3. Reviewers follow the risky paths into the code
The identity reviewer traces `DELETE /v1/account` through the database state change and every credential check. The data reviewer follows the worker through deletion and retained records. The operator checks retries, idempotency, metrics, and rollback.
They use the agent's explanation to locate code, then verify its claims. Reviewers move between high-level intent and concrete state transitions, failure paths, and neighboring invariants until the behavior is coherent.
A Microsoft field study found that code and change understanding was central to modern review. Review also produced knowledge transfer, team awareness, alternative solutions, and defect detection. See [Expectations, Outcomes, and Challenges of Modern Code Review](https://www.microsoft.com/en-us/research/publication/expectations-outcomes-and-challenges-of-modern-code-review/).
### 4. Artifacts make behavior inspectable
The agent attaches a browser recording, state-transition diagram, focused test output, and small HTML report for comparing failure paths. HTML earns its place because the review depends on several states and outcomes; the linear plan remains Markdown. [When Should AI Coding Agents Produce HTML Instead of Markdown?](/learn/code-context/ai-agent-html-vs-markdown) covers that choice.
Each file supports a specific claim. The recording demonstrates the flow, the tests identify exercised cases, and the report compares queue, token, and restoration paths. [What Are Code Review Artifacts?](/learn/code-review/what-are-code-review-artifacts) explains how evidence beside the diff becomes part of the review.
### 5. A finding changes the implementation
The identity reviewer discovers that access tokens are rejected immediately, but a refresh token can still mint a new access token until the deletion worker runs. The implementation contradicts the approved plan.
The approved context already settled the expected behavior. The agent fixes refresh-token validation, adds a regression test, and updates the change map.
![An approved account-deletion lifecycle compared with a reviewed revision that fails to revoke refresh tokens and a corrected revision that closes the gap.]()
![An approved account-deletion lifecycle compared with a reviewed revision that fails to revoke refresh tokens and a corrected revision that closes the gap.]()
The correction arrives with three other commits. A reviewer who already inspected the first revision should see the cumulative change from that checkpoint to the current head. [What Is a Revision Diff?](/learn/code-review/what-is-a-revision-diff) describes how that comparison avoids rereading unchanged work.
### 6. The team decides and preserves what remains true
The identity, data, and API reviewers approve the current revision after checking the fix and refreshed evidence. After merge, the accepted lifecycle, retention rule, and recovery behavior update maintained product and technical documentation. [How to Keep Codebase Documentation Current When AI Agents Write Code](/learn/code-context/living-documentation-for-ai-agents) covers that final step.
## A practical review sequence
Use these seven review actions:
Read the issue, RFC, or approved plan first. Identify the behavior, non-goals, and constraints the code must preserve.
Record both the approved context version and the code revision under review. If either changes materially, make that change visible.
Ask for affected boundaries, entry points, validation, and uncertainty. Give reviewers a reading order based on risk and ownership.
Follow consequential paths across state transitions, side effects, failures, and rollback. Inspect surrounding code where the diff depends on an invariant.
Match artifacts to the current revision. Ask what each proves and what it leaves untested.
Keep discussion attached to the relevant code or artifact. After new pushes, compare against each reviewer's last checkpoint rather than assuming the previous review still applies.
Tie approval to the reviewed revision. Move accepted product and technical decisions into the documentation that the next person or agent will read.
## Divide review by ownership without losing context
Reviewers do not need identical mental models. Each owner can inspect a different part of the change as long as every decision refers to the same request and revision.
The product owner verifies the requested experience. Security examines credential and data boundaries. The service owner traces failure behavior. Together they check one revision against one approved request.
GitHub pull request reviews already support named reviewers, line comments, suggestions, approvals, and requests for changes. GitHub also advises reviewers to understand a pull request's motivation and linked context before evaluating the diff. See [Reviewing proposed changes in a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-proposed-changes-in-a-pull-request).
VS Code's preview [Artifacts panel](https://code.visualstudio.com/docs/chat/chat-artifacts) can surface plans, screenshots, documents, and agent-produced resources beside a conversation. Teams can use that panel while preserving the route from request to evidence to decision across their other review tools.
## Know the limits
This workflow improves traceability, but it does not prove correctness.
* An approved plan can contain a bad decision.
* Reviewers can misunderstand unfamiliar code or accept weak evidence.
* Tests demonstrate selected behavior, not every production condition.
* Generated explanations and polished artifacts can be stale or wrong.
* A small diff can carry large consequences, while a large mechanical diff may need less interpretation.
* More process can consume attention without improving a routine, reversible change.
Keep changes focused, assign review by consequence, preserve exact checkpoints where they matter, and make uncertainty visible.
## Frequently asked questions
### Is an AI-generated pull request summary enough for code review?
No. It is useful orientation, but reviewers still need to compare the implementation with the requested behavior, inspect risky code paths, evaluate current evidence, and make a decision about an exact revision.
### How do you review AI-generated code you did not write?
Start with the intended outcome and constraints. Use the agent's change map to find entry points, then trace state changes, side effects, failures, and validation through the actual code. Ask for evidence where runtime behavior is easier to inspect than infer.
### Are passing tests enough to trust AI-generated code?
No. Passing tests show that selected assertions passed in a particular environment. Reviewers still need to judge whether the tests cover the approved behavior, whether important paths are missing, and whether the implementation preserves system constraints.
### Should every AI-generated change require a formal plan?
No. A small, reversible change may need only a clear request, focused tests, and ordinary review. An approved plan becomes valuable when several people or agents need one decision, or when product, security, data, API, migration, or operational consequences are substantial.
### What if the generated change is too large to understand?
Reduce or partition it before treating a summary as a substitute for review. Separate independent behavior, establish a safe reading order, and require evidence for each consequential slice. If reviewers cannot connect the code to the approved request, the change is not ready to ship.
Compare the agent's handoff with the current local diff and return line-specific feedback.
*Last reviewed July 18, 2026. Maintained by the Plannotator project.*
# Review Pull Request Artifacts Beside the Code
Source: https://docs.plannotator.ai/learn/code-review/review-pull-request-artifacts
Plannotator gathers screenshots, GIFs, videos, HTML, and Markdown from GitHub pull requests and GitLab merge requests into one artifact gallery beside the code diff.
Plannotator gathers supported screenshots, GIFs, videos, HTML files, and Markdown documents from a hosted GitHub pull request or GitLab merge request into one **Artifacts** gallery beside the code diff.
The gallery preserves where each artifact appeared, who posted it, and when it entered the conversation. Reviewers can inspect the evidence without searching through the description, comments, review replies, and resolved threads.
![Plannotator rendering an HTML code explainer with a selected passage ready for an anchored review comment.]()
## Pull request evidence gets scattered
GitHub and GitLab already let people attach files to a pull request or merge request. A developer might put screenshots in the description, add a recording after another push, and share an HTML explainer in a review reply. An agent might contribute a Markdown walkthrough or another validation image later.
The files remain in the conversation, but the reviewer has to find them before evaluating them. Long discussions make that harder, especially when some evidence sits inside resolved threads or several people add artifacts at different times.
Plannotator reads the hosted review conversation and builds a focused gallery from the supported attachments it finds. It does not move the original files or erase their context. Each gallery item links back to the description, comment, review, or thread where it appeared.
## Review each medium with the right anchor
A useful comment should point to the part of the evidence that caused it. Plannotator changes the annotation control to match the artifact.
### Select text in HTML and Markdown
HTML explainers render inside Plannotator's restricted viewer. Reviewers can select the exact sentence or rendered section they want to discuss. Markdown documents use the same text-selection workflow.
![Plannotator showing a pull request artifact gallery with screenshots, videos, HTML explainers, and Markdown documents collected beside the code diff.]()
Agent-produced HTML can contain scripts, frames, and network requests. Plannotator treats remote HTML as untrusted content and renders it in a sandbox rather than giving it the authority of the review application. See [when AI coding agents should produce HTML instead of Markdown](/learn/code-context/ai-agent-html-vs-markdown) for the format and security tradeoffs.
### Pin a comment to an image or GIF
Click the relevant point on a screenshot or GIF, then leave the note. The review keeps the point with the comment, so another person does not have to infer which control, pixel, or visual state the reviewer meant.
![Plannotator showing a numbered review pin attached to a precise point in a screenshot artifact.]()
### Comment at a video timestamp
Pause a video at the relevant moment and comment on that timestamp. The note stays attached to the playback position, which makes feedback such as “the menu flickers here” reproducible.
![Plannotator showing a video artifact paused at a timestamp with a comment anchored to that moment.]()
Every supported artifact can also receive a note about the artifact as a whole.
## Keep the source and route the feedback
The gallery shows the artifact's author, conversation location, and original source link. That provenance helps reviewers distinguish evidence from the pull request author, another reviewer, or an agent participating in the conversation.
Artifact feedback joins the same review draft as code annotations. When the review is ready, Plannotator can post the feedback to the GitHub pull request or GitLab merge request with links to the original artifact and conversation. A local reviewer can instead send the structured feedback directly to the coding agent working on the change.
## Hide reviewed evidence without deleting it
Reviewers can hide an artifact after inspecting it and restore hidden artifacts later. Hiding only changes the local gallery view. It does not delete the attachment or alter the hosted review conversation.
![Plannotator showing the control used to hide a reviewed pull request artifact and restore hidden artifacts later.]()
## What the Artifact Gallery does not collect
The gallery has a deliberate boundary:
* It appears for hosted GitHub pull requests and GitLab merge requests because those reviews have a description and conversation to inspect.
* It does not appear for local diff reviews.
* It collects supported images, GIFs, videos, HTML, and Markdown referenced in the hosted conversation.
* It does not automatically import GitHub Actions workflow artifacts.
* It does not prove that an artifact still matches the current head revision. Reviewers should check when the evidence was produced after the code changes.
GitHub and GitLab remain the systems of record for the review conversation. Plannotator gives the code and its supporting evidence one surface for inspection and feedback.
Open a hosted pull request or merge request in Plannotator and review its supported artifacts beside the diff.
Learn how screenshots, recordings, HTML, documents, and validation output support a code review decision.
*Last reviewed July 18, 2026. Maintained by the Plannotator project.*
# What Are Code Review Artifacts? Screenshots, Video, HTML, and AI Evidence
Source: https://docs.plannotator.ai/learn/code-review/what-are-code-review-artifacts
Code review artifacts are screenshots, recordings, HTML, reports, and other evidence reviewed beside a code diff. Learn what GitHub supports and why AI makes these artifacts more important.
A **code review artifact** is reviewable evidence attached to a proposed change that the code diff cannot communicate well by itself. It might be a screenshot, screen recording, HTML prototype, Markdown report, test result, architecture diagram, or benchmark visualization.
The code diff shows **what changed**. Artifacts help show **what the change does, why it was made, and how it was validated**.
![A reviewer compares a code diff with supporting screenshot, video, HTML, Markdown, and test-result artifacts.]()
![A reviewer compares a code diff with supporting screenshot, video, HTML, Markdown, and test-result artifacts.]()
A code review artifact can be created by a person, an AI coding agent, or a CI workflow. Its role in the review matters more than who produced it.
## A pull request is becoming more than a patch
Consider a pull request that changes a checkout flow. The author or coding agent might provide:
* a before-and-after screenshot;
* a short recording of the updated interaction;
* an HTML prototype showing the possible states;
* a Markdown explanation of the implementation;
* a browser-test report or failure trace from CI.
None of these files replaces the code. They answer questions that are difficult to settle by reading the patch alone:
* Does the new layout work at mobile widths?
* What happens between clicking **Pay** and seeing confirmation?
* Does the loading state match the intended design?
* Which paths did the automated test exercise?
* What tradeoff did the author make and why?
The reviewer needs both the patch and the evidence required to evaluate it.
![A central code diff is connected by violet threads to screenshot, video, HTML, Markdown, and test-result evidence.]()
![A central code diff is connected by violet threads to screenshot, video, HTML, Markdown, and test-result evidence.]()
## Why is the word “artifact” confusing?
Software teams already use *artifact* in several ways. AI products have added another meaning.
Our broader guide to [AI artifacts](/learn/ai-development/what-is-an-ai-artifact) explains how documents, images, applications, media, and other agent outputs become reusable objects beyond a chat. In code review, the artifact has a narrower job: it helps a reviewer understand or validate a proposed change.
| Term | Meaning | Relationship to code review |
| - | - | - |
| Claude Artifact | A substantial, self-contained AI output intended to be viewed, changed, reused, or shared outside the conversation | It becomes review evidence when it explains or demonstrates a proposed change |
| GitHub pull request attachment | A file uploaded into a pull request description or comment | It places evidence in the review conversation |
| GitHub Actions artifact | Files produced and retained by a workflow run, such as logs, screenshots, coverage, or binaries | It is automated evidence that may help validate a change |
| Code review artifact | Any self-contained evidence a reviewer needs beside the diff | This describes the artifact’s role, regardless of its origin |
Anthropic did not invent the general software term. Its [Artifacts product](https://support.claude.com/en/articles/9487310-what-are-artifacts-and-how-do-i-use-them) made a particular form of AI output more visible: a standalone document, application, diagram, visualization, or interactive page that can be inspected separately from the chat that produced it.
## What can GitHub already do?
GitHub already lets people attach a wide range of files to pull requests. You can drag a file into a pull request description or comment, and GitHub uploads it immediately and inserts an anonymized URL into the Markdown text.
GitHub supports common media such as PNG, GIF, JPEG, SVG, MP4, MOV, and WebM. Pull request comments also accept HTML, Markdown, PDFs, office documents, JSON, logs, notebooks, patches, archives, audio, and many development-file formats. See GitHub’s current [file attachment documentation](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/attaching-files).
GitHub applies the repository’s visibility to uploaded files:
* files uploaded to public repositories can be accessed without authentication;
* files uploaded to private or internal repositories require repository access.
This is already enough for a small evidence set. An author can put two screenshots in the description and a reviewer can discuss them in a comment.
The workflow becomes harder when evidence arrives at different times and in different places. A screenshot may be in the description, a recording in a later comment, an HTML explainer in a review reply, and a coverage report under a workflow run. A reviewer has to discover the evidence before evaluating it.
That is the distinction: GitHub provides the file transport. A dedicated artifact surface organizes the evidence as something to review.
## Are GitHub Actions artifacts the same thing?
Not exactly.
GitHub defines a [workflow artifact](https://docs.github.com/en/actions/concepts/workflows-and-actions/workflow-artifacts) as a file or collection of files produced during a workflow run and retained after the job completes. GitHub’s examples include:
* log files and core dumps;
* test results and failure screenshots;
* compiled binaries and archives;
* stress-test output and code-coverage reports.
Those files are artifacts of the build or test process. They become code review artifacts when a reviewer needs them as evidence for the pull request.
The distinction matters operationally. Workflow artifacts live under the workflow run, require repository read access to download, and expire according to GitHub’s retention settings. GitHub currently keeps build logs and workflow artifacts for 90 days by default. A screenshot uploaded into the pull request conversation has a different location and lifecycle.
## Why are AI coding agents making artifacts more important?
Coding agents produce more than source code. They can run browsers, reproduce bugs, execute tests, inspect logs, create diagrams, compare designs, and explain the work they performed.
GitHub Copilot coding agent, for example, can use a browser to validate a web application and [include captured screenshots in its pull request](https://github.blog/changelog/2025-07-02-copilot-coding-agent-now-has-its-own-web-browser/). GitHub also preserves agent session logs and links agent-authored commits back to those logs so reviewers and auditors can trace how a change was produced.
Claude Code now treats PR walkthroughs, system explainers, dashboards, incident timelines, and release checklists as [shareable session artifacts](https://claude.com/blog/artifacts-in-claude-code). These pages can combine codebase context, connected tools, test output, and the agent’s explanation in one visual surface.
Trustworthy evidence can reduce the work of understanding a large agent-created change. A polished explanation can also be wrong, stale, or selectively reassuring. Use artifacts to investigate the change, not as a reason to stop reading the code.
## Why is HTML becoming a common AI artifact format?
Markdown remains useful for durable, text-first documents. HTML becomes attractive when the explanation needs visual hierarchy, spatial layout, or interaction.
In [“The unreasonable effectiveness of HTML,”](https://claude.com/blog/using-claude-code-the-unreasonable-effectiveness-of-html) Claude Code engineer Thariq Shihipar describes using HTML for dense technical outputs that people are more likely to read and understand. A single HTML file can combine:
* tables and side-by-side comparisons;
* rendered code and annotated diffs;
* SVG diagrams and architecture maps;
* screenshots and visual states;
* tabs, filters, sliders, or small purpose-built controls;
* responsive layouts for large reports.
His code-review example is direct: create an HTML artifact that explains a pull request, renders the actual diff, adds margin annotations, and color-codes findings by severity.
That makes HTML more than a document format. It can be a temporary inspection interface built for one change.
HTML is active content. An uploaded page can contain scripts, network requests, frames, and other behavior. A review system must treat arbitrary HTML as untrusted and render it inside a restricted sandbox rather than giving it the review application’s authority.
Reviewers should also know whether an HTML artifact is a static explanation, an interactive prototype, or a live page backed by changing data. A visually convincing page is not automatically reproducible evidence.
## What makes an attachment genuinely reviewable?
Uploading a file is the beginning, not the complete review workflow. Useful code review artifacts need several properties.
### Discoverability
The reviewer should be able to see the relevant evidence set without searching a long conversation or opening unrelated workflow runs.
### Provenance
The artifact should show who or what produced it, where it came from, and when it entered the review. Agent-generated evidence should retain the agent identity and the human who initiated the work.
### Safe, format-aware inspection
Different evidence needs different treatment. Images need spatial inspection. Video needs playback and timestamps. Markdown needs readable rendering and text selection. HTML needs isolation.
### Anchored discussion
Comments should be able to refer to a point, region, timestamp, quotation, or whole artifact. “The flicker around 00:14” is more useful when the comment is actually attached to 00:14.
### A relationship to the code revision
Reviewers need to know which version of the code the evidence demonstrates. A screenshot captured before three later pushes may no longer describe the current pull request.
### Access, retention, and deletion
Artifact visibility should follow the review’s access rules. Teams should also know how long the bytes remain, whether an external link can expire, and what happens to the discussion when an attachment is deleted.
### An auditable decision
For consequential changes, the durable record includes the file, its origin, the comments it received, which concerns were resolved, and the human review decision that followed.
## How does Plannotator handle code review artifacts?
The open-source Plannotator code-review app gathers supported images, GIFs, video, HTML, and Markdown referenced in a hosted GitHub pull request or GitLab merge request into one **Artifacts** view beside the diff.
The review behavior follows the format:
* images and GIFs can receive point or whole-artifact comments;
* video can receive timestamped or whole-video comments;
* Markdown can receive quoted-text or whole-document comments;
* HTML can receive selected-text or whole-page comments and is rendered inside a restricted sandbox.
The source remains visible, so a reviewer can tell whether an artifact came from the change-request description, a comment, a review, or a review thread. Plannotator preserves the author, timestamp when available, and a link to the original conversation. Reviewers can hide evidence they have already inspected and restore it later.
Artifact notes join the ordinary review draft. They can be posted to the GitHub or GitLab review with links back to the original evidence, or sent directly to the local coding agent.
This is deliberately not a claim that every hosted upload becomes a Plannotator artifact. The current focused set is images, GIFs, video, HTML, and Markdown found in the hosted conversation. GitHub Actions artifacts are not automatically imported. Local diff reviews do not have an artifact gallery because they do not have a hosted PR or MR conversation to collect from. Artifacts are currently associated with the review rather than pinned to a particular Git revision.
GitHub or GitLab remains the system of record for the change request. Plannotator provides a focused surface for inspecting and discussing supported evidence beside the code. See [how to review pull request artifacts in Plannotator](/learn/code-review/review-pull-request-artifacts) for the released workflow.
![Plannotator Review showing a Markdown review artifact selected beside its uploaded artifact list and an annotation about validating product behavior.]()
![Plannotator Review showing a Markdown review artifact selected beside its uploaded artifact list and an annotation about validating product behavior.]()
See how Plannotator collects hosted PR and MR evidence, preserves its source, and anchors feedback to text, image points, and video timestamps.
## Common failure modes
Artifacts improve review only when reviewers understand their limits.
* **Stale evidence:** the artifact demonstrates an earlier revision of the code.
* **Broken or expired links:** externally hosted evidence disappears or its access rules change.
* **Unsafe active content:** HTML or SVG is rendered with more authority than it should receive.
* **Missing provenance:** the reviewer cannot tell whether a person, agent, or workflow created the output.
* **Presentation bias:** a polished walkthrough makes the change feel safer than the underlying implementation is.
* **Incomplete validation:** a successful screenshot or test report demonstrates one path, not every relevant behavior.
* **Evidence overload:** a large pile of generated reports increases review work instead of directing attention.
A good artifact reduces uncertainty. It should not bury the reviewer in output.
## Frequently asked questions
### Are code review artifacts the same as build artifacts?
No. A build artifact is output produced by a build or workflow. It becomes a code review artifact only when a reviewer needs to inspect it as evidence for the proposed change.
### Does GitHub support code review artifacts?
GitHub supports many file attachments in pull request descriptions and comments, and GitHub Actions retains workflow artifacts. Those capabilities provide the underlying files. A dedicated review-artifact surface adds organization, format-aware inspection, provenance, and anchored discussion.
### Do artifacts replace the code diff?
No. The code diff remains the proposed implementation. Artifacts make its behavior, validation, and surrounding reasoning easier to inspect.
### Can an AI agent create review artifacts?
Yes. Agents can create screenshots, recordings, diagrams, reports, HTML explainers, and test output. Reviewers should still verify the evidence, preserve its provenance, and make the final review decision themselves.
### Is it safe to review an HTML artifact?
Only when the hosting or review system treats it as untrusted active content. Arbitrary HTML should be isolated with browser sandboxing and restrictive content policies. External HTML should not inherit access to the review application.
### Should every pull request include artifacts?
No. A small backend change may be completely understandable from its tests and diff. Artifacts are useful when behavior, design, validation, or system context cannot be reviewed efficiently from code alone.
Next: [Learn how revision diffs show what changed since a reviewer’s last look](/learn/code-review/what-is-a-revision-diff).
*Last reviewed July 18, 2026. Maintained by the Plannotator project.*
# What Is a Revision Diff? A Practical Code Review Guide
Source: https://docs.plannotator.ai/learn/code-review/what-is-a-revision-diff
Learn what a revision diff is, how it differs from a pull request diff, and why it makes repeat code reviews faster after authors push new commits.
A **revision diff** is a cumulative diff between the exact version of a change set a reviewer last reviewed and its current version. It answers one practical question: **what changed since I last looked?**
![A reviewer returns to a pull request after nine commits and compares the current head with the exact revision reviewed on Tuesday.]()
![A reviewer returns to a pull request after nine commits and compares the current head with the exact revision reviewed on Tuesday.]()
A revision diff is sometimes called an **interdiff** or a **patch-set diff**. The names vary; the reviewer’s question does not.
## What problem does a revision diff solve?
Imagine reviewing a 40-file pull request on Tuesday afternoon. You leave 12 comments and finish the review. By Thursday morning, the author has pushed nine more commits.
![A Git commit timeline shows nine commits between a Tuesday code-review checkpoint and Thursday’s current head, while Totman inspects the cumulative revision diff since the last review.]()
![A Git commit timeline shows nine commits between a Tuesday code-review checkpoint and Thursday’s current head, while Totman inspects the cumulative revision diff since the last review.]()
The full pull request diff still answers:
> What does this branch change compared with the base branch?
But that is no longer the question you need answered. You already reviewed most of that work. Your question is:
> What changed between the version I reviewed Tuesday and the version in front of me now?
Without a revision diff, reviewers usually fall back to one of two workflows:
1. Re-read the full pull request and repeatedly confirm that old code has not changed.
2. Read each new commit separately and mentally combine overlapping edits, reversions, and fixups.
A revision diff compares the two relevant snapshots directly. If only six of the original 40 files changed after Tuesday, the repeat review contains six files.
## What does GitHub offer today?
GitHub’s web review tells you which files changed and lets you manually select commits or compare SHAs. It does not make your last completed review a first-class, automatic cumulative diff inside the normal pull request web experience. GitHub’s VS Code extension does provide a version of that workflow.
More specifically:
* GitHub unmarks a file as **Viewed** if that file changes later. This helps identify affected files, but it does not isolate only the new hunks in those files. See [GitHub’s review documentation](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-proposed-changes-in-a-pull-request?tool=webui).
* GitHub’s newer Files changed experience can display one commit or a manually selected set of commits. See the [GitHub Files changed announcement](https://github.blog/changelog/2025-12-11-review-commit-by-commit-improved-filtering-and-more-in-the-pull-request-files-changed-public-preview/).
* GitHub can show the version attached to a completed review, and its compare page and API can compare known commit SHAs.
* The official GitHub Pull Requests extension for VS Code includes a command named **Show Changes Since Last Review**. See the [extension source](https://github.com/microsoft/vscode-pull-request-github/blob/main/package.nls.json).
This means the underlying comparison is not a new Git primitive. The missing step is to select the reviewer’s last completed checkpoint automatically and show that cumulative comparison inside the review.
## How does a revision diff work?
Every revision diff needs two endpoints:
When a review finishes, record the pull request’s exact head commit. This is the reviewer’s baseline.
When the reviewer returns, read the pull request’s current head commit.
Generate one cumulative diff from the reviewed revision to the current revision. Intermediate commits do not need to be replayed.
In simplified Git terms:
```text theme={null}
reviewed revision: 6a0f3c1
current revision: b91d2e8
revision diff: 6a0f3c1 → b91d2e8
```
The output should describe the net result. If commit five adds a line and commit eight removes it, that line should not appear in the revision diff.
## Revision diff vs. pull request diff vs. commit diff
| View | Comparison | Best question it answers |
| - | - | - |
| Full pull request diff | Base branch → current pull request head | What will this pull request change overall? |
| Individual commit diff | One commit’s parent → that commit | What did this particular commit do? |
| Selected commit range | Manually chosen commit range | What happened across these selected commits? |
| Revision diff | Last reviewed revision → current head | What changed since I last reviewed this? |
The distinction is the baseline. A full pull request diff is anchored to the base branch. A revision diff is anchored to a reviewer’s previous checkpoint.
![Three translucent Git comparison baselines overlay the same pull request, with the reviewer’s last checkpoint highlighted in violet through the current head.]()
![Three translucent Git comparison baselines overlay the same pull request, with the reviewer’s last checkpoint highlighted in violet through the current head.]()
## Eight revision-diff terms in plain language
### Revision
One version of the pull request as it existed at a particular moment. Each new push can create a new revision.
### Head SHA
The commit identifier for the current tip of the pull request branch. It is the fingerprint of the code currently under review.
### Patch set
The saved changes associated with a revision. Systems that need reliable historical comparisons may preserve the patch set rather than storing only a commit identifier.
### Interdiff
Another name for a diff between two revisions. It compares revision A with revision B instead of comparing the pull request with its base branch.
### Force-push or rewritten history
A push that replaces the branch’s existing commit history, often after a rebase. The new history may contain the same intent expressed through different commits.
### Retention
How long an old revision remains available for comparison. A commit identifier is useful only while the underlying commit or a saved snapshot can still be read.
### Revision marker vs. patch set
A revision marker says, “the reviewer saw commit `6a0f3c1`.” A patch set preserves enough data to reconstruct what the reviewer saw. The marker is smaller; the patch set is more durable.
### Provider compare
A comparison generated by the Git hosting provider, such as GitHub’s compare API. It is convenient when both endpoints are still available and the comparison stays within provider limits.
## What happens after a force-push or rebase?
A rebase complicates the commit graph, but it does not change the reviewer’s question. The desired comparison is still:
> the exact code previously reviewed → the code under review now
If the old commit remains available, the system can compare the two commit snapshots. If it does not, a reliable revision-diff system needs a previously saved patch set or equivalent snapshot.
This is why **remembering a SHA** and **preserving a reviewable revision** are different product decisions.
![A two-lane Git diagram where a force-push makes a reviewed commit unreachable while a preserved patch still compares cleanly with the current head.]()
![A two-lane Git diagram where a force-push makes a reviewed commit unreachable while a preserved patch still compares cleanly with the current head.]()
## Should every reviewer have a separate baseline?
Usually, yes. Review state belongs to the reviewer, not just the pull request.
One person may have approved revision 4, another may have requested changes on revision 6, and a third may be opening the pull request for the first time. “Since last review” has a different starting point for each person.
A useful default is the head commit associated with that reviewer’s most recent completed review. Products should also make the chosen baseline visible and allow an explicit revision to be selected when the automatic choice is wrong.
## What are the limitations?
Revision diffs reduce repeat work, but they do not eliminate review judgment:
* A small code diff can have a large behavioral effect.
* Generated files and binary assets may not produce useful textual diffs.
* Base-branch changes can affect merge behavior without appearing in a head-to-head revision diff.
* A reviewer may need the full pull request context even when only a few lines changed.
* If a previous revision was not retained, a perfect historical comparison may be impossible.
Use the revision diff as an additional review lens, not a replacement for the full pull request diff.
## Frequently asked questions
### Is a revision diff the same as GitHub’s Files changed view?
No. GitHub’s default Files changed view compares the pull request with its base branch. A revision diff compares two versions of the pull request itself.
### Is a revision diff the same as reviewing new commits?
No. Reviewing commits exposes the sequence of edits. A revision diff exposes the cumulative result of those edits.
### Can I create a revision diff manually?
Yes. If you know the commit reviewed previously and the current head commit, you can compare those SHAs with Git or a provider compare page. The hard part is consistently recording the correct reviewer-specific baseline and retaining access to it.
### Why not just review every changed file again?
That works, but it spends reviewer attention proving that previously reviewed code did not change. Revision diffs concentrate attention on the part of the pull request that actually moved.
*Last reviewed July 18, 2026. Maintained by the Plannotator project.*
# Why AI-Generated Pull Requests Are Harder to Review
Source: https://docs.plannotator.ai/learn/code-review/why-ai-generated-pull-requests-are-harder-to-review
Why AI-generated pull requests are harder for teams to review, even with Codex, Cursor, and GitHub. Learn what shared context and evidence are still missing.
AI-generated pull requests are harder for teams to review when the code arrives without a shared record of the work behind it. The missing record may include the authorizing request, agent and model identity, execution state, skipped validation, and supporting evidence. Those details often remain scattered across private chats, agent sessions, CI runs, and vendor-specific interfaces.
Codex, Cursor, and GitHub Copilot are making individual review more interactive. A developer can inspect a diff beside an agent, ask why a file changed, request another review, and ask the agent to implement a finding. Those workflows make a pull request easier to explore. A team shipping a real product still needs a durable account of what the agent was asked to do, what it completed, how it checked the result, and which exact revision people are approving.
![A developer discusses a pull request with coding agents while a wider team reviews the exact revision, agent provenance, readiness state, validation evidence, and unresolved questions in one shared record.]()
![A developer discusses a pull request with coding agents while a wider team reviews the exact revision, agent provenance, readiness state, validation evidence, and unresolved questions in one shared record.]()
## Agent-native review is already useful
[Codex code review](https://openai.com/index/introducing-upgrades-to-codex/) can automatically review a GitHub pull request when it moves from draft to ready, post findings on the pull request, and respond to a focused request such as `@codex review for security vulnerabilities`. If Codex recommends an edit, the author can ask it to implement the change in the same thread. The Codex IDE extension also lets developers track and review cloud tasks without leaving the editor.
Cursor provides several review paths. Its [agent review workflow](https://cursor.com/blog/agent-best-practices) can analyze proposed edits line by line, compare local changes with the main branch, and flag issues before the work reaches GitHub. Inside a pull request, [tagging `@Cursor`](https://cursor.com/changelog/1-4) can send an instruction to a background agent that applies the fix and pushes another commit.
GitHub Copilot adds another version of this experience. Its agent sessions expose progress and logs, and Copilot-authored commits link back to those sessions. A reviewer can ask what changed, what was validated, and why. GitHub documents these capabilities in [Managing agent sessions](https://docs.github.com/en/copilot/how-tos/copilot-on-github/use-copilot-agents/manage-and-track-agents).
These tools reduce the cost of orienting yourself inside a pull request. They can explain unfamiliar code, surface likely defects, and shorten the loop between a finding and its fix. An industrial study of LLM-assisted code review found that developers generally preferred AI-led assistance for large or unfamiliar pull requests, while preferences varied with codebase familiarity and risk. The researchers favored hybrid workflows that combine proactive findings with on-demand questions and reviewer control. See [Rethinking Code Review Workflows with LLM Assistance](https://research.chalmers.se/en/publication/551186).
## A personal review conversation is not a team record
An agent chat can help one developer form a mental model. It does not automatically tell every reviewer:
* which person authorized the change;
* which agent, model, and execution system contributed to the current code;
* whether the agent is still working, blocked, waiting for a decision, or finished;
* which tests and investigations ran against the current commit;
* what the agent skipped, could not reproduce, or remains uncertain about;
* whether a screenshot, recording, or report still matches the current head;
* which parts product, security, platform, or operations have reviewed;
* what changed after each person's last completed review.
Those facts may exist somewhere. The problem is that each reviewer may have to reconstruct them from a different agent interface, pull request comment, CI page, or private conversation.
A 2026 study of 33,596 agent-created pull requests found that coding agents produced measurably different pull-request description styles and received different patterns of reviewer engagement and outcomes. The authors caution that repository norms, task type, and code complexity may explain part of the variation, so the results are not causal. The useful finding for teams is narrower: how an agent communicates its work affects the review process. See [How AI Coding Agents Communicate](https://arxiv.org/abs/2602.17084).
## Three review questions need better answers
### Which agent and model produced this change?
Git authorship can identify a bot account or the human who initiated a task. It often does not describe the full production path. One pull request may contain human edits, a Cursor background-agent commit, a Codex correction, and a generated test from another session. An agent may also switch models or delegate part of the work.
Record the agent product, execution environment, model or model family when available, initiating person, session link, and commits produced. Model identity supports audit, policy, and debugging. It does not establish quality. A newer or more expensive model can still misunderstand the request, miss a failure path, or validate the wrong behavior.
Some products already expose parts of this information. Cursor advertises an enterprise [AI code tracking API](https://cursor.com/changelog/1-4) for commit-level visibility into AI usage and accepted changes. GitHub Copilot records agent sessions and links its commits to session logs. These are useful product-specific records, but they do not create one portable metadata contract across every agent that can contribute to a GitHub pull request.
### Is the pull request actually ready for review?
GitHub supports **Draft** and **Ready for review** states. A draft pull request cannot merge and does not automatically request review from code owners. Marking it ready requests formal review. See [About pull requests](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests).
That state describes the pull request, not every agent task behind it.
| State | What it establishes | What it does not establish |
| - | - | - |
| Draft | The author is not formally requesting merge review | Whether an agent is running, blocked, complete, or waiting for a decision |
| Ready for review | The author is requesting review of the current pull request | Whether the agent met the definition of done, ran consequential checks, or disclosed open questions |
| Mergeable | Required repository checks and approvals currently allow merge | Whether the change implements the right product decision or has enough evidence for its operational risk |
A useful agent record should state **working**, **blocked**, **awaiting decision**, or **complete**, along with the definition of done and remaining work. The person presenting the pull request for review owns that status. The agent should not certify its own patch as safe to ship.
### Did the agent perform due diligence?
“Tests pass” is too vague for a consequential change. Reviewers need to know what ran, what passed, what failed, what was skipped, and which commit the results cover.
For example:
```text theme={null}
Revision: c4a912e
Validated:
- pnpm test --filter authorization: 42 passed
- pnpm typecheck: passed
- session revocation browser flow: passed, recording attached
- migration rehearsal: not run, staging database unavailable
Open question:
- queue saturation behavior remains unverified
```
The record should include repository checks, browser or device paths, migration rehearsals, security review, performance tests, and supporting [code review artifacts](/learn/code-review/what-are-code-review-artifacts) only when they apply. It should also name missing evidence. A failed or unavailable check helps a reviewer make a decision; hiding it behind a polished summary does not.
For hosted GitHub pull requests and GitLab merge requests, Plannotator's [Artifact Gallery](/learn/code-review/review-pull-request-artifacts) collects supported screenshots, video, HTML, and Markdown from the review conversation so the evidence can be inspected beside the diff.
When the agent pushes another commit, earlier evidence may become stale. The team should bind validation and artifacts to the exact revision they support. Returning reviewers can then use a [revision diff](/learn/code-review/what-is-a-revision-diff) to isolate what changed after their last completed review.
## Session logs are evidence, not the review interface
Agent session logs can be valuable. GitHub lets collaborators monitor Copilot sessions, trace commits to their sessions, and query completed work. Logs can explain which tools ran, how the agent approached the task, and where it struggled.
Requiring every reviewer to read a full transcript transfers the reconstruction work to the team. Long sessions contain exploration, repeated commands, abandoned approaches, and details unrelated to the merge decision. They may also include repository information, tool output, or customer data that requires restricted retention.
Use a compact agent work record as the index. Link to the underlying session, CI output, and artifacts when a reviewer or auditor needs them.
| Record | Required contents |
| - | - |
| Authority | Source request or approved plan, responsible person, and material deviations |
| Provenance | Agent, execution environment, model when available, session, and contributed commits |
| State | Working, blocked, awaiting decision, or complete; definition of done; remaining work |
| Revision | Repository, pull request, head SHA, and the comparison each reviewer completed |
| Validation | Exact checks, results, skipped work, failures, environment, and supported claims |
| Evidence | Screenshots, recordings, HTML, traces, benchmarks, or reports tied to the revision |
| Decision | Named reviewers, unresolved findings, accepted risks, and the final human verdict |
The [AI coding agent handoff](/learn/code-context/ai-coding-agent-handoff) can stay short for a small change. A cross-service authorization or data-migration change needs more evidence because more people must verify and operate the result.
## Better metadata does not make a broad pull request easy
A clear work record reduces archaeology. It cannot make an entangled change cheap to review.
A 2026 study of 33,707 agent-authored pull requests found that structural signals such as files changed, lines changed, and change entropy predicted high review effort far better than text features. The result supports a practical limit: presentation helps reviewers find the work, but the footprint of the change still determines much of the review cost. See [Early-Stage Prediction of Review Effort in AI-Generated Pull Requests](https://arxiv.org/abs/2601.00753).
Split independent behavior before review. Give product, security, platform, and operations owners a reading path through the code they own. Keep the summary, validation, and artifacts current as the head changes. If reviewers cannot connect a change to its authorizing request or verify its consequential behavior, the pull request is not ready merely because an agent marked its task complete.
## Review the current change as a team
Ask Codex, Cursor, Copilot, or another reviewer to explain unfamiliar paths, find issues, or implement requested fixes. Keep their findings attributed.
Route product, technical, security, and operational questions to the people who own them. Generated explanations remain claims until the code and behavior support them.
Refresh stale evidence after new pushes. The responsible reviewer then approves, requests changes, or accepts a known risk against the current revision.
## Where Plannotator fits
Open-source Plannotator can open a GitHub pull request or GitLab merge request in its browser review UI. It shows the diff, supports line-specific comments and suggestions, collects supported evidence from the hosted conversation, and can launch supported review agents. GitHub or GitLab remains the system of record.
Plannotator does not import the private agent transcript or infer that validation happened. Put the request, material decisions, validation results, and known gaps in the pull request or merge request so another reviewer can verify them.
## Frequently asked questions
### Why are AI-generated pull requests harder to review?
They can arrive faster and include more code while the request, agent provenance, execution state, validation, and evidence remain outside the pull request. Reviewers then have to reconstruct both the change and the process that produced it.
### Does GitHub show whether a pull request is a draft?
Yes. GitHub clearly distinguishes Draft from Ready for review. That status does not say whether every contributing agent is finished, whether the definition of done was met, or whether validation evidence is current.
### Should an AI-generated pull request name the model?
Record the agent, provider, model or model family when available, execution environment, initiating person, and session. Use model information for provenance and policy, not as proof that the code is correct.
### Should reviewers receive the complete agent transcript?
Usually not as the primary handoff. Provide a compact, revision-bound work record and link to the full session when its details matter. Restrict sensitive session data according to the repository's access and retention rules.
### Can Codex and Cursor review pull requests?
Yes. Codex can review GitHub pull requests, post findings, accept focused review instructions, and implement requested edits in the same thread. Cursor provides local Agent Review and can run background-agent work from GitHub pull-request instructions. Teams still need to decide how those findings, fixes, and sessions enter their shared review record.
### What should an AI coding agent include in a pull request?
Include the authorizing request, exact revision, change map, execution state, validation commands and results, skipped checks, open questions, risks, and relevant artifacts. Add agent and model provenance when available. The [agent handoff guide](/learn/code-context/ai-coding-agent-handoff) provides a reusable format.
Give reviewers a stable index into the request, current revision, validation, evidence, and unresolved work.
Connect approved intent, implementation, evidence, review, and the final team decision.
See what changed after each reviewer's last completed checkpoint.
Review screenshots, recordings, HTML, reports, and other evidence beside the diff.
*Last reviewed July 18, 2026. Maintained by the Plannotator project.*
# Learn AI-Assisted Software Planning and Review
Source: https://docs.plannotator.ai/learn/index
Practical, source-backed guides to planning and specifications, agent instructions, Markdown collaboration, code review, and AI-development workflows.
Use these guides to make plans, specifications, agent instructions, review evidence, and handoffs easier to inspect and maintain. Learn pages explain a durable question. Product commands stay in [Open Source](/open-source/), and reusable artifacts stay in [Templates](/templates/).
## Planning and specifications
Turn reviewed requirements, design, and tasks into agent work, then compare the result with implementation evidence.
Define product intent, review it with people and agents, and stop before technical design.
Choose the right planning depth, annotate the proposal, and inspect revisions before implementation.
Compare revised plans without rereading every unchanged section.
Choose durable text or an interactive explainer based on the decision readers need to make.
Move one product brief from structure to visual hierarchy to tested interaction.
Keep current system truth separate from the plans and decisions that produced it.
## Agent instructions
Give agents exact commands, boundaries, and references without creating an instruction dump.
Find repeated local feedback and turn the useful patterns into maintained instructions.
Connect returned work to the request, revision, evidence, risks, and next action.
## Markdown and document collaboration
Import a URL or render local HTML for agent feedback, or use App Notes to annotate a live page.
Connect intended behavior, implementation, validation, and current documentation.
## Code review
Return line-specific feedback from a local browser diff.
Understand cumulative review across pushes, rebases, and force-pushes.
Use screenshots, video, HTML, Markdown, and other evidence beside code.
Check whether visual and operational evidence matches the current revision.
Control review load without trusting a generated summary as proof.
## AI-development workflows
Use a neutral eight-stage model to connect intent, agent execution, evidence, shipping judgment, and learning.
Keep human attention at the points where intent becomes code and code becomes a shipping decision.
Distinguish inspectable outputs from chat responses and source records.
Recognize when more context reduces an agent's ability to use the right evidence.
Use generated repository maps without confusing them with maintained authority.
Preserve state, evidence, and stop conditions across long-running work.
Prepare a bounded goal and inspect real outputs the next morning.
*Reviewed July 29, 2026. Maintained by the Plannotator documentation team.*
# Local Diff Review for Coding Agents
Source: https://docs.plannotator.ai/learn/local-diff-review-for-coding-agents
Open local code changes in Plannotator, add line-specific comments or suggestions, and send structured feedback back to your coding agent.
Run `plannotator review` in a repository to inspect the current change set in a browser. Plannotator shows a file-oriented diff, lets you comment on exact lines or ranges, and returns the review to the agent session as structured feedback.
## Start a local review
```bash theme={null}
plannotator review
```
Most supported agents also install a review command or skill. For example, Claude Code uses `/plannotator-review`, while Codex can use `$plannotator-review` or `!plannotator review`.
Plannotator detects the repository and builds the opening review from the current VCS state. For Git, the default `since-base` view includes committed branch work, working-tree changes, and untracked files when the base branch resolves. If no base resolves, Plannotator falls back to uncommitted work instead of hiding committed changes.
The [original Plannotator demo](https://www.youtube.com/watch?v=a_AT7cEN_9I) shows the browser review loop. The current UI has expanded since that recording, so use the documentation below for present behavior.
The Git status panel separates the result into **Committed**, **Changes**, and **Untracked**. You can switch to the file tree, change the comparison, or open the session-only commit history where the repository supports it.
## Add precise feedback
Select one line or a range in the diff, then add a comment or suggested replacement. Plannotator keeps the file path, line range, and diff side with the annotation.
When you select **Send Feedback**, the agent receives a Markdown review grouped by file. A typical item identifies the file, selected line, comment, and suggested code. The agent can act on that review without reconstructing your intent from a general chat message.
Use **Approve** when the change is ready. Plannotator returns the configured code-review approval message to the active agent session. It does not commit, merge, or deploy the change.
## Stage and unstage carefully
Local Git reviews can stage or unstage supported files from the review UI. That control does not apply to every VCS provider or review mode. Do not expect it for Jujutsu, Perforce, remote-only pull request diffs, or already committed files.
## What stays local
For a local review, Plannotator starts a temporary server on `127.0.0.1` and reads the diff from the local repository. The patch is served to your browser on the same machine. Optional features can make external requests, including Ask AI, remote assets, or commands you explicitly run, but the basic local diff review does not upload the patch to a hosted Plannotator service.
## When local diff review helps
Use it when an agent changed several files, the terminal diff is hard to navigate, or your feedback needs exact line context. Repeat the review after the agent responds so you can verify the current code instead of approving from its summary.
Learn the local, pull request, merge request, VCS, and provider boundaries.
*Originally published February 19, 2026, by backnotprop. Last reviewed July 18, 2026. Maintained by the Plannotator project.*
# Plan Diff: See What Changed Between Iterations
Source: https://docs.plannotator.ai/learn/plan-diff-see-what-changed
Compare an agent's revised plan with an earlier version in rendered or raw diff views, then review only what changed.
When a coding agent resubmits a plan, Plannotator can show the lines it added and removed since the previous version. Open the diff badge to review the changed sections instead of rereading the entire plan.
Plan Diff came from community requests [#138](https://github.com/backnotprop/plannotator/issues/138) and [#111](https://github.com/backnotprop/plannotator/issues/111). The [original feature demo](https://www.youtube.com/watch?v=uIWkFCg60Lk) shows the first version of the interaction.
## Open the plan diff
Plannotator saves each arriving plan before it opens the review UI. When another version of the same plan arrives, a `+N/-M` badge appears below the document card. Select the badge to switch between the normal plan and its diff.
The automatic comparison uses the immediately previous version. Open the **Version Browser** in the sidebar to choose an older base version.
## Choose a diff view
* **Rendered** shows the plan as formatted content. Added blocks use green, removed blocks use red with strikethrough, and modified blocks use yellow.
* **Raw** shows a Git-style Markdown diff with `+` and `-` lines.
Both views come from the same line-level diff. Plannotator groups consecutive removals and additions into modified blocks so related changes stay together.
You can annotate an added, removed, or modified block. The returned feedback labels the comment as diff content so the agent knows you were responding to a revision.
## How plan versions are grouped
Plannotator derives a plan slug from the first Markdown heading, the date, and the current project. Plans with the same heading on the same day in the same project are treated as iterations of one plan. Identical resubmissions are deduplicated.
Versions are stored under the Plannotator data directory, normally:
```text theme={null}
~/.plannotator/history/{project}/{plan-slug}/
```
This history is separate from the optional decision snapshots stored under `~/.plannotator/plans/`.
The heading-and-date grouping can misclassify unusual cases. If two unrelated plans use the same first heading on the same day, inspect the selected base in the Version Browser before relying on the diff.
## Use the diff in a review loop
1. Review the first plan and select **Send Feedback**.
2. Let the agent revise and resubmit it.
3. Open the `+N/-M` badge.
4. Check whether the revision addresses your feedback and whether it introduces a new issue.
5. Approve the current plan or send another round of feedback.
Plan Diff compares stored versions on your computer. Formal authorization, synchronization between people, and cross-plan comparison are outside this local feature.
Follow the complete plan review, feedback, revision, and approval loop.
*Originally published February 22, 2026, by backnotprop. Last reviewed July 18, 2026. Maintained by the Plannotator project.*
# How to Plan with AI Coding Agents: Find Unknowns Before You Build
Source: https://docs.plannotator.ai/learn/planning/how-to-plan-with-ai-coding-agents
Plan with AI coding agents by finding unknowns, testing risky assumptions, recording deviations, and verifying the result against a clear finish line.
Plan with an AI coding agent by giving it a clear outcome, then using its codebase access to find unknowns before you commit to an implementation. Better models need shorter instructions, not less planning. Keep the goal and boundaries explicit while the plan changes as research, prototypes, and code reveal new evidence.
## Plan the decisions, not every keystroke
As coding agents improve, they can make more routine execution choices. Humans still need to decide what should be built, what must remain true, and what evidence counts as done. Anthropic's analysis of about 400,000 Claude Code sessions found that people made most planning decisions while Claude made most execution decisions. It also found that task-specific domain expertise was linked to more successful sessions. ([Anthropic](https://www.anthropic.com/research/claude-code-expertise?level=0))
This changes the useful level of detail. Describe the outcome, constraints, risky decisions, and finish line. Let the agent inspect the repository and propose the mechanical steps. Add detail when it prevents a costly mistake, not because a long plan looks thorough.
In a July 2026 interview, Claude Code engineer Thariq Shihipar said the team had cut its system prompt by 80 percent as models improved. He said many examples and absolute rules had begun to constrain newer models. This was a team-specific change, not a target for every repository. Audit `CLAUDE.md`, `AGENTS.md`, and skills for stale instructions. Keep hard constraints that still matter, and explain the reason behind softer preferences. ([Full interview](https://www.youtube.com/watch?v=aVO6E181cNU\&t=2051s), [Peter Yang's public notes](https://creatoreconomy.so/p/how-i-plan-build-and-run-loops-with-claude-code-thariq-shihipar))
| Prescriptive one-shot plan | Iterative agent planning |
| - | - |
| Assumes the first prompt contains enough context | Treats the request as the start of discovery |
| Lists detailed steps before repository research | Lets code, tests, history, and docs shape the plan |
| Hides uncertainty inside confident instructions | Names unknowns and asks the human to decide |
| Builds the full design before testing it | Prototypes the choice most likely to change |
| Treats deviation as failure to follow the plan | Records deviations as evidence for the next plan |
| Lets the builder judge its own result | Uses explicit checks and independent verification |
The right column does not mean vague delegation. It gives the agent freedom over routine execution while people keep control of product intent, irreversible choices, and final acceptance.
![A human and two coding-agent robots uncover an AI coding plan by connecting repository evidence and interview questions to three prototypes, implementation notes, a revised plan, and independent verification.]()
![A human and two coding-agent robots uncover an AI coding plan by connecting repository evidence and interview questions to three prototypes, implementation notes, a revised plan, and independent verification.]()
## Use this nine-step planning workflow
### 1. Start with the request
State the user or operator outcome, why it matters, and the boundaries the work must respect. Include hard constraints such as data handling, compatibility, permissions, migration rules, and systems the agent may change.
Do not start by dictating a file list unless the files are part of the requirement. The repository may contain a better path.
### 2. Ask for technical exploration
Have the agent inspect the relevant code, tests, documentation, recent history, prior attempts, and current runtime behavior. Ask it to report evidence before it recommends an approach.
Claude Code's official guidance describes its loop as gathering context, taking action, and verifying the result. It also recommends exploring before implementation and giving the agent something concrete to verify against. ([Claude Code documentation](https://code.claude.com/docs/en/how-claude-code-works)) The same planning pattern works with other coding agents that can inspect a repository and run its tools.
### 3. Turn unknowns into questions
Ask the agent what could change the architecture, user behavior, security boundary, migration, or validation strategy. Then have it interview you one question at a time, starting with the answer that would change the plan most.
Shihipar's public [blind-spot example](https://thariqs.github.io/html-effectiveness/unknowns/01-blindspot-pass.html) scans code and history before proposing an authentication change. His [interview example](https://thariqs.github.io/html-effectiveness/unknowns/06-interview.html) orders questions by architectural impact. The useful pattern is evidence first, then focused questions.
### 4. Prototype choices that words cannot settle
Use a small prototype, visual explainer, trace, benchmark, or reference implementation when you will only know the right choice after seeing it work. Ask for several meaningfully different options when the task involves interaction or visual judgment.
HTML is useful for interactive mockups and explainers. Markdown remains better for compact plans and durable text. The [HTML vs. Markdown guide](/learn/code-context/ai-agent-html-vs-markdown) helps choose the format.
### 5. Write the refined plan
Fold the exploration, answers, and prototype decisions into a plan. Put the choices a human might change near the top. Keep routine refactoring and plumbing concise.
Use the [AI coding plan template](/templates/ai-coding-plan) for the outcome, scope, evidence, implementation, risks, validation, and documentation. If you need a broader method with durable project state or feature specifications, use the [planning framework index](/frameworks).
### 6. Build the smallest useful proof
Test the assumption most likely to invalidate the plan. A proof might be one migration against realistic data, one API round trip, one browser interaction, or one performance measurement at a representative size.
Do not use the easiest task as the proof. Prove the part that would make you choose a different design.
### 7. Keep implementation notes
Ask the agent to record what the code revealed, where reality differed from the plan, what choice it made, and what still needs human judgment. For an unexpected but reversible detail, give it a conservative default: preserve existing behavior, data, and access; avoid a new dependency or external side effect; and log the choice.
The agent should stop when a surprise would change product behavior, security, data ownership, a public contract, or an irreversible operation. Shihipar's [implementation-notes example](https://thariqs.github.io/html-effectiveness/unknowns/09-implementation-notes.html) separates discoveries, conservative deviations, and decisions that belong to a human.
### 8. Revise the plan when the evidence changes
Planning did not fail because implementation found something new. Update the current plan, explain the deviation, and retire assumptions that no longer hold. For a material change, return to review before continuing.
Use [Plan Diff](/learn/plan-diff-see-what-changed) to compare an agent's revised plan with the earlier version. The [plan-approval guide](/learn/code-context/approve-ai-coding-plan-before-execution) covers the separate decision to approve the current plan before execution.
### 9. Verify with fresh evidence
Keep coordination, execution, and verification distinct. The coordinator preserves the goal and decisions. The builder implements them. A fresh reviewer, test harness, or domain expert checks the result without inheriting all of the builder's assumptions.
Anthropic's official loops guide recommends a second agent for code review because a reviewer with fresh context is less influenced by the main agent's reasoning. It also recommends clear stop criteria and a pilot before a large run. ([Anthropic loops guide](https://claude.com/blog/getting-started-with-loops)) Independent review still needs repository evidence and human judgment for consequential changes. The [AI software factory guide](/learn/ai-development/what-is-an-ai-software-factory) places these planning controls and evidence checks inside a repeatable delivery loop.
## Copy this planning and interview prompt
```text theme={null}
Help me plan this change before writing production code.
Outcome: [what should be true for the user or operator]
Boundaries: [systems, data, compatibility, permissions, and non-goals]
1. Inspect the relevant code, tests, docs, history, and prior attempts.
2. Report the evidence that changes how this work should be designed.
3. Find blind spots in my request. Do not claim completeness.
4. Interview me one question at a time. Ask first about answers that
would change the architecture, product behavior, or validation.
5. Suggest the smallest prototype, explainer, or test that would settle
the riskiest unknown.
6. Write a plan with the decisions I may want to change at the top,
followed by scope, implementation, risks, and validation.
7. Define a finish line. Use measurable checks where they prove the goal,
and a rubric plus human review where quality requires judgment.
8. During implementation, keep notes on discoveries and deviations.
Preserve existing behavior, data, and access when a reversible surprise
is not covered. Stop for consequential or irreversible decisions.
9. After implementation, revise the plan and return the exact checks,
artifacts, unresolved issues, and an independent verification result.
```
This prompt is a starting contract. Delete parts that do not apply. A small, reversible fix may need only the outcome, one code inspection, and a focused test.
## Choose the right finish line
Use a measurable exit condition when the measurement directly proves the requested result. Use a rubric or human judgment when the result includes taste, meaning, risk, or tradeoffs that one number cannot capture.
| Finish line | Works well for | Example | Main risk |
| - | - | - | - |
| Deterministic check | Binary behavior or contract | All migration fixtures preserve row counts and access rules | The check can omit an important case |
| Numeric threshold | Performance or bounded quality measure | p95 latency stays below 200 ms at the stated load | The agent may optimize the score instead of the experience |
| Reference match | Port, rendering, or compatibility work | Output matches a trusted implementation on a fixed corpus | The reference may not cover local requirements |
| Rubric | Design, writing, or multi-part behavior | Score accessibility, clarity, task completion, and visual fit separately | A vague rubric creates confident but inconsistent grades |
| Human decision | Product judgment or irreversible risk | An owner accepts the tradeoff after seeing the prototype and evidence | The decision can become a bottleneck if requested too often |
Anthropic recommends goal-based loops for tasks with verifiable exit criteria. In the interview, Shihipar contrasts a measurable target with visual work that needs a rubric and a separate verifier. ([Anthropic loops guide](https://claude.com/blog/getting-started-with-loops), [interview](https://www.youtube.com/watch?v=aVO6E181cNU\&t=201s))
## A blind-spot prompt is not a completeness check
An agent can search only the evidence it can reach and reason from the models it already has. If neither the human nor the agent knows what complete looks like, asking for unknown unknowns may produce a polished list that misses the real failure.
Ground the pass with:
* current code, tests, logs, migrations, and prior incidents;
* domain standards, regulations, and security or accessibility checklists;
* reference behavior and representative data;
* explicit rubrics and failure cases;
* an interview with the person who owns the problem; and
* independent verification after implementation.
Treat the blind-spot report as a research queue. Confirm each important claim against a source, a test, or a person with domain knowledge.
## Case study: plan a video workflow by removing unknowns
In Peter Yang's interview with Shihipar, the initial goal was to turn a spoken recording into a rendered video with word-level captions and overlays. Shihipar asked the agent to explain how Whisper transcription could fail, then used HTML to compare overlay styles before committing to the React and video-rendering implementation. The explainer exposed transcription risks, and the prototype made visual choices concrete. ([Interview planning segment](https://www.youtube.com/watch?v=aVO6E181cNU\&t=507s), [Peter Yang's thread](https://x.com/petergyang/status/2079209983984677210), [public episode notes](https://creatoreconomy.so/p/how-i-plan-build-and-run-loops-with-claude-code-thariq-shihipar))
The example does not prove that every plan should be HTML or that one prompt can find every unknown. It shows how an explainer or prototype can settle a specific decision before full implementation.
## Review the current plan and the returned work
Once the unknowns are small enough to proceed, review the current plan instead of an earlier draft. Open-source Plannotator can [annotate an AI coding plan](/open-source/workflows/plan-review), return feedback to the agent, and compare the next submission. The [long-horizon task guide](/learn/ai-development/what-are-long-horizon-tasks-for-ai-agents) explains how to preserve the objective, progress memory, checkpoints, and evidence when execution spans dependent stages or sessions.
Planning does not replace code review. Compare the result with the current plan, inspect the actual diff, run the finish-line checks, and make sure the implementation notes have been folded into maintained documentation.
## Frequently asked questions
### Should a coding-agent plan list every file and edit?
Only when those details expose a boundary or prevent a known mistake. Let repository exploration determine routine file edits. Keep human attention on outcomes, risky choices, constraints, and proof.
### Is this the same as Claude Code plan mode?
No. Plan mode is one product interface for proposing work before execution. This field guide describes a tool-independent discovery loop that may use plan mode, normal conversation, prototypes, tests, and implementation notes.
### When is a one-shot plan enough?
A one-shot plan can be enough for a small, familiar, reversible change with strong tests and no consequential unknown. Use the iterative loop when the task crosses systems, contains product or design judgment, changes data or access, or depends on behavior the team has not verified.
### When should the agent stop and ask a person?
It should stop when new evidence changes the intended behavior, security or privacy boundary, data ownership, public API, migration safety, cost commitment, or another hard-to-reverse decision.
*Published and last reviewed July 20, 2026. Written and maintained by the Plannotator documentation team.*
# Spec-Driven Development for AI Coding Agents
Source: https://docs.plannotator.ai/learn/planning/spec-driven-development-for-ai-coding-agents
Learn how spec-driven development turns reviewed requirements, design, tasks, and implementation evidence into durable context for AI coding agents.
**Spec-driven development for AI coding agents** turns intended software behavior into reviewable requirements, design, and work artifacts before execution. People review decisions at each boundary. Agents use the accepted artifacts to implement the change, then return evidence that people compare with the accepted intent.
Specification-driven development is another name for the same broad method. It is not one fixed file tree or one vendor workflow. The useful pattern is a controlled path from intent to implementation and back to evidence.
Microsoft describes specifications as a shared source for requirements, constraints, acceptance criteria, and edge cases before AI-assisted implementation. A 2026 research paper separates three levels of rigor: spec-first, spec-anchored, and spec-as-source. The right level depends on the cost and life of the work. ([Microsoft](https://developer.microsoft.com/blog/spec-driven-development-ai-native-engineering), [Piskala, arXiv:2602.00180](https://arxiv.org/abs/2602.00180))
![A human reviews requirements, webhook design, and implementation tasks before an abstract coding-agent process runs and returns source-diff and test evidence.]()
![A human reviews requirements, webhook design, and implementation tasks before an abstract coding-agent process runs and returns source-diff and test evidence.]()
## Use a reviewed artifact sequence
The files vary by framework, but a complete workflow must preserve five kinds of information:
1. **Requirements define observable behavior.** Record the user outcome, scope, non-goals, constraints, edge cases, and acceptance criteria. A human reviews them before technical choices narrow the solution.
2. **Design explains the chosen solution.** Record architecture, interfaces, data, failure behavior, security boundaries, and open assumptions. A human checks whether the design satisfies the requirements.
3. **A plan or task set makes the design executable.** Name the work order, dependencies, affected areas, and validation for each meaningful unit. A human checks that the tasks preserve the design intent.
4. **Implementation changes the system.** The agent follows the reviewed artifacts, reports discoveries, and stops when a new decision changes accepted behavior or risk.
5. **Evidence connects the result to the intent.** Tests, source diffs, traces, screenshots, or runtime checks show what changed. A human compares that evidence with the acceptance criteria.
This sequence does not require a large document for every change. A small, reversible fix can use a short requirement and a focused plan. A multi-phase system change needs more durable state.
### Put human review where decisions compound
Review each artifact before it becomes an input to more expensive work:
* Review requirements before design. Remove vague outcomes and decide what remains out of scope.
* Review the design before planning. Check technical assumptions, failure paths, interfaces, and operating limits.
* Review the plan or tasks before execution. Check order, task boundaries, repository scope, and verification steps.
* Review implementation evidence before acceptance. Compare the current result with the accepted requirements, not with the agent's summary.
The review depth depends on risk. Authentication, data migration, tenancy, billing, and public interfaces need more evidence than a local documentation fix.
## Compare three current specification workflows
The comparison uses current primary sources. They are [GitHub Spec Kit v0.16.1](https://github.com/github/spec-kit/blob/v0.16.1/docs/reference/workflows.md), [Kiro Specs captured August 10, 2026](https://kiro.dev/docs/specs/), and [GSD Core v1.10.0](https://github.com/open-gsd/gsd-core/blob/v1.10.0/docs/reference/planning-artifacts.md).
| Dimension | [GitHub Spec Kit](/frameworks/github-spec-kit) | [Kiro Specs](/frameworks/kiro-specs) | [GSD Core](/frameworks/gsd) |
| - | - | - | - |
| Artifact model | A feature specification, implementation plan, task list, constitution, and optional supporting artifacts | A requirements or bug-analysis file, a design file, and a tasks file | A durable `.planning/` tree with project, requirements, roadmap, state, phase context, plans, summaries, and verification records |
| Workflow | Specify, review the specification, plan, review the plan, create tasks, then implement | Requirements-first, design-first, or Quick Spec flows lead to design and tasks | Discuss a phase, plan it, execute the plan, verify the result, and update project state |
| Task grain | Stable task identifiers can include exact file paths, dependencies, and user-story groups | Tasks can form a dependency graph and run in parallel waves | Plans declare waves, dependencies, files, requirements, actions, checks, and acceptance criteria |
| Review points | Built-in gates review the specification and plan. The method in this guide adds task review before implementation. | Requirements and design flows include review. Quick Spec creates all three files without approval gates. | Phase discussion locks decisions. Plan checking, verification, and user acceptance testing inspect later stages. |
| Persistence | Teams choose whether specifications flow back into the main spec, flow forward into new specs, or remain living documents. | Feature files live in the project's `.kiro/specs/` directory. | Project and phase records preserve decisions, progress, blockers, summaries, and verification across sessions. |
| Tool coupling | An open-source CLI installs commands and templates for supported coding-agent hosts. | The workflow is part of Kiro's IDE, CLI, and web product. | An installed command system coordinates planning documents, agent work, checks, and state. |
These profiles describe artifact shape and workflow. They do not show that one framework produces better code. For a direct two-framework decision, use [GitHub Spec Kit vs. Kiro Specs](/compare/github-spec-kit-vs-kiro-specs). The [framework chooser](/frameworks/) covers other planning methods and artifact models.
## Inspect the same reliable-webhook case
The public [spec-planning-frameworks repository](https://github.com/plannotator/spec-planning-frameworks/tree/7bfffe891436c02e0b9ecccc65ceb0b64c2a0701) applies several frameworks to one [reliable-webhook-delivery brief](https://github.com/plannotator/spec-planning-frameworks/blob/7bfffe891436c02e0b9ecccc65ceb0b64c2a0701/cases/reliable-webhook-delivery/brief.md).
The brief requires signed delivery, idempotency, retry backoff with jitter, dead-letter handling, replay, audit history, tenant isolation, observability, and acceptance tests. It leaves the queue, database, web framework, signing algorithm, limits, retention, hosting, and interface decisions open.
### GitHub Spec Kit completed its planning flow
The July 19 run used Spec Kit `0.13.1.dev0` at commit `57cc518d`. It produced a constitution, checklist, research record, data model, four contracts, and quickstart. Inspect the [specification](https://github.com/plannotator/spec-planning-frameworks/blob/7bfffe891436c02e0b9ecccc65ceb0b64c2a0701/examples/github-spec-kit/raw/specs/001-reliable-webhook-delivery/spec.md), [plan](https://github.com/plannotator/spec-planning-frameworks/blob/7bfffe891436c02e0b9ecccc65ceb0b64c2a0701/examples/github-spec-kit/raw/specs/001-reliable-webhook-delivery/plan.md), and [69-task list](https://github.com/plannotator/spec-planning-frameworks/blob/7bfffe891436c02e0b9ecccc65ceb0b64c2a0701/examples/github-spec-kit/raw/specs/001-reliable-webhook-delivery/tasks.md). The run selected Fastify, PostgreSQL, and Prisma. Those are run decisions, not shared case requirements. ([Run provenance](https://github.com/plannotator/spec-planning-frameworks/blob/7bfffe891436c02e0b9ecccc65ceb0b64c2a0701/evidence/github-spec-kit/provenance.md))
### GSD created project state but not a phase plan
The run used `@opengsd/gsd-core@1.7.0`. It produced [project context](https://github.com/plannotator/spec-planning-frameworks/blob/7bfffe891436c02e0b9ecccc65ceb0b64c2a0701/examples/gsd/raw/.planning/PROJECT.md), [18 requirements](https://github.com/plannotator/spec-planning-frameworks/blob/7bfffe891436c02e0b9ecccc65ceb0b64c2a0701/examples/gsd/raw/.planning/REQUIREMENTS.md), a [five-phase roadmap](https://github.com/plannotator/spec-planning-frameworks/blob/7bfffe891436c02e0b9ecccc65ceb0b64c2a0701/examples/gsd/raw/.planning/ROADMAP.md), and [state](https://github.com/plannotator/spec-planning-frameworks/blob/7bfffe891436c02e0b9ecccc65ceb0b64c2a0701/examples/gsd/raw/.planning/STATE.md). The run then created [Phase 1 context](https://github.com/plannotator/spec-planning-frameworks/blob/7bfffe891436c02e0b9ecccc65ceb0b64c2a0701/examples/gsd/raw/.planning/phases/01-signed-idempotent-delivery/01-CONTEXT.md). The phase-plan run stalled and was interrupted. No completed plan is present. ([Run provenance](https://github.com/plannotator/spec-planning-frameworks/blob/7bfffe891436c02e0b9ecccc65ceb0b64c2a0701/evidence/gsd/provenance.md))
### Kiro is a manual, source-faithful example
The authenticated Kiro workflow was unavailable for the comparison. The repository contains three original, source-faithful files: [requirements](https://github.com/plannotator/spec-planning-frameworks/blob/7bfffe891436c02e0b9ecccc65ceb0b64c2a0701/examples/kiro-specs/manual/requirements.md), [design](https://github.com/plannotator/spec-planning-frameworks/blob/7bfffe891436c02e0b9ecccc65ceb0b64c2a0701/examples/kiro-specs/manual/design.md), and [tasks](https://github.com/plannotator/spec-planning-frameworks/blob/7bfffe891436c02e0b9ecccc65ceb0b64c2a0701/examples/kiro-specs/manual/tasks.md). Each file follows Kiro's documented artifact model. Every file states that it was not generated by Kiro. The files are inspectable workflow evidence, not vendor output. ([Example provenance](https://github.com/plannotator/spec-planning-frameworks/blob/7bfffe891436c02e0b9ecccc65ceb0b64c2a0701/evidence/kiro-specs/provenance.md))
### What this case can and cannot show
The repository compares artifact shapes and workflow evidence for one TypeScript backend case. It does not compare implemented systems, code quality, model quality, delivery time, or production reliability. A completed document also does not prove that its requirements are correct.
The framework versions used in the July run are older than the current sources in the comparison table. The generated files preserve the behavior of those pinned runs. Do not treat an unmerged benchmark branch or a local experiment as published results.
## Watch for eight failure modes
1. **Vague requirements.** Terms such as fast, reliable, secure, or scalable do not define an observable finish line.
2. **Hidden assumptions.** The specification chooses a queue, database, identity boundary, or limit without naming the decision.
3. **Stale specifications.** Code or runtime behavior changes while the document continues to describe an earlier system.
4. **Tasks that lose intent.** A task list names files and edits but drops the reason, constraint, or acceptance criterion.
5. **Ceremony larger than the work.** The framework creates more artifacts and reviews than a small, reversible change needs.
6. **Unreviewed generated detail.** An agent fills gaps with plausible architecture, limits, or edge-case behavior that nobody accepted.
7. **Source and runtime drift.** The repository, deployed system, configuration, or external service no longer matches the specification's evidence.
8. **False confidence from completion.** A complete document looks authoritative even when tests, implementation evidence, or human review are missing.
The remedy is not always more text. Name the decision, link the evidence, assign the review point, and remove artifacts that do not help a later decision.
## Choose the smallest durable artifact
### Use a technical specification for one bounded design
Choose a [technical specification](/templates/technical-specification) when one feature or system change needs requirements, interfaces, risks, and acceptance criteria in one reviewed document. This works well when the implementation can fit inside one coherent design.
### Use an AI coding plan for one implementation pass
Choose an [AI coding plan](/templates/ai-coding-plan) when the outcome and design are already known. The plan must connect ordered code changes to verification. The [planning guide](/learn/planning/how-to-plan-with-ai-coding-agents) explains how repository research and new evidence can revise that plan.
### Use a project framework for durable state
Choose a project framework when work spans phases, agents, or context windows. The framework must preserve decisions, current state, completed evidence, and the next safe action. The cost of that state must remain smaller than the cost of rebuilding context.
## Keep the specification current
Implementation exposes facts that planning cannot know. Record a discovery when it changes the work. Ask a human to review it when it changes behavior, risk, or scope.
Then choose a persistence rule. Update the main specification, create a follow-on specification, or maintain a living specification beside the code. Spec Kit documents these as flow-back, flow-forward, and living-spec policies. ([Spec Kit v0.16.1](https://github.com/github/spec-kit/blob/v0.16.1/docs/concepts/spec-persistence.md)) The [living documentation guide](/learn/code-context/living-documentation-for-ai-agents) explains how to keep current system truth separate from historical plans and decisions.
## Review the artifact before the agent runs
Open-source Plannotator can display and annotate local Markdown plans and specifications. It can return feedback to supported coding-agent sessions and compare revised submissions. Use the local [plan review workflow](/open-source/workflows/plan-review) to inspect requirements, design decisions, and tasks before execution.
```bash theme={null}
plannotator annotate specification.md --gate
```
Plannotator provides a review surface. It does not make the specification correct, execute a framework, or replace implementation evidence.
## Source record
* Method sources: Microsoft article published June 10, 2026, and arXiv:2602.00180 submitted January 30, 2026. Both were checked August 10, 2026.
* Current framework sources: GitHub Spec Kit v0.16.1, GSD Core v1.10.0, and Kiro Specs documentation updated August 4, 2026. All were checked August 10, 2026.
* Same-case evidence: `plannotator/spec-planning-frameworks` at commit `7bfffe891436c02e0b9ecccc65ceb0b64c2a0701`, dated July 19, 2026.
*Last reviewed August 10, 2026. Researched and maintained by the Plannotator documentation team.*
# What Is a Product Requirements Document? How to Write One
Source: https://docs.plannotator.ai/learn/planning/what-is-a-product-requirements-document
Learn what a product requirements document is, how to write and review one with people and coding agents, and where technical design begins.
A product requirements document, or PRD, defines the user problem, intended outcome, scope, and observable requirements for a product or feature. It answers what should change and why. It should stop before detailed technical design and the step-by-step implementation sequence.
![A product requirements document reviewed by Totman and a coding agent, with user evidence on the left and separate technical specification and implementation plan documents beyond the technical-design boundary.]()
![A product requirements document reviewed by Totman and a coding agent, with user evidence on the left and separate technical specification and implementation plan documents beyond the technical-design boundary.]()
## What belongs in a PRD
| Question | PRD answer |
| - | - |
| Who has the problem? | Named users, relevant context, and journeys |
| Why solve it? | Evidence, goals, and the outcome that matters |
| What must the product do? | Observable functional requirements and acceptance criteria |
| What quality boundary matters? | Measurable nonfunctional requirements |
| What is excluded? | Non-goals and release boundaries |
| How will the team judge the result? | Success metrics plus counter-metrics |
| What is still unknown? | Open questions with an owner or evidence path |
A useful requirement is specific enough to challenge but does not prescribe a design without cause:
```md theme={null}
FR-4. A workspace owner can choose an expiry when creating a guest link.
Acceptance: Given an owned folder, when the owner selects seven days,
then the created link shows the same expiry before it is copied.
```
The requirement describes user-visible behavior. It does not choose a database column, cache strategy, or route implementation.
## How to write a product requirements document
1. State the user problem and link the evidence that makes it worth solving.
2. Name the users and write the journeys that deliver the intended outcome.
3. Set goals, non-goals, constraints, and dependencies before listing features.
4. Write observable requirements with acceptance criteria. Keep technical choices out unless they are fixed product constraints.
5. Add success metrics, counter-metrics, and open questions with owners or evidence paths.
6. Review the full document for conflicts, undefined terms, missing failure paths, and assumptions that a coding agent could mistake for decisions.
The [product requirements document template and example](/templates/product-requirements-document) applies this sequence in copyable Markdown.
## When to use one
Use a PRD when several people or agents need a shared product boundary before technical design, especially when the work has multiple user journeys, meaningful non-goals, business or usability outcomes, or unresolved product questions.
Use a [PRFAQ](/frameworks/amazon-working-backwards-prfaq) earlier, when the team still needs to test the proposed customer value and answer the questions that could stop the idea. A PRFAQ can lead to a PRD once the product direction is clear.
Skip a separate PRD when the change is small, reversible, and already has a clear user outcome. A concise issue or coding plan may be enough. Do not create a PRD only to satisfy a process label.
## How people and coding agents should review it
People should challenge the problem, evidence, priority, user impact, risk, and success measures. Coding agents can help test internal consistency, find undefined terms, trace acceptance criteria to requirements, and identify technical questions that the PRD leaves unresolved.
Use this review sequence:
1. Restate the user problem and intended outcome without copying the summary.
2. Trace each journey to one or more requirements.
3. Mark requirements that cannot be observed or tested.
4. Check goals against non-goals, constraints, success metrics, and counter-metrics.
5. Separate product questions from technical-design questions.
6. Record open questions instead of silently filling them with agent assumptions.
An agent should not turn an ambiguous product choice into an implementation detail. It should surface the choice and request evidence or a decision.
## Where the PRD stops
| Document | Primary job | Typical detail |
| - | - | - |
| PRD | Define product intent and required outcomes | Users, journeys, scope, requirements, acceptance, metrics |
| Technical specification | Define the maintained technical behavior and design | Architecture, interfaces, data, failure behavior, security, rollout |
| Implementation plan | Sequence the current change | Files or systems, ordered steps, dependencies, risks, validation |
These boundaries are editorial guidance, not universal industry law. Teams use different names. The important test is whether readers can tell which document owns product intent, which owns technical truth, and which is the current execution sequence.
BMad Method’s pinned [PRD template](https://github.com/bmad-code-org/BMAD-METHOD/blob/717479bc3f50f38119fd958b9e577a8bde2e0184/src/bmm-skills/2-plan-workflows/bmad-prd/assets/prd-template.md) separates product vision, users, journeys, requirements, non-goals, scope, metrics, and questions from its later architecture and delivery artifacts. GitHub Spec Kit’s pinned [specification](https://github.com/github/spec-kit/blob/57cc518d63d6f10da3dd93df1ebcadda87c59374/templates/spec-template.md), [plan](https://github.com/github/spec-kit/blob/57cc518d63d6f10da3dd93df1ebcadda87c59374/templates/plan-template.md), and [tasks](https://github.com/github/spec-kit/blob/57cc518d63d6f10da3dd93df1ebcadda87c59374/templates/tasks-template.md) show a comparable separation under different names. Atlassian’s maintained [PRD guide](https://www.atlassian.com/agile/product-management/requirements) is another source-backed example of goals, assumptions, user stories, design context, and out-of-scope decisions.
Start with the [PRD template](/templates/product-requirements-document). Then use [PRD vs technical specification vs implementation plan](/compare/prd-vs-technical-specification-vs-implementation-plan) to place the downstream documents. Workspaces can [share, annotate, edit, and version the PRD](https://help.plannotator.ai/workspaces/review-plans-and-technical-decisions) with people and agents; it does not generate the document for you.
*Reviewed July 18, 2026. Written and maintained by the Plannotator documentation team.*
# Use Plannotator with Amp
Source: https://docs.plannotator.ai/open-source/agents/amp
Install Plannotator's Amp plugin and run manual code, file, and last-answer reviews from the command palette.
Amp uses a native command-palette plugin for manual Plannotator workflows. It does not intercept Amp's planning flow.
## Install
Install the [Plannotator command](/open-source/start/installation), then install the Amp plugin:
```bash theme={null}
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
```
Restart Amp or run `plugins: reload` from the command palette.
To install it only for one project, copy the file to `.amp/plugins/plannotator.ts` in that project.
## Use it
Open Amp's command palette and choose:
* **Plannotator: Review changes**
* **Plannotator: Review changes or PR**
* **Plannotator: Annotate file**
* **Plannotator: Annotate last answer**
Leave the URL blank in **Review changes or PR** to review local changes.
Last verified against Plannotator OSS v0.25.0 on July 27, 2026. Maintained by the Plannotator project.
# Use Plannotator with Claude Code
Source: https://docs.plannotator.ai/open-source/agents/claude-code
Install Plannotator for Claude Code, review plans at ExitPlanMode without making Claude wait, invoke document and code review skills, and update the plugin.
Plannotator opens Claude Code's plans in a review UI in your browser. **Approve** lets Claude implement the plan. **Send Feedback** returns your annotations so Claude can revise it.
How Claude waits for your decision depends on the Claude Code version:
* **Claude Code 2.1.287 or later, in the interactive terminal:** the [Plannotator mod](#the-plannotator-mod) is on by default. Claude does not wait. Your decision arrives later as a message.
* **Older Claude Code, `claude -p` and SDK runs, Windows, or the mod turned off:** a hook holds `ExitPlanMode` open, and Claude waits until you decide.
## Install
Install the command:
```bash theme={null}
curl -fsSL https://plannotator.ai/install.sh | bash
```
Then run these commands in Claude Code:
```text theme={null}
/plugin marketplace add backnotprop/plannotator
/plugin install plannotator@plannotator
```
Restart Claude Code so the plugin takes effect. The standard installer also adds three Claude-specific skills: `plannotator-review`, `plannotator-annotate`, and `plannotator-last`. It writes them to `~/.claude/skills`. If `$CLAUDE_CONFIG_DIR` is set, it uses `$CLAUDE_CONFIG_DIR/skills` instead.
The marketplace plugin supplies plan review and the Plannotator mod. The skills supply the three manual slash commands and call the installed `plannotator` binary. The plugin does not include the binary. See [Install and Manage Plannotator Skills](/open-source/start/skills) for extra skills and model-callable settings.
## Use it
Enter plan mode and ask Claude Code to prepare a plan. When Claude calls `ExitPlanMode`, Plannotator opens the plan. **Approve** allows implementation. **Send Feedback** returns your annotations and direct edits to Claude for another revision.
Use the installed skills for manual workflows:
```text theme={null}
/plannotator-review
/plannotator-annotate path/to/spec.md
/plannotator-last
```
`/plannotator-review` accepts a GitHub pull request or GitLab merge request URL. `/plannotator-annotate` accepts a file, folder, or web URL.
## The Plannotator mod
On Claude Code 2.1.287 or later, in the interactive terminal, the plugin runs the Plannotator mod. It is on by default.
When Claude calls `ExitPlanMode`, or you run `/plannotator-review`, `/plannotator-annotate` or `/plannotator-last`, Plannotator opens in your browser and Claude ends its turn. Claude does not wait for you:
* You can keep chatting with Claude while the review is open.
* When you decide, your decision arrives in the session as a message from the Plannotator plugin. Claude continues from there.
* If Claude revises the plan while the review is open, the same tab updates to the new version. Your comments stay.
* After you approve a plan, Claude calls `ExitPlanMode` once more and works from the exact plan text you approved.
* Claude can open Plannotator itself with its `plannotator` tool, for example when you ask it to "open notes.md in Plannotator". A `plannotator review`, `annotate` or `last` command that Claude runs in Bash opens the same way.
* Ask AI in the review is answered by this Claude session. See [Ask this session](/open-source/workflows/ask-this-session).
* The status line shows the reviews that are waiting for you.
* A review stays open if you close the terminal. Resume the session, for example with `claude --continue`, and the decision is delivered.
While a plan review is open, Claude is not blocked. If you leave plan mode yourself before you approve, Claude can start editing.
Keep the `plannotator` binary up to date as well: rerun the installer. With an older binary, plan review falls back to the waiting flow.
The mod is part of the marketplace plugin. A [manual hook](#manual-hook-setup) always uses the waiting flow.
### Turn the mod off
Set `PLANNOTATOR_CLAUDE_MOD=0` in the shell that starts Claude Code, or in the `env` block of Claude Code's `settings.json`. You can also add this to `~/.plannotator/config.json`:
```json theme={null}
{ "claudeCodeMod": false }
```
The environment variable wins over the config file. Claude Code reads the setting when it starts, so restart Claude Code after you change it. With the mod off, Claude waits for your decision, and Ask AI uses a provider you pick.
## Update
Rerun the standard installer to update the `plannotator` binary and the core skills. The marketplace plugin updates separately. Refreshing the marketplace alone does not update an installed plugin.
From a terminal:
```bash theme={null}
claude plugin marketplace update plannotator
claude plugin update plannotator@plannotator
```
Then restart Claude Code.
Or, inside Claude Code, run:
```text theme={null}
/plugin marketplace update plannotator
```
Then open `/plugin`, go to **Installed**, select **plannotator**, and choose **Update now**. Restart Claude Code.
Claude Code has no `/plugin update` command.
## Manual hook setup
If you do not use Claude Code's plugin system, add this hook to `~/.claude/settings.json`. With a manual hook, Claude waits for your decision on every Claude Code version.
```json theme={null}
{
"hooks": {
"PermissionRequest": [
{
"matcher": "ExitPlanMode",
"hooks": [
{
"type": "command",
"command": "plannotator",
"timeout": 345600
}
]
}
]
}
}
```
Last verified against Plannotator OSS v0.25.1 on July 31, 2026. The Plannotator mod, Ask this session, and update sections were checked against Plannotator v0.28.0 on October 4, 2026, and the update steps were verified on Claude Code 2.1.289. Maintained by the Plannotator project.
# Use Plannotator with Codex
Source: https://docs.plannotator.ai/open-source/agents/codex
Enable Plannotator's Codex Stop hook, review plans after they render, and invoke review skills or shell commands.
Codex plan review uses the experimental `Stop` hook. Plannotator reads the latest plan after the turn renders. Feedback asks Codex to continue the same turn and revise the plan.
## Install
On macOS, Linux, or WSL, run:
```bash theme={null}
curl -fsSL https://plannotator.ai/install.sh | bash
```
When Codex is installed or its home already contains user configuration, the installer enables hooks and writes the Plannotator `Stop` hook. Restart Codex Desktop after installation.
The installer stores hook configuration under `$CODEX_HOME`. If `$CODEX_HOME` is not set, it uses `~/.codex`. The installer stores the shared `plannotator-review`, `plannotator-annotate`, and `plannotator-last` skills under `~/.agents/skills`. `$CODEX_HOME` does not change that location.
Codex hooks are currently disabled on Windows. The Windows installer does not enable the plan-review hook.
## Use it
When a Codex turn ends with a plan, Plannotator opens automatically. Approval leaves the completed turn as-is. Feedback returns a continuation reason so Codex can revise the plan.
Use shell commands for manual workflows:
```text theme={null}
!plannotator review
!plannotator annotate path/to/spec.md
!plannotator last
```
You can also invoke `$plannotator-review`, `$plannotator-annotate`, or `$plannotator-last`.
See [Install and Manage Plannotator Skills](/open-source/start/skills) for the optional skills, specific-skill installation, updates, and removal.
## Update
Rerun the standard installer. It replaces the binary and shared core skills, then updates its managed Codex `Stop` hook without replacing a custom Plannotator hook wrapper.
## Check manual hook configuration
Codex requires the feature flag in `~/.codex/config.toml` or a repository's `.codex/config.toml`:
```toml theme={null}
[features]
hooks = true
```
The adjacent `hooks.json` can contain:
```json theme={null}
{
"hooks": {
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "/absolute/path/to/plannotator",
"timeout": 345600
}
]
}
]
}
}
```
Use an absolute command path for Codex Desktop because app-launched processes may not inherit your shell `PATH`.
Last verified against Plannotator OSS v0.25.1 on July 31, 2026. Maintained by the Plannotator project.
# Use Plannotator with Copilot CLI
Source: https://docs.plannotator.ai/open-source/agents/copilot-cli
Install Plannotator's Copilot CLI plugin for plan interception, code review, and document annotation.
The Copilot CLI plugin intercepts `exit_plan_mode` and opens the plan in Plannotator before Copilot continues.
## Install
Install the `plannotator` command with the [standard installer](/open-source/start/installation). Then run these commands in Copilot CLI:
```text theme={null}
/plugin marketplace add backnotprop/plannotator
/plugin install plannotator-copilot@plannotator
```
Restart Copilot CLI.
## Review a plan
Press `Shift+Tab` to enter Copilot CLI plan mode. When Copilot writes `plan.md` and calls `exit_plan_mode`, the plugin opens Plannotator. Approval lets Copilot continue. Feedback returns your annotations so the plan can be revised.
## Manual commands
```text theme={null}
/plannotator-review
/plannotator-review https://github.com/owner/repo/pull/123
/plannotator-annotate path/to/spec.md
/plannotator-last
```
`/plannotator-last` reads Copilot CLI's session event log. That log format is controlled by Copilot CLI and may change between versions.
Last verified against Plannotator OSS v0.25.0 on July 27, 2026. Maintained by the Plannotator project.
# Use Plannotator with Droid
Source: https://docs.plannotator.ai/open-source/agents/droid
Install Plannotator's Droid plugin for manual code review, file annotation, and last-message review.
The Droid plugin provides manual review commands. It does not intercept Droid's planning flow.
## Install
Install the [Plannotator command](/open-source/start/installation), then run:
```bash theme={null}
droid plugin marketplace add https://github.com/backnotprop/plannotator
droid plugin install plannotator@plannotator
```
## Use it
```text theme={null}
/plannotator-review
/plannotator-review https://github.com/owner/repo/pull/123
/plannotator-annotate path/to/spec.md
/plannotator-annotate docs/
/plannotator-last
```
The plugin expects `plannotator` on `PATH`. It opens the local browser UI and returns the submitted result to the Droid session.
Last verified against Plannotator OSS v0.25.0 on July 27, 2026. Maintained by the Plannotator project.
# Use Plannotator with Gemini CLI
Source: https://docs.plannotator.ai/open-source/agents/gemini-cli
Configure Gemini CLI plan review and install Plannotator's review and annotation commands.
The standard installer configures Gemini CLI's policy, `BeforeTool` hook, and Plannotator commands when it detects `~/.gemini`.
## Requirements and installation
Use Gemini CLI 0.36.0 or later. Then run the [standard Plannotator installer](/open-source/start/installation).
The installer adds:
* `~/.gemini/policies/plannotator.toml`, which allows `exit_plan_mode` without a separate terminal confirmation
* a `BeforeTool` hook in `~/.gemini/settings.json`
* `/plannotator-review` and `/plannotator-annotate` command files under `~/.gemini/commands`
Restart Gemini CLI after installation.
The `.toml` files are native Gemini CLI commands, not Agent Skills.
The standard installer also writes Plannotator's shared core skills under `~/.agents/skills` for hosts that read that location. Before you copy or remove either file type, read [Install and Manage Plannotator Skills](/open-source/start/skills#understand-host-specific-files).
## Review a plan
Run `/plan` in Gemini CLI. When the agent calls `exit_plan_mode`, the hook reads the plan and opens Plannotator. Approval lets the agent continue. Feedback returns your annotations for revision.
## Manual commands
```text theme={null}
/plannotator-review
/plannotator-review https://github.com/owner/repo/pull/123
/plannotator-annotate path/to/spec.md
```
If Gemini CLI was installed after Plannotator, rerun the Plannotator installer so it can add the Gemini-specific files.
Rerun the installer to update the native command files, policy, and managed hook entry, then restart Gemini CLI.
Last verified against Plannotator OSS v0.25.1 on July 31, 2026. Maintained by the Plannotator project.
# Choose Your Agent
Source: https://docs.plannotator.ai/open-source/agents/index
Choose a supported coding agent, editor, or note app and follow its Plannotator setup guide.
Choose the coding agent you already use. Its guide shows how to install Plannotator, open plans, annotate files, and review code.
## Coding agents
| Agent | Plan review | Open manually |
| - | - | - |
| [Claude Code](/open-source/agents/claude-code) | Marketplace plugin intercepts `ExitPlanMode` | Core skills appear as slash commands |
| [Codex](/open-source/agents/codex) | Experimental post-render `Stop` hook on macOS, Linux, and WSL | Shell commands and shared Agent Skills |
| [OpenCode](/open-source/agents/opencode) | `@plannotator/opencode` provides `submit_plan` | Installer-managed native command files |
| [Copilot CLI](/open-source/agents/copilot-cli) | Marketplace plugin intercepts `exit_plan_mode` | Plugin slash commands |
| [Gemini CLI](/open-source/agents/gemini-cli) | Installer adds a `BeforeTool` hook for `exit_plan_mode` | Native TOML command files |
| [Pi](/open-source/agents/pi) | `@plannotator/pi-extension` provides plan mode | Extension slash commands |
| [Amp](/open-source/agents/amp) | Manual only | Amp plugin command palette |
| [Droid](/open-source/agents/droid) | Manual only | Droid plugin slash commands |
| [Kiro CLI](/open-source/agents/kiro-cli) | Manual only | Kiro-specific skills and example custom agent |
Read [Install and Manage Plannotator Skills](/open-source/start/skills) for the core and extra skill lists, exact locations, and specific-skill commands.
## Editors and notes
* [VS Code](/open-source/agents/vscode) opens Plannotator sessions in editor tabs and can send selected-code annotations into an active code review.
* [Zed](/open-source/agents/zed) opens the current local review file from Plannotator.
* [Obsidian and Bear](/open-source/agents/notes) save plans to a note app from Plannotator's settings and plan-review UI.
* [Octarine](/open-source/agents/octarine) saves plans to a named Octarine workspace and folder.
Start with [Installation](/open-source/start/installation) if the `plannotator` command is not installed yet.
Last verified against Plannotator OSS v0.25.1 on July 31, 2026. Maintained by the Plannotator project.
# Use Plannotator with Kiro CLI
Source: https://docs.plannotator.ai/open-source/agents/kiro-cli
Install Plannotator's Kiro CLI skills and example custom agent for manual document and code review.
The standard installer adds Kiro-specific review skills and an example custom agent when it detects `kiro-cli` or `~/.kiro`. The current setup uses manual skills rather than a transparent plan hook.
## Install
Run the [standard Plannotator installer](/open-source/start/installation). If you install Kiro later, rerun the installer.
The installer adds:
* `plannotator-review` and `plannotator-annotate` under `~/.kiro/skills`
* `plannotator-setup-goal` and `plannotator-visual-explainer` under `~/.kiro/skills`
* an example agent at `~/.kiro/agents/plannotator.json`
An existing `~/.kiro/agents/plannotator.json` is not overwritten.
The standard installer gives Kiro two normally optional skills: `plannotator-setup-goal` and `plannotator-visual-explainer`. It does not install `plannotator-compound` for Kiro. See [Install and Manage Plannotator Skills](/open-source/start/skills) for the complete matrix.
## Use the example agent
```bash theme={null}
kiro-cli chat --agent plannotator
```
The agent exposes the installed skills as `skill://` resources. You can add the same resources to your own Kiro custom agent instead.
Rerun the standard installer to update the managed Kiro skill copies. Your existing `~/.kiro/agents/plannotator.json` remains unchanged.
Last verified against Plannotator OSS v0.25.1 on July 31, 2026. Maintained by the Plannotator project.
# Save Plannotator Plans to Obsidian or Bear
Source: https://docs.plannotator.ai/open-source/agents/notes
Configure Plannotator to save plans to an Obsidian vault or Bear notes.
Plannotator can save plans to Obsidian or Bear. Configure the note app from the review UI's settings.
## Obsidian
1. Open **Settings** in a plan review.
2. Enable Obsidian.
3. Select an auto-detected vault or enter its path.
4. Choose the destination folder. The default is `plannotator`.
Saved Markdown includes YAML frontmatter with creation time, source, and tags. Plannotator derives tags from the plan title and code languages and adds a `[[Plannotator Plans]]` backlink.
## Bear
Enable Bear in **Settings**. Plannotator creates a Bear note with the plan title and body. It adds generated tags or the custom tags you configure.
Bear support is available on macOS because it uses Bear's local URL scheme.
These note actions save a copy of the plan. The agent's source plan and Plannotator's local history remain separate.
Plannotator also supports [Octarine](/open-source/agents/octarine), which requires a workspace name and uses Octarine's local URL scheme.
Last verified against Plannotator OSS v0.25.0 on July 27, 2026. Maintained by the Plannotator project.
# Save Plannotator Plans to Octarine
Source: https://docs.plannotator.ai/open-source/agents/octarine
Configure Plannotator to save plans to a named Octarine workspace and folder.
Plannotator can create an Octarine note from the current plan. This support uses Octarine's local `octarine://` URL scheme.
## Configure Octarine
1. Open **Settings** in a plan review.
2. Enable Octarine.
3. Enter the exact Octarine workspace name.
4. Choose a folder inside that workspace. The default is `plannotator`.
The workspace name is required. Plannotator cannot save the note when this field is empty.
## Save a plan
After you configure Octarine, use the note save action in the review UI to save a plan manually. To save plans automatically, enable **Auto-save on Plan Arrival**. Plannotator creates the note when the plan loads, before you approve or deny it.
Plannotator creates a fresh note in the configured workspace and folder without opening the note. Octarine adds the `.md` extension to the generated filename.
The saved note starts with YAML frontmatter containing:
* generated tags from the plan and project
* `Status: Draft`
* `Author: plannotator`
* a `Last Edited` timestamp
This action saves a copy. The agent's source plan and Plannotator's local history remain separate.
Last verified against Plannotator OSS v0.25.0 on July 27, 2026. Maintained by the Plannotator project.
# Use Plannotator with OpenCode
Source: https://docs.plannotator.ai/open-source/agents/opencode
Add the Plannotator OpenCode plugin, choose its planning workflow, and install manual review commands.
The OpenCode plugin gives configured planning agents a `submit_plan` tool. The default `plan-agent` workflow exposes it to OpenCode's built-in `plan` agent.
## Install the plugin
Add Plannotator to `opencode.json`:
```json theme={null}
{
"$schema": "https://opencode.ai/config.json",
"plugin": ["@plannotator/opencode@latest"]
}
```
Restart OpenCode.
Run the standard installer if you also want `/plannotator-review`, `/plannotator-annotate`, and `/plannotator-last`:
```bash theme={null}
curl -fsSL https://plannotator.ai/install.sh | bash
```
These are native OpenCode Markdown command files. On macOS, Linux, and WSL, the installer uses `${XDG_CONFIG_HOME:-$HOME/.config}/opencode/commands`. On Windows PowerShell and Command Prompt, it uses `%USERPROFILE%\.config\opencode\commands`. They are separate from Plannotator's Agent Skills. See [Install and Manage Plannotator Skills](/open-source/start/skills#understand-host-specific-files) for the artifact differences.
## Review a plan
Use OpenCode's `plan` agent. When it calls `submit_plan`, Plannotator opens the plan in the browser. Approval lets the agent continue. Feedback returns structured annotations for revision.
By default, `submit_plan` is not exposed to `build` or other primary agents.
## Choose a workflow
Use the expanded plugin entry when you need a different scope:
```json theme={null}
{
"$schema": "https://opencode.ai/config.json",
"plugin": [
["@plannotator/opencode@latest", {
"workflow": "plan-agent",
"planningAgents": ["plan", "sisyphus"]
}]
]
}
```
Supported workflows:
| Workflow | Behavior |
| - | - |
| `plan-agent` | Exposes `submit_plan` to `plan` and names in `planningAgents`. This is the default. |
| `manual` | Does not register `submit_plan`. Use Plannotator commands when needed. |
| `user-managed` | Registers the tool without modifying prompts or permissions. |
| `all-agents` | Exposes the tool broadly to primary agents. This preserves the older behavior. |
Keep options inside the two-item Plannotator plugin entry. Do not add the options object as a separate item in the `plugin` array.
OpenCode uses the plugin's embedded server under Bun. In Node-based or wrapped environments, it falls back to the installed `plannotator` command.
## Switch agents after a review
Plannotator can ask OpenCode to switch agents after plan approval or code-review feedback. Choose the target from the approval menu or Settings.
When you have not saved a choice, plan approval switches from the planning agent to `build`, while code-review feedback stays on the current agent. After you save a choice, that target is shared by both surfaces.
Plannotator checks the configured target against OpenCode's current agent list before delivery. If the target is missing or cannot be checked, Plannotator shows a warning. It still approves the plan or sends the feedback. It skips the agent switch and does not send the stale target to OpenCode.
## Ask this session
On OpenCode 2, Ask AI in code review, annotate, and `/plannotator-last` is answered by your OpenCode session. It is the only Ask AI option there. In plan review, the session is waiting for your plan decision, so it gives a quick answer from its context only, and nothing is added to the conversation. OpenCode 1 and remote sessions use a separate provider that you pick. See [Ask this session](/open-source/workflows/ask-this-session).
## Update
Rerun the standard installer to update the binary and native command files. It clears cached Plannotator plugin packages for OpenCode 1 and OpenCode 2. Clearing the OpenCode 2 cache is new in Plannotator 0.28.0. Restart OpenCode so the configured `@plannotator/opencode@latest` entry reloads.
Last verified against Plannotator OSS v0.25.1 on July 31, 2026. The Ask this session and update sections were checked against Plannotator v0.28.0 on October 4, 2026. Maintained by the Plannotator project.
# Use Plannotator with Pi
Source: https://docs.plannotator.ai/open-source/agents/pi
Install and update the Plannotator Pi extension, review plans without making the agent wait, and use code review, document annotation, and last-message review.
Pi uses its own Plannotator extension. You do not need the standard Plannotator installer for this setup. The extension provides Pi's plan tool and slash commands; it does not install Plannotator's standalone core or extra Agent Skills.
## Install
```bash theme={null}
pi install npm:@plannotator/pi-extension
```
Pi 0.79.1 or later is required.
## Enter plan mode
Start Pi in plan mode:
```bash theme={null}
pi --plan
```
You can also run `/plannotator-plan-mode` or press `Ctrl+Alt+P` during a session. Both toggle plan mode.
In plan mode, the agent writes a Markdown plan and calls `plannotator_submit_plan`. Plannotator opens the plan for approval or annotated feedback. After approval, Pi enters execution mode and tracks checklist progress.
## Plan review does not make the agent wait
Since Plannotator 0.28.0, the agent does not wait while you review. When the review opens, the agent ends its turn. Your decision arrives later as a message.
* You can keep chatting with the agent while the review is open.
* The agent still cannot change code. Planning restrictions stay on until you approve.
* If the agent revises the plan while the review is open, the open tab updates to the new version and keeps your comments.
* Pressing Esc in Pi no longer cancels an open plan review. To abandon a review, leave plan mode with `/plannotator-plan-mode` or `Ctrl+Alt+P`. Leaving plan mode closes the open review.
## Ask this session
In plan review, code review, annotate, and `/plannotator-last`, Ask AI is answered by your Pi session. It is the only Ask AI option there, so there is no provider picker. Your question shows in Pi's chat. If the agent is busy, choose **Ask when it finishes** or **Interrupt and ask now**. In remote mode, you pick a separate provider instead. See [Ask this session](/open-source/workflows/ask-this-session).
## Hand an approved plan to another extension
Pi uses automatic in-session execution by default. Set `executionMode` in the global or project config:
1. `~/.pi/agent/plannotator.json`
2. `/.pi/plannotator.json`
The project config overrides the global config.
```json theme={null}
{
"executionMode": "external"
}
```
After approval, external mode completes these actions in order:
1. Restores the model, thinking level, and active tools from before planning.
2. Returns Plannotator to idle.
3. Emits `plannotator:plan-approved` with this payload:
```ts theme={null}
{
cwd: string;
planFilePath: string;
planContent: string;
feedback?: string;
}
```
A companion extension can listen to that Pi event and own execution. Plannotator does not enter its executing phase or track checklist progress in external mode. Tools from other extensions remain available. Plannotator disables only the tools that it enabled.
## Manual commands
```text theme={null}
/plannotator-review
/plannotator-annotate path/to/spec.md
/plannotator-last
```
`/plannotator-review` uses the detected Git, GitButler, or Jujutsu provider. Pass `--git` or `--gitbutler` to force one. GitButler review requires `but` 0.21.0 or later on `PATH`.
## Try without installing
```bash theme={null}
pi -e npm:@plannotator/pi-extension
```
## Update
If you also use the standard Plannotator installer, rerunning it updates the extension when `pi` is on your `PATH`. Otherwise, update from Pi:
```bash theme={null}
pi update --extensions
```
This updates your installed Pi packages, Plannotator included. A plain `pi update` updates only Pi itself. To update only Plannotator, run `pi update npm:@plannotator/pi-extension`. Restart Pi after updating.
Last verified against Plannotator OSS v0.25.1 on July 31, 2026. The plan review, Ask this session, and update sections were checked against Plannotator v0.28.0 on October 4, 2026. Maintained by the Plannotator project.
# Open Plannotator in VS Code
Source: https://docs.plannotator.ai/open-source/agents/vscode
Open Plannotator plan and code reviews in VS Code tabs and add editor selections to the active review.
The Plannotator VS Code extension redirects review sessions opened from an integrated terminal into VS Code tabs. It works alongside your coding-agent setup.
## Install
Install Plannotator from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=backnotprop.plannotator-webview) or [Open VSX](https://open-vsx.org/extension/backnotprop/plannotator-webview). Use Open VSX for VSCodium and editors that install extensions from that registry. VS Code 1.85.0 or later is required.
Install and configure Plannotator for your coding agent, then open a new VS Code integrated terminal. Terminals created before the extension activates do not receive the browser-routing environment variable.
## Use it
Launch a plan, document, or code review from the integrated terminal. The extension opens the local Plannotator URL in a VS Code tab instead of an external browser.
The extension also provides:
* **Plannotator: Open URL** to open a local Plannotator URL manually
* **Plannotator: Add Annotation** to add the current editor selection to the active review
* `Cmd+Shift+.` on macOS or `Ctrl+Shift+.` on Windows and Linux as the default keybinding for adding an editor annotation
Plannotator follows the current VS Code color theme. Review panels close after you approve or submit feedback.
## Remove the extension
Choose one removal method:
1. In VS Code, run:
```bash theme={null}
code --uninstall-extension backnotprop.plannotator-webview
```
Add `--profile ""` for a named profile.
2\. Open the **Extensions** view, find Plannotator, open its settings menu, and select **Uninstall**.
Use the Extensions view in VSCodium or another Open VSX editor. [VSCodium uses Open VSX](https://github.com/VSCodium/vscodium/blob/master/docs/extensions.md#how-to-use-the-open-vsx-registry) in that view by default. Restart the editor's extension host when prompted.
The extension stores its virtual Plannotator cookie jar in editor-managed `globalState` under the key `plannotator-cookies`. It does not provide a command to clear that record, so the record can remain after uninstall.
Do not delete the editor's shared profile or state database. These stores contain data from other extensions.
See [Remove Plannotator](/open-source/start/installation#remove-plannotator) for the complete executable, agent, skill, runtime, and local-data cleanup.
## If the external browser still opens
1. Confirm `plannotatorWebview.injectBrowser` is enabled.
2. Open a new integrated terminal.
3. Launch the agent from that terminal and start the review again.
Last verified against Plannotator OSS v0.25.1 on July 31, 2026. Maintained by the Plannotator project.
# Open review files in Zed
Source: https://docs.plannotator.ai/open-source/agents/zed
Open the current local Plannotator review file in Zed or Zed Preview.
Plannotator can open the current local file in Zed from plan review, document annotation, and code review.
## Use it
1. Open a local Plannotator review.
2. Open the **Open in...** menu on the document or code file.
3. Choose **Zed**, or choose **Zed Preview** on macOS to open the document in the preview build.
Plannotator lists Zed only when it detects an installed application or executable. On macOS, **Zed Preview** appears as a separate choice when that app bundle is installed. Linux and Windows use the regular `zed` executable for preview builds too, so they use the existing Zed entry.
## Availability
Opening a file in Zed requires a local source path.
The action is unavailable in these cases:
* a remote session
* a pull-request review without a local checkout
* a deleted file
* a committed GitButler Stack or Branch view that does not match the live workspace
Last verified against Plannotator OSS v0.25.0 on July 27, 2026. Maintained by the Plannotator project.
# Artifact Server: A Local Workspace for AI Agent Artifacts
Source: https://docs.plannotator.ai/open-source/artifact-server
Browse, edit, annotate, and organize files created by AI agents in one local workspace with MCP and OpenAPI access.
Artifact Server is a local, source-available workspace for files created or used by AI agents. It organizes these files into projects where you can review them and connect them to Kanban work.
Agents connect through MCP or its checked OpenAPI contract. Artifact Server is experimental and built for one person using local files and local agents. It has no accounts or cloud service.
Inspect the source, setup instructions, MCP reference, and HTTP API contract.
![AI agents bring HTML, Markdown, images, video, and reports into one local Artifact Server workspace organized by project and Kanban work.]()
![AI agents bring HTML, Markdown, images, video, and reports into one local Artifact Server workspace organized by project and Kanban work.]()
## What Artifact Server does
* Organizes artifacts into projects.
* Links existing files without copying them.
* Stores new files when Artifact Server should own the bytes.
* Previews and edits HTML, Markdown, images, video, audio, PDFs, text, and other files.
* Keeps browser comments with each artifact.
* Tracks work on a four-column Kanban board.
* Exposes 11 MCP tools and an OpenAPI contract.
Use Artifact Server when agent output is spread across repositories, project folders, downloads, or temporary locations and you need one local place to find and inspect it.
## Link existing files or publish new ones
A **linked artifact** points to a file that already lives on your computer. The original file remains the source of truth. Editing it through Artifact Server writes to that file, and conflict checks prevent an older view from silently overwriting a newer external edit.
A **managed artifact** stores its bytes in Artifact Server. Use this when an agent creates a report, prototype, image, recording, or other output that does not have a permanent home yet.
Both kinds of artifacts use the same project tree, viewers, editor, annotations, downloads, and Kanban connections.
## Review agent output in the browser
Self-contained HTML opens in a sandboxed viewer. Relative CSS, JavaScript, images, fonts, and media work when the files are indexed at matching project paths. Markdown uses Plannotator's packaged viewer and editor. Images, video, audio, PDFs, text, and unknown binary files have built-in previews or raw downloads.
Comments stay in Artifact Server for human reference. Artifact Server does not send them back to an agent or turn them into a review submission.
## Connect agents through MCP
The local server exposes MCP over Streamable HTTP:
```text theme={null}
http://127.0.0.1:7337/mcp
```
Agents can discover projects, search and read artifacts, link local files, publish managed files, repair moved links, and manage Kanban cards. Start with `artifact_list_projects`. Prefer `artifact_link` when a useful file already exists on disk. Use `artifact_publish` when Artifact Server should own the file.
## Run Artifact Server
Artifact Server requires Node.js 22 or newer and pnpm.
```bash theme={null}
git clone https://github.com/plannotator/artifact-server.git
cd artifact-server
pnpm install
pnpm build
pnpm start
```
Open [http://127.0.0.1:7337](http://127.0.0.1:7337). Artifact Server stores its catalog and managed files under `~/.plannotator/artifact-server/` by default.
## Local and source-available
Artifact Server runs on your computer. Linked files remain in their current folders. Managed files, annotations, and Kanban state stay in its local data directory.
Artifact Server is source-available, not OSI open source. It is free for individuals, nonprofits, education, public research, work solely on public OSI-licensed projects, and 30-day company evaluations. Other for-profit organizational use requires a commercial license. Read the [complete license](https://github.com/plannotator/artifact-server/blob/main/LICENSE.md) before use.
## How it relates to Plannotator
[Plannotator OSS](/open-source/) reviews plans, documents, and code with coding agents. Artifact Server focuses on finding and working with the wider set of files agents produce. The projects share document-viewing and annotation foundations but remain separate products.
Learn more about the broader category in [What is an AI artifact?](/learn/ai-development/what-is-an-ai-artifact).
*Last verified against the Artifact Server repository on July 19, 2026. Maintained by the Plannotator project.*
# Set Up the Plannotator Inbox for Your Coding Agents
Source: https://docs.plannotator.ai/open-source/inbox
Start the Plannotator Inbox, connect Claude Code, Codex, Pi, OpenCode, or another MCP client, and answer agent questions without holding a session open.
The Plannotator Inbox is one local window on your computer where agents leave you messages, questions, files, and guided reviews. You answer when you can. No agent waits on the Inbox, so a session keeps working or ends its turn after it writes.
When you press **Send**, your reply goes back to the session that asked.
## Prerequisites
* A coding agent: Claude Code, Codex, Pi, OpenCode, or another MCP client.
* Plannotator on the same computer. Run `plannotator --version` and verify `v0.28.9` or later.
## Set up the Inbox
Run the installer. It also updates an existing install.
```bash theme={null}
curl -fsSL https://plannotator.ai/install.sh | bash
```
```powershell theme={null}
irm https://plannotator.ai/install.ps1 | iex
```
See [Install Plannotator](/open-source/start/installation) for other options.
```bash theme={null}
plannotator inbox
```
The Inbox starts and opens in your browser. Run it once before you connect an agent: the first run writes the file that the Claude Code, Pi, and OpenCode connections look for when a session starts.
After that, you do not need to keep the Inbox running. An agent that writes to a stopped Inbox starts it in the background, without opening a tab.
Use the [Plannotator plugin](/open-source/agents/claude-code) on Claude Code 2.1.287 or later, and [update the plugin](/open-source/agents/claude-code#update) if you installed it earlier. Its Plannotator mod adds a `plannotator_inbox` tool, which is on by default.
**Quit and restart Claude Code.** Claude Code adds the tool when it starts, so a session that started before your first `plannotator inbox` does not have it. A new conversation inside a running Claude Code is not enough.
The mod does not run in `claude -p`, SDK runs, or on Windows. There, connect Claude Code through MCP like Codex: `claude mcp add --scope user plannotator-inbox -- plannotator inbox mcp`.
Use the [Pi extension](/open-source/agents/pi) or the [OpenCode plugin](/open-source/agents/opencode). Their Inbox tool is off by default. Turn it on with one of these:
* In the Inbox, open **Settings** and turn the switch on for Pi or OpenCode.
* Set the environment variable before you start the agent:
```bash theme={null}
export PLANNOTATOR_INBOX_TOOL=1
```
Then start a new Pi session (or run `/reload`), or restart OpenCode.
Add `plannotator inbox mcp` as an MCP server. For Codex:
```bash theme={null}
codex mcp add plannotator-inbox -- plannotator inbox mcp
```
Restart Codex after you add it. The command also adds the server to the Codex app and IDE extension.
For Cursor, VS Code, Gemini CLI, Zed, and other clients, open the Inbox and use the client picker on its first screen or in **Settings**. It shows the exact command, config snippet, or install link for each client, with the full path to your `plannotator` binary. Apps started from the Dock might not see your shell `PATH`, so prefer that full-path version.
In a new session, ask your agent:
```text theme={null}
Send me a test message in my Plannotator Inbox.
```
A thread appears in the Inbox. Type a reply and press **Send**.
## How it works
* **Threads by project.** Each agent session writes to its own thread unless the agent names a thread to join. The sidebar groups threads by project: the repository, or the folder when there is no repository.
* **Questions and Send.** Questions appear as cards. Click to pick an answer. Your picks save at once, and **Send** delivers your picks, your words, and any file annotations as one reply.
* **Replies wake the session.** With Claude Code, Pi, or OpenCode 2, your reply arrives in the session that asked as a new turn once the session is idle. It never interrupts a running turn. Codex and other MCP clients are not woken: the agent reads your reply with the `wait_for_reply` or `read_thread` tool.
* **Local by default.** The Inbox binds `127.0.0.1` and stores everything under `~/.plannotator/inbox/` (or `$PLANNOTATOR_DATA_DIR/inbox/`). To open it from your other devices, see [Open the Inbox over your tailnet](#open-the-inbox-over-your-tailnet).
## How to use it
* Hand off long work and let the agent leave its questions in the Inbox instead of stopping to wait for you.
* Get decisions while you are away from the terminal, then answer several threads in one pass.
* Review files the agent attached, and annotate them before you reply.
* Read guided reviews of a code change, section by section.
At first, ask your agent to use the Inbox by name, for example "leave your open questions in my Plannotator Inbox". With an MCP-only agent, also tell it to wait for your reply.
Use a plan review or `plannotator annotate` instead when you need a decision before the agent continues.
## Open the Inbox over your tailnet
Requires Plannotator `v0.28.10` or later.
If you use Tailscale, you can open the Inbox from your phone, tablet, or another computer on your tailnet. See [Review Plannotator sessions over Tailscale](/open-source/tailscale) for Tailscale setup and HTTPS certificates.
Turn it on in one of two ways:
* Run `plannotator inbox --tailscale`. It publishes until the Inbox stops and works with `--background` and `--no-open`. If the Inbox is already running, the command asks it to publish.
* In the Inbox, open **Settings** and turn on **Over your tailnet**. The switch stays on, so the Inbox publishes at every start, also when an agent starts it. You can turn it on only from this computer.
On the other device, open the address that the command prints and **Settings** shows: `https://..ts.net:/`, where the port is the Inbox's own port.
* **Tailnet only.** The Inbox stays bound to `127.0.0.1`. Tailscale Serve publishes it over HTTPS inside your tailnet. The Inbox never uses Tailscale Funnel.
* **Only your login.** The Inbox lets in only the Tailscale login that owns this computer. It refuses other logins and tagged devices.
* **Agents stay local.** MCP and the reply wake answer only on this computer, never over the tailnet.
* **Tailscale unavailable.** If Tailscale is missing or signed out, the Inbox still runs on this computer, and **Settings** shows why it could not publish.
* **Hard off.** `PLANNOTATOR_INBOX_TAILSCALE=0` keeps it off, even with `--tailscale` or the switch.
To let in another login, for example your own login on a shared tailnet, add it to `~/.plannotator/config.json`:
```json theme={null}
{ "inboxTailscaleAllow": ["you@example.com"] }
```
An allowed login can reply and send **New messages**. Both run as turns in your agent sessions on this computer, where agents run commands. Allow only people you would let run your agents. Anyone who holds your unlocked phone while it is signed in to Tailscale has the same access.
To stop publishing, turn the switch off or quit the Inbox. The Inbox removes the address when it stops or restarts. After a hard kill or a reboot, the address stays in Tailscale until the Inbox starts again. To remove it sooner, run `tailscale serve --https= off`. To keep a published Inbox running after you close the terminal, start it with `plannotator inbox --background --tailscale`.
If you followed the earlier manual workaround, remove that mapping with `tailscale serve --https=443 off`. It exposes the whole Inbox, including its agent tools, to everyone on your tailnet. The Inbox detects it, refuses requests through it, and **Settings** offers to replace it with the owner-only address.
## Troubleshooting
* **My agent does not see the Inbox tool.** Run `plannotator inbox` once, then fully restart Claude Code or OpenCode, or start a new Pi session. On Pi and OpenCode, also turn the tool on. When `PLANNOTATOR_INBOX_TOOL` is set, it decides for every agent and overrides **Settings**.
* **Codex does not write to the Inbox.** Codex has no built-in Inbox tool. Add the MCP server with `codex mcp add plannotator-inbox -- plannotator inbox mcp`, then restart Codex.
* **My reply did not arrive.** A reply waits until the session is idle. MCP-only agents must read it with `wait_for_reply` or `read_thread`, so ask the agent to check.
* **I cannot open the Inbox from my phone.** Sign in to Tailscale with the same login on both devices, check that Tailscale is signed in on this computer, and check that **Over your tailnet** is on in **Settings**.
* **The Inbox address changed.** When its last port is taken, the Inbox starts on a new port and shows a notice. MCP connections through `plannotator inbox mcp` follow the change. Allow browser notifications again at the new address.
* **I want to stop the Inbox.** Press `Ctrl+C` in the terminal that runs it. For a background Inbox, find its process ID with `grep '"pid"' ~/.plannotator/inbox/inbox.json` and run `kill `. The next agent that writes starts it again.
For every command, setting, MCP tool, and file on disk, see the [Inbox reference](https://plannotator.ai/docs/reference/inbox/).
Last verified on October 9, 2026, against Plannotator `v0.28.10`. Maintained by the Plannotator project.
# Plannotator OSS Documentation
Source: https://docs.plannotator.ai/open-source/index
Install Plannotator, annotate plans and documents, review code changes, and return feedback to your coding agent.
Plannotator is an open-source, local feedback tool for coding agents. It opens plans, Markdown, HTML, local code changes, pull requests, and merge requests in a visual interface, then returns your annotations and feedback to the agent.
The `plannotator` binary runs a temporary server on your computer and opens the session in your browser. Plannotator supports Claude Code, Codex, OpenCode, Copilot CLI, Gemini CLI, Pi, Amp, Droid, and Kiro CLI through host-specific hooks, plugins, commands, or skills.
Install, update, or remove the binary and connect your coding agent.
Deploy the deprecated OSS share portal and paste service when compatibility requires them.
Compare core and extra skills, choose specific skills and hosts, and manage updates.
Open Markdown, mark what should change, and send feedback to your coding agent.
Review local code changes and return line-specific feedback to your coding agent.
Use the deprecated OSS sharing flow, retained for compatibility, and import returned annotations.
Set up Claude Code, Codex, OpenCode, Copilot CLI, or another supported agent.
Start it from your coding agent or run it directly.
## Plans and documents
Use Plannotator to select text, request deletions, attach comments or images, edit Markdown, and send structured feedback. Plan reviews can also show what changed after the agent revises the plan.
Review a plan before the agent starts implementation.
Annotate documents, plain-text config and data files, URLs, and folders.
Annotate rendered local HTML and understand its security boundary.
## Review code
`plannotator review` opens local Git, Jujutsu, GitButler, or Perforce changes. You can also pass a GitHub pull request or GitLab merge request URL. Plannotator shows the diff, accepts line comments and suggestions, and returns your feedback to the agent session.
Review committed branch work, working-tree changes, and untracked files where the current VCS supports them.
Open GitHub and GitLab reviews from their URLs and choose local or API-only review.
## Where data goes
Normal local sessions bind to `127.0.0.1`. Plannotator stores plans, history, drafts, configuration, and session records under its data directory. This directory is `~/.plannotator` by default. Plannotator uses an absolute `XDG_DATA_HOME` only when `~/.plannotator` does not exist.
Remote mode binds to `0.0.0.0`. The review UI and local APIs do not add user authentication. Use SSH port forwarding or a trusted private network.
Plannotator OSS does not send usage telemetry or analytics. Its app surfaces check GitHub automatically for the latest release, and a local Git review can contact its configured `origin`. Optional features can contact URL, provider, AI, sharing, or hosted services. See [Privacy and data flow](/open-source/reference/privacy-and-data-flow) for the details.
Plannotator is dual-licensed under [MIT](https://github.com/backnotprop/plannotator/blob/main/LICENSE-MIT) or [Apache 2.0](https://github.com/backnotprop/plannotator/blob/main/LICENSE-APACHE). Source code, releases, and issue tracking are in [`backnotprop/plannotator`](https://github.com/backnotprop/plannotator).
Last verified on July 31, 2026, using Plannotator product commit `7cd023c`. Maintained by the Plannotator project.
# Plannotator CLI reference
Source: https://docs.plannotator.ai/open-source/reference/cli
Commands and flags for reviewing changes, annotating files and URLs, reopening sessions, and reading saved plan decisions.
The `plannotator` command opens a local review session in your browser. Run `plannotator --help` for the help text shipped with your installed version.
## Review code changes
```bash theme={null}
plannotator review [--git | --gitbutler] [--local | --no-local] [PR_URL]
```
With no URL, Plannotator reviews changes in the current repository. It detects Git, GitButler, Jujutsu, or Perforce. Use `--git` or `--gitbutler` to override detection. GitButler support requires `but` 0.21.0 or later; see the [GitButler workflow guide](/open-source/workflows/gitbutler) for detection, views, and limits. Jujutsu is detected through the installed `jj` command and does not have a separate flag.
Pass a GitHub pull request or GitLab merge request URL to review it. Plannotator prepares a local checkout by default so it can show complete files. Use `--no-local` for a diff-only review.
```bash theme={null}
plannotator review
plannotator review --git
plannotator review --gitbutler
plannotator review https://github.com/owner/repo/pull/123
plannotator review --no-local https://gitlab.com/group/project/-/merge_requests/42
```
## Annotate a file, URL, or folder
```bash theme={null}
plannotator annotate ]
```
Markdown and supported plain-text files open as documents. Local HTML renders as HTML by default; `--markdown` converts it to Markdown. A folder opens the supported document files it contains. Local files are limited to 2 MiB.
URLs use Jina Reader by default. `--no-jina` uses a direct fetch followed by local HTML-to-Markdown conversion.
`--gate` adds an Approve action. `--json` writes a machine-readable decision to standard output. `--hook` implies `--gate` and writes the hook-native block/pass contract described in [Hooks](/open-source/reference/hooks).
`--require-approval` and `--result-file ` are strict automation options. They work only with direct `annotate --gate --json` calls and cannot be combined with `--hook`.
* `--require-approval` exits `0` only for approval. Annotations or dismissal exit `1`.
* `--result-file ` publishes the same newline-terminated JSON record written to stdout.
* Invalid flags, startup failures, and result-publication failures exit `2`.
* The result path is resolved from the current working directory. Its parent must already exist, and the destination must not exist, including as a dangling symlink.
The strict result is one of `{"decision":"approved"}`, `{"decision":"approved","feedback":""}`, `{"decision":"annotated","feedback":""}`, or `{"decision":"dismissed"}`.
Plannotator writes the decision to stdout before publishing the result file. Result publication uses a same-directory temporary file with `0600` permissions where supported and an atomic no-overwrite link. This prevents replacement of an existing destination, but it does not guarantee persistence after a system crash.
## Annotate the last agent message
```bash theme={null}
plannotator annotate-last [--stdin] [--gate] [--json] [--hook]
plannotator last [--stdin] [--gate] [--json] [--hook]
```
The command reads the last assistant message from a supported agent session. Use `--stdin` to supply the text yourself:
```bash theme={null}
printf '%s' "$message" | plannotator annotate-last --stdin
```
`last` is an alias for `annotate-last`.
## Reopen a running session
```bash theme={null}
plannotator sessions
plannotator sessions --open
plannotator sessions --open 2
plannotator sessions --clean
```
`sessions` lists live local servers. `--open [N]` opens the numbered session, with session 1 as the default. `--clean` removes stale session records.
## Read saved plan decisions
```bash theme={null}
plannotator archive
```
This opens the read-only archive for decisions saved under `/plans/`. The default is `~/.plannotator/plans/`; see [Configuration](/open-source/reference/configuration#where-settings-live) for data-directory resolution.
## Goal setup commands
```bash theme={null}
plannotator setup-goal [--json]
```
This command belongs to the installed `/goal` workflow. `interview` opens goal questions; `facts` opens the facts acceptance view. Pass `-` to read the bundle JSON from standard input.
## Global options and hook-only commands
* `--browser ` selects a browser, application, or executable for this run. It can appear with any command.
* `--version` and `-v` print the installed version.
* `plannotator improve-context` is called by an installed agent hook. It reads a hook event from standard input and is not intended for direct use.
Running `plannotator` without arguments also belongs to hook integration and expects JSON on standard input. For an interactive session, choose `review`, `annotate`, `last`, `archive`, or `sessions` explicitly.
## Installation lifecycle
Use the operating-system installer to install or update Plannotator.
```bash theme={null}
plannotator uninstall [--dry-run] [--purge]
```
`plannotator uninstall` removes the installed executable and Plannotator-managed integrations. Use `--dry-run` to inspect the removal plan without changing files. Use `--purge` to include local data. Read [Remove Plannotator](/open-source/start/installation#remove-plannotator) before you use `--purge`. That procedure explains safeguards, retained files, and residual state.
Agent Skills and host plugins have separate lifecycles. See [Install and Manage Plannotator Skills](/open-source/start/skills) before removing a `/plannotator-*` entry, because the same visible command can be backed by a skill, a native command file, or a plugin.
Last verified against Plannotator OSS v0.25.1 on July 31, 2026. Maintained by the Plannotator project.
# Configure Plannotator
Source: https://docs.plannotator.ai/open-source/reference/configuration
How Plannotator combines command flags, environment variables, config.json, and browser UI settings.
Plannotator has four settings layers. Use command flags for one run, environment variables for a shell or host integration, `config.json` for persistent runtime behavior, and the Settings panel for review UI preferences.
## Where settings live
Plannotator chooses its data directory in this order:
1. `PLANNOTATOR_DATA_DIR`, with leading `~` expansion
2. An existing `~/.plannotator` directory
3. `$XDG_DATA_HOME/plannotator` when `XDG_DATA_HOME` is an absolute path
4. `~/.plannotator`
When `PLANNOTATOR_DATA_DIR` is relative, Plannotator resolves it from the process's launch working directory. The same value can select several directories when installers, agents, or shells start from different locations. Use an absolute value when several hosts share one configuration.
Before you delete data, identify each working directory that launched Plannotator. Resolve `PLANNOTATOR_DATA_DIR` from each directory. Apply the deletion safety checks to every resulting absolute path.
It does not implicitly use `~/.local/share/plannotator` when `XDG_DATA_HOME` is unset. An existing `~/.plannotator` continues to win over XDG so an upgrade does not silently move your data.
The persistent runtime config is `/config.json`. At the default location, that is:
```text theme={null}
~/.plannotator/config.json
```
Plannotator treats a missing file as an empty config. If the JSON is malformed, it prints a warning and uses defaults.
## Precedence
The narrowest setting wins:
1. A command flag, when the command supports one
2. An environment variable
3. A value in `config.json`
4. The built-in default
For example, URL conversion resolves in this order: `--no-jina`, `PLANNOTATOR_JINA`, `jina` in `config.json`, then the default of enabled.
The Settings panel uses a related but separate rule. Settings that Plannotator syncs to the server prefer `config.json`, then the browser cookie, then the built-in default. Changes in the panel update the cookie immediately and write the supported fields back to `config.json`.
## Runtime config file
This example shows every supported top-level config key. You only need to include values you want to change.
```json theme={null}
{
"displayName": "Avery",
"prompts": {},
"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 }
],
"verifyAttestation": false,
"jina": true,
"annotateHistory": true,
"guideHistory": true,
"pfmReminder": false,
"glimpse": true,
"share": "enabled",
"cursorSandbox": true,
"claudeCodeMod": true
}
```
### Supported diff values
| Setting | Values |
| - | - |
| `diffStyle` | `split`, `unified` |
| `overflow` | `scroll`, `wrap` |
| `diffIndicators` | `bars`, `classic`, `none` |
| `lineDiffType` | `word-alt`, `word`, `char`, `none` |
| `defaultDiffType` | `since-base`, `uncommitted`, `unstaged`, `staged`, `merge-base`, `all` |
| `lineBgIntensity` | `subtle`, `normal`, `strong` |
`conventionalLabels` replaces the built-in comment labels. Set it to `null` to restore the defaults.
`annotateHistory` stores a copy of each annotated local file under the data directory so later sessions can show a version diff. Set it to `false` if you do not want that history written.
`guideHistory` defaults to `true` and stores successful Guided Reviews and their section progress. Set it to `false` to stop new guide writes. Existing guides remain on disk.
`cursorSandbox` defaults to `true` and controls whether Plannotator passes `--sandbox enabled` to Cursor review jobs. Set it to `false` only when Cursor's sandbox cannot start on your system.
`claudeCodeMod` defaults to `true` and controls the [Plannotator mod](/open-source/agents/claude-code#the-plannotator-mod) on Claude Code 2.1.287 or later. Set it to `false` to turn the mod off, so Claude waits for your decision. `PLANNOTATOR_CLAUDE_MOD` overrides it. Claude Code reads it when it starts, so restart Claude Code after a change.
`verifyAttestation` is also a valid config key, but only the installer reads it. When enabled, installation requires an authenticated GitHub CLI and verifies build provenance after the checksum.
## Browser UI settings
The Settings panel stores UI preferences in a browser cookie because Plannotator sessions use changing local ports. The cookie can be shared across those ports on the same host.
The server-synced settings are your display name, diff options, conventional comments, and custom comment labels. Other interface choices, such as theme, layout, panel state, and file browser preferences, remain in the browser cookie.
Some functional cookies do not use a `plannotator-` prefix. Current examples include `plannotator.agents`, `review-split-ratio`, and `update-dismissed-version`; Plannotator can also read the legacy `review-diff-style` cookie. Pull request review state uses other browser stores. Hidden artifact choices use `localStorage` keys named `plannotator-pr-artifacts:hidden:`, and review-submission recovery can use tab-scoped `sessionStorage`.
To remove browser state, close every Plannotator review and share tab first. In each browser profile, clear full site data for every exact Plannotator origin and port you used, including `http://localhost:`, alternate local or remote origins, and `https://share.plannotator.ai` when applicable. If the browser groups cleanup by hostname, clearing `localhost` can also remove data for unrelated local applications. Browser cleanup does not delete `config.json`, saved plans, or annotation history from disk.
### Change the theme
Open the header menu, select **Settings**, then open **Theme**. Choose **Light**, **Dark**, or **System**, then choose a color theme. The mode and color theme are browser preferences, so they can differ between browsers.
When Plannotator opens inside the VS Code extension, it follows the current VS Code color theme. See [VS Code](/open-source/agents/vscode).
### Close the tab after a decision
Open **Settings > General > Auto-close Tab**. The default is **Off**, which keeps the completion page open after you send feedback, approve, or close a session. You can instead close it immediately, after three seconds, or after five seconds.
## Prompt customization
The `prompts` object in `config.json` changes supported feedback messages returned to the calling agent after a decision. It does not replace the instructions used by launched AI review jobs. See [Customize Feedback](/open-source/reference/custom-feedback) for supported paths, keys, placeholders, defaults, and precedence.
## Environment variables
Environment variables are the right layer for remote mode, a fixed port, a browser choice, or behavior set by an agent host. See [Environment variables](/open-source/reference/environment-variables).
`PLANNOTATOR_AI=disabled` is an environment-only kill switch. It removes Ask AI, Review Agents, and Guided Review from the UI and disables provider and review-job execution without disabling ordinary reviews.
Last verified on July 31, 2026, using Plannotator product commit `7cd023c`. Maintained by the Plannotator project.
# Customize Feedback
Source: https://docs.plannotator.ai/open-source/reference/custom-feedback
Change the messages Plannotator returns after plan, document, and code-review decisions.
Add feedback templates under `prompts` in Plannotator's `config.json`. Plan and document feedback use the `plan` and `annotate` sections. Code review uses the separate `review` section.
The file is `/config.json`. The data directory is normally `~/.plannotator`, but `PLANNOTATOR_DATA_DIR` or an absolute `XDG_DATA_HOME` can change it. Plannotator reads the file again when it generates the next supported feedback message, so you do not need to restart it.
## Plan and document feedback
Use `prompts.plan` for an agent's plan-review decision:
```json theme={null}
{
"prompts": {
"plan": {
"denied": "Revise the plan, address every item below, then call {{toolName}} again.\n\n{{feedback}}",
"approvedWithNotes": "The plan is approved with these implementation notes:\n\n{{feedback}}"
}
}
}
```
Keep `{{feedback}}` in a template that should return your annotations. If you remove it, the template still runs, but the exported annotations are omitted from the message.
| Key | Used when | Available placeholders | Built-in behavior |
| - | - | - | - |
| `plan.denied` | You request changes to an agent plan | `{{toolName}}`, `{{planFileRule}}`, `{{feedback}}` | Requires the agent to revise every submitted item before resubmitting and preserves the plan title unless asked to change it. |
| `plan.approved` | You approve a plan without notes | `{{planFilePath}}`, `{{doneMsg}}` | Tells the agent to execute the approved plan. OpenCode uses a shorter built-in message. |
| `plan.approvedWithNotes` | You approve a plan and include notes | `{{planFilePath}}`, `{{doneMsg}}`, `{{feedback}}`, `{{proceedSuffix}}` | Returns the approval plus your implementation notes. `{{proceedSuffix}}` is populated only by the OpenCode flow when it should start implementation. |
| `plan.autoApproved` | A non-interactive flow approves automatically | None | Reports that the plan was auto-approved and tells the agent to continue. |
Use `prompts.annotate` when a supported agent wrapper formats annotations on a file, folder, or assistant message:
```json theme={null}
{
"prompts": {
"annotate": {
"fileFeedback": "{{fileHeader}} notes for {{filePath}}:\n\n{{feedback}}",
"messageFeedback": "Revise your response using these notes:\n\n{{feedback}}",
"approvedWithNotes": "Approved. Continue without revising the reviewed content solely because of these notes.\n\n{{contextBlock}}{{feedback}}"
}
}
}
```
| Key | Used when | Available placeholders | Built-in behavior |
| - | - | - | - |
| `annotate.fileFeedback` | An agent wrapper returns file or folder annotations | `{{fileHeader}}`, `{{filePath}}`, `{{feedback}}` | Labels the result as Markdown annotations, identifies the file or folder, and asks the agent to address the feedback. |
| `annotate.messageFeedback` | An agent wrapper returns annotations on the latest assistant message | `{{feedback}}` | Labels the result as message annotations and asks the agent to address them. |
| `annotate.approved` | No verified current user path | None | Plannotator accepts this config key, but no current feature reads it. |
| `annotate.approvedWithNotes` | A supported agent wrapper returns approval with non-blocking notes | `{{feedback}}`, `{{context}}`, `{{contextBlock}}` | Reports approval, passes the notes, and tells the agent not to revise or reopen the reviewed content solely because of them. |
The annotation transport determines whether Plannotator applies a template:
| Transport | Template behavior | Approval behavior |
| - | - | - |
| OpenCode and Pi wrappers | Apply configurable feedback and approved-with-notes templates | No-notes approval does not use `annotate.approved` |
| Direct `plannotator annotate` and `plannotator annotate-last` commands | Return exported feedback without templates | Plain-text approval is fixed to `The user approved.` |
| Structured JSON | Returns structured decisions without templates | Can return approval notes as `feedback` |
| Hook-native output | Returns the hook-native block or pass contract | Cannot return approval notes |
## Code-review feedback
Use `prompts.review` for the result of `plannotator review`, including local changes, pull requests, and merge requests:
```json theme={null}
{
"prompts": {
"review": {
"approved": "# Code Review\n\nNo changes requested. Continue with the agreed next step.",
"denied": "\n\nValidate each submitted finding against the code and report your verdict before changing anything."
}
}
}
```
| Key | Used when | Placeholders | Built-in behavior |
| - | - | - | - |
| `review.approved` | You approve a code review | None | Returns a Code Review heading and says that no changes were requested. |
| `review.denied` | You send code-review annotations | None | Appends instructions to validate only the submitted findings, report evidence and a verdict for each one, and discuss them before changing code. |
A `review.denied` override replaces only the built-in suffix. It leaves the annotations unchanged. Plannotator adds the suffix only when the submitted review has annotations.
These settings do not change the instructions used by Ask AI or by an AI review job launched inside code review. Those jobs use their own prompts and any enabled global Agent Skills.
## Agent-specific overrides
Place an override under `runtimes` inside the relevant section:
```json theme={null}
{
"prompts": {
"plan": {
"denied": "Revise the plan using this feedback:\n\n{{feedback}}",
"runtimes": {
"opencode": {
"denied": "Update the plan, then call {{toolName}}:\n\n{{feedback}}"
}
}
},
"review": {
"runtimes": {
"codex": {
"approved": "# Code Review\n\nNo changes requested."
}
}
}
}
}
```
Supported runtime names are `claude-code`, `amp`, `droid`, `kiro-cli`, `opencode`, `copilot-cli`, `pi`, `codex`, and `gemini-cli`.
For any key, Plannotator chooses the first non-blank string in this order:
1. `prompts..runtimes..`
2. `prompts..`
3. A built-in value for that runtime, when one exists
4. The built-in general value
An empty or whitespace-only string is treated as unset. A misspelled or unavailable `{{placeholder}}` remains unchanged in the returned message. A missing or malformed config file falls back to built-in behavior; malformed JSON also writes a warning to standard error.
## Placeholder values
| Placeholder | Value at runtime |
| - | - |
| `{{feedback}}` | Your exported annotations or notes. |
| `{{toolName}}` | The agent action used to resubmit a plan, such as `ExitPlanMode`, `submit_plan`, `exit_plan_mode`, or `plannotator_submit_plan`. |
| `{{planFileRule}}` | A file-location instruction when the current plan flow supplies one; otherwise an empty string. |
| `{{planFilePath}}` | The current plan's backing-file path when supplied by the agent flow. |
| `{{doneMsg}}` | Optional save-path or checklist text supplied by the agent flow. |
| `{{proceedSuffix}}` | Optional OpenCode text that tells the agent to start implementation; empty in other current flows. |
| `{{fileHeader}}` | `File` or `Folder`. |
| `{{filePath}}` | The annotated file or folder path. |
| `{{context}}` | A short description of the approved source when the wrapper supplies one. |
| `{{contextBlock}}` | `{{context}}` followed by two newlines, or an empty string. |
## Check your change
1. Add a short marker such as `[custom-plan-feedback]` to one template.
2. Run the matching supported flow. For example, request a plan change for `plan.denied`, send an annotated code review for `review.denied`, or annotate a file through OpenCode, Pi, or Amp for `annotate.fileFeedback`.
3. Make sure that the returned message contains the marker and the expanded placeholders.
4. Remove the marker after you identify the selected key and runtime.
If the marker does not appear, make sure that the configuration path, JSON syntax, runtime name, and selection order are correct. See [Configuration](/open-source/reference/configuration) and [Environment variables](/open-source/reference/environment-variables) for the data-directory setting.
Last verified against Plannotator OSS v0.25.0 on July 27, 2026. Maintained by the Plannotator project.
# Plannotator environment variables
Source: https://docs.plannotator.ai/open-source/reference/environment-variables
Runtime, browser, remote-session, sharing, installer, and agent environment variables supported by Plannotator.
Use environment variables when a setting belongs to a shell, remote machine, or agent. Values set for one command affect only that run:
```bash theme={null}
PLANNOTATOR_PORT=19432 plannotator review
```
## Session and browser
| Variable | Accepted value and behavior |
| - | - |
| `PLANNOTATOR_REMOTE` | **Values:** `1` or `true` forces remote mode. `0` or `false` forces local mode.
**Default:** Detect SSH from `SSH_TTY` or `SSH_CONNECTION`. | | `PLANNOTATOR_URL_HOST` | **Values:** A hostname, IPv4 address, bracketed IPv6 address, or `auto`.
**Effect:** Changes the advertised remote URL without changing the server bind address.
**Auto:** Uses the Tailscale MagicDNS name, then exactly one Tailscale IPv4 address.
**Precedence:** The environment value overrides `urlHost` in `config.json`. | | `PLANNOTATOR_PORT` | **Values:** A fixed port such as `19432`, or a range such as `19432-19463`.
**Default:** A random available port locally and `19432` remotely. | | `PLANNOTATOR_BROWSER` | **Value:** A browser app name or path on macOS, or an executable on Linux and Windows.
**Precedence:** The CLI `--browser` flag wins. | | `BROWSER` | **Effect:** Supplies the fallback browser command when `PLANNOTATOR_BROWSER` is unset.
**No browser:** `none`, `false`, `0`, and `:` do not launch one. | | `PLANNOTATOR_GLIMPSE` | **Values:** `1` or `true` enables the Glimpse window when available. Other values disable it.
**Default:** Enabled. | | `PLANNOTATOR_GLIMPSE_WIDTH` | **Effect:** Sets the initial Glimpse window width.
**Default:** `1280`. | | `PLANNOTATOR_GLIMPSE_HEIGHT` | **Effect:** Sets the initial Glimpse window height.
**Default:** `900`. | Remote mode binds the unauthenticated local server to `0.0.0.0`. Forward it through SSH or your development environment and do not expose that port to an untrusted network. See [Troubleshooting](/open-source/troubleshooting#remote-ssh-and-development-containers). Use [Tailscale remote reviews](/open-source/tailscale) for tailnet-only HTTPS access that keeps the server on `127.0.0.1`. See [Remote access](/open-source/remote-access) for trusted private networks, SSH, development containers, and opening a session from another device. ## Annotation, history, and sharing | Variable | Accepted value and behavior | | - | - | | `PLANNOTATOR_JINA` | **Values:** `1` or `true` uses Jina Reader. Other values use direct fetch and local conversion.
**Precedence:** The `--no-jina` flag wins. | | `JINA_API_KEY` | Optional bearer token sent to Jina Reader. | | `PLANNOTATOR_ANNOTATE_HISTORY` | **Values:** `1` or `true` saves per-file annotation history. Other values disable it.
**Default:** Enabled. | | `PLANNOTATOR_GUIDE_HISTORY` | **Values:** `1` or `true` saves successful Guided Reviews. Other values disable new writes.
**Default:** Enabled.
**Existing data:** Saved guides remain readable. | | `PLANNOTATOR_SHARE` | **Values:** `disabled` hides sharing. Any other value enables it.
**Precedence:** Overrides `share` in `config.json` for integrations that use Plannotator's shared configuration resolver. An explicit OpenCode `share` setting takes precedence over this variable. | | `PLANNOTATOR_SHARE_URL` | **Effect:** Sets the share portal base URL.
**Default:** `https://share.plannotator.ai`. | | `PLANNOTATOR_PASTE_URL` | Paste API used for encrypted short links and raw HTML sharing. | The portal and paste-service deployment variables are documented in [Self-host Plannotator's deprecated share services](/open-source/self-hosting#deployment-variables). ## Files, diagnostics, and local tools | Variable | Accepted value and behavior | | - | - | | `PLANNOTATOR_DATA_DIR` | **Effect:** Selects the data directory for configuration, plans, history, sessions, and installed runtime state.
**Path:** Expands a leading `~`. Resolves a relative value from the launch working directory.
**Default:** An existing `~/.plannotator`, then an absolute `$XDG_DATA_HOME/plannotator`, then `~/.plannotator`. | | `PLANNOTATOR_FILE_BROWSER_MAX_FILES` | **Value:** A positive integer.
**Effect:** Limits files returned by the file browser.
**Default:** `5000`. | | `PLANNOTATOR_SEM_PATH` | Explicit path to the optional `sem` semantic-diff binary. | | `PLANNOTATOR_GIT_TIMEOUT_MS` | **Value:** A timeout in milliseconds.
**Use:** Set it only when you diagnose an unusually slow repository. | | `PLANNOTATOR_DEBUG` | Any non-empty value enables additional diagnostic output. | | `PLANNOTATOR_AGENT_TERMINAL_REMOTE` | **Values:** `1`, `true`, or `yes` enables the embedded agent terminal in remote mode or a `--tailscale` session.
**Default:** Disabled for both session types.
**Risk:** The terminal can run commands on the remote machine. | | `PLANNOTATOR_AI` | **Value:** `disabled` removes Ask AI, Review Agents, and Guided Review. It also disables their provider and job endpoints.
**Other features:** Ordinary reviews remain available. | | `PLANNOTATOR_CURSOR_SANDBOX` | **Values:** `0`, `false`, or `disabled` omits Cursor's `--sandbox enabled` flag.
**Default:** Enabled.
**Risk:** Without the flag, write protection depends on Ask mode and Cursor configuration. | Relative `XDG_DATA_HOME` values are ignored. Plannotator does not apply the XDG specification's implicit `~/.local/share` default. ## Agent setup Most users should let the installer set these values for supported agents. | Variable | Accepted value and behavior | | - | - | | `PLANNOTATOR_ORIGIN` | **Values:** `claude-code`, `amp`, `droid`, `opencode`, `codex`, `copilot-cli`, `gemini-cli`, `kiro-cli`, or `pi`.
**Effect:** Forces the calling agent.
**Invalid value:** Falls back to detection. | | `PLANNOTATOR_CWD` | Original project directory supplied by an integration wrapper. | | `PLANNOTATOR_BIN` | **Effect:** Sets the Plannotator executable for integrations that launch the CLI.
**Default:** `plannotator` from `PATH`. | | `PLANNOTATOR_PLAN_TIMEOUT_SECONDS` | **Effect:** Sets the maximum wait for OpenCode `submit_plan`.
**Default:** `345600`.
**No timeout:** Set `0`. | | `PLANNOTATOR_ALLOW_SUBAGENTS` | **Value:** `1` lets OpenCode subagents use `submit_plan`.
**Default:** Off. | ## Claude Code These apply to the [Plannotator mod](/open-source/agents/claude-code#the-plannotator-mod) on Claude Code 2.1.287 or later. Set them in the shell that starts Claude Code or in the `env` block of Claude Code's `settings.json`. Claude Code reads them when it starts, so restart it after a change. | Variable | Accepted value and behavior | | - | - | | `PLANNOTATOR_CLAUDE_MOD` | **Off:** `0`, `false`, `off`, or `disabled` turns the mod off. Claude then waits for your decision, and Ask AI uses a provider you pick.
**On:** `1`, `true`, or `on`. An empty or other value counts as unset.
**Default:** On.
**Precedence:** Overrides `claudeCodeMod` in `config.json`.
**Always off:** In `claude -p` and SDK runs, and on Windows. | | `PLANNOTATOR_MOD_DEBUG` | **Value:** `1` makes the mod write a debug log to `~/.plannotator/claude-code-mod/debug.log`, or under `PLANNOTATOR_DATA_DIR` when set.
**Default:** Off.
**Use:** Attach the log when you report a problem with the mod. | Other `PLANNOTATOR_*` values in the source tree coordinate child processes, tests, or packaged integrations. They are not stable user configuration. ## Installer controls | Variable | Accepted value and behavior | | - | - | | `PLANNOTATOR_MINIMAL` | **Values:** `1`, `true`, or `yes` installs only the CLI binary.
**Omitted components:** Hooks, skills, and sidecar tools. | | `PLANNOTATOR_VERIFY_ATTESTATION` | **Enable:** `1`, `true`, or `yes` requires build-provenance verification.
**Disable:** `0`, `false`, or `no`. | | `PLANNOTATOR_SKIP_SEM_INSTALL` | **Values:** `1`, `true`, or `yes` skips the semantic-diff sidecar. | | `PLANNOTATOR_SKIP_AGENT_TERMINAL_INSTALL` | **Values:** `1`, `true`, or `yes` skips the agent-terminal runtime. | | `PLANNOTATOR_PROMPT_TIMEOUT` | **Effect:** Sets the wait for an interactive integration choice in seconds.
**Default:** `30`.
**No timeout:** Set `0`. | The installer reads `PLANNOTATOR_DATA_DIR` and `PLANNOTATOR_VERIFY_ATTESTATION` too. See [Privacy and data flow](/open-source/reference/privacy-and-data-flow) for the network and storage consequences of these settings. Last verified on July 31, 2026, using Plannotator product commit `7cd023c`. Maintained by the Plannotator project. # Add external annotations to Plannotator Source: https://docs.plannotator.ai/open-source/reference/external-annotations Tested HTTP schemas for adding tool findings to a live Plannotator plan, document, or code review session. External annotations let a local tool add findings to an open Plannotator session. The user sees them immediately and they are included when Plannotator exports feedback.
Keep this unauthenticated endpoint on a local or forwarded trusted connection. Do not expose it to an untrusted network.
Copy the active session URL from the terminal or `plannotator sessions`. Then replace `PORT` in the examples below.
## Add a plan or document comment
A sidebar comment needs `source` and `text`. Its default type is `GLOBAL_COMMENT`.
```bash theme={null}
curl -X POST http://localhost:PORT/api/external-annotations \
-H 'Content-Type: application/json' \
-d '{
"source": "style-checker",
"type": "GLOBAL_COMMENT",
"text": "Define the rollback condition before implementation.",
"author": "Docs check"
}'
```
To pin a comment or deletion to existing text, use `COMMENT` or `DELETION` and include the exact phrase in `originalText`:
```bash theme={null}
curl -X POST http://localhost:PORT/api/external-annotations \
-H 'Content-Type: application/json' \
-d '{
"source": "policy-checker",
"type": "COMMENT",
"originalText": "Deploy immediately after merge",
"text": "Add the verification and rollback steps first."
}'
```
Plan and document fields:
| Field | Requirement |
| - | - |
| `source` | Required, non-empty string identifying the tool |
| `text` | Required, non-empty annotation text |
| `type` | Optional: `GLOBAL_COMMENT`, `COMMENT`, or `DELETION`; defaults to `GLOBAL_COMMENT` |
| `originalText` | Required and non-empty for `COMMENT` and `DELETION` |
| `author` | Optional display name |
Plannotator creates the annotation ID and placement metadata. Do not send a `blockId`.
## Add a code review finding
This example creates a line-level concern on the new side of a diff:
```bash theme={null}
curl -X POST http://localhost:PORT/api/external-annotations \
-H 'Content-Type: application/json' \
-d '{
"source": "eslint",
"scope": "line",
"type": "concern",
"filePath": "src/session.ts",
"lineStart": 48,
"lineEnd": 48,
"side": "new",
"text": "This timer is not cleared when the request is aborted.",
"author": "eslint bridge"
}'
```
For a suggestion, include replacement code:
```json theme={null}
{
"source": "refactor-checker",
"scope": "line",
"type": "suggestion",
"filePath": "src/math.ts",
"lineStart": 12,
"lineEnd": 12,
"side": "new",
"text": "Avoid mutating the input.",
"originalCode": "items.sort()",
"suggestedCode": "items.toSorted()"
}
```
Review fields:
| Field | Requirement |
| - | - |
| `source` | Required, non-empty string identifying the tool |
| `scope` | `line`, `file`, or `general`; defaults to `line` |
| `filePath` | Required for `line` and `file`; omitted for `general` |
| `lineStart`, `lineEnd` | Both required numbers for `line` |
| `side` | `new` or `old`; defaults to `new` |
| `type` | `comment`, `suggestion`, or `concern`; defaults to `comment` |
| `text`, `suggestedCode` | At least one must be a string |
| `originalCode`, `author` | Optional strings |
## Add a batch
Wrap multiple valid objects in `annotations`. The request succeeds with `201` and returns the generated IDs.
```bash theme={null}
curl -X POST http://localhost:PORT/api/external-annotations \
-H 'Content-Type: application/json' \
-d '{
"annotations": [
{ "source": "audit", "scope": "file", "filePath": "src/a.ts", "text": "Add a test for the error path." },
{ "source": "audit", "scope": "general", "text": "The migration needs a rollback command." }
]
}'
```
An empty batch or one invalid object returns `400` and adds nothing.
## Read, update, and remove annotations
| Request | Result |
| - | - |
| `GET /api/external-annotations` | `{ "annotations": [...], "version": N }` |
| `GET /api/external-annotations?since=N` | `304 Not Modified` when the version is unchanged |
| `GET /api/external-annotations/stream` | Server-sent event snapshot followed by add, update, remove, and clear events |
| `PATCH /api/external-annotations?id=UUID` | Merge JSON fields into one annotation; the ID cannot be changed |
| `DELETE /api/external-annotations?id=UUID` | Remove one annotation |
| `DELETE /api/external-annotations?source=NAME` | Remove every annotation from one source |
| `DELETE /api/external-annotations` | Clear all external annotations |
The event stream sends a heartbeat every 30 seconds. Use the snapshot endpoint with `since` as a polling fallback.
External annotations live only for the current session. Persist findings in your own tool if they must survive after the Plannotator server closes.
Last verified against Plannotator OSS v0.25.0 on July 27, 2026. Maintained by the Plannotator project.
# Use Plannotator Approval Gates and Automation Hooks
Source: https://docs.plannotator.ai/open-source/reference/hooks
Gate a document or agent message, distinguish approval from dismissal, and return plain text, structured JSON, or hook-native output.
Use `--hook` when a host hook must block on submitted annotations. In this mode, both **Approve** and **Close** let the hook pass. Use direct `--gate --json --require-approval` when success requires explicit approval.
Use `--json` when your wrapper must distinguish approved, dismissed, and annotated decisions.
```bash theme={null}
plannotator annotate path/to/spec.md --hook
plannotator annotate-last --hook
```
`--hook` implies `--gate`, so the review UI includes an Approve action.
In hook-native mode, both **Approve** and **Close** produce empty output, so either action lets the host hook pass. Use direct `--gate --json --require-approval` when **Close** must be a failed gate rather than a pass.
## Output contracts
The contracts apply to `annotate` and `annotate-last`.
### Hook-native output
```bash theme={null}
plannotator annotate path/to/spec.md --hook
```
| User action | Standard output |
| - | - |
| Submit annotations | `{"decision":"block","reason":""}` |
| Approve | Empty |
| Close | Empty |
This contract works directly with Claude Code and Codex `PostToolUse` or `Stop` command-hook protocols that treat a `block` decision as feedback for the agent. If `--hook` and `--json` are both present, the hook-native contract wins.
### Structured JSON
```bash theme={null}
plannotator annotate path/to/spec.md --gate --json
```
| User action | Standard output |
| - | - |
| Submit annotations | `{"decision":"annotated","feedback":""}` |
| Approve | `{"decision":"approved"}` or `{"decision":"approved","feedback":""}` |
| Close | `{"decision":"dismissed"}` |
`--json` does not add the Approve action by itself. Add `--gate` if approval is part of your wrapper's contract.
### Require explicit approval
Use the strict options when an automation should succeed only after approval:
```bash theme={null}
plannotator annotate path/to/spec.md \
--gate --json --require-approval \
--result-file .plannotator-results/spec-review.json
```
Strict options apply only to direct `annotate --gate --json` runs. They reject `annotate-last`, `--hook`, and calls without both `--gate` and `--json`.
| Outcome | JSON decision | Exit status |
| - | - | - |
| Approve, with or without notes | `approved` | `0` |
| Submit annotations | `annotated` | `1` |
| Close | `dismissed` | `1` |
| Invalid command or flags, startup failure, or result publication failure | None, unless the review decision already completed | `2` |
Without `--require-approval`, completed user decisions keep the existing exit status of `0`.
`--result-file` writes the same newline-terminated JSON bytes as stdout. The path is resolved from the current working directory. Its parent must exist, and the destination must not exist, including as a dangling symlink. Plannotator writes stdout first, then atomically publishes an owner-readable and owner-writable file without overwriting an existing path. Publication is atomic but not guaranteed to survive a system crash before the parent directory is flushed.
### Plain text
Without `--json` or `--hook`, submitted annotations are printed as feedback. Approval prints the exact line `The user approved.` and closing prints nothing.
Outside strict approval mode, completed user decisions exit with status 0. Invalid input and startup failures can exit nonzero. Wrappers must inspect both the process status and standard output.
## Pass input safely
The path to review must come from the hook event or from a trusted wrapper argument. Quote it as one shell argument:
```bash theme={null}
artifact_path="path supplied by the host"
plannotator annotate "$artifact_path" --hook
```
Hook event schemas differ by agent and version. Do not copy an input-field name from another host. Use the host's current hook documentation to extract the file path, then call the CLI contract above.
For a host that sends content rather than a file path, pipe it to `annotate-last --stdin`:
```bash theme={null}
printf '%s' "$artifact_text" | plannotator annotate-last --stdin --hook
```
Avoid expanding untrusted hook content as shell code. Pass values as quoted arguments or standard input.
## Installed plan hooks
The full installer and agent plugins configure plan review for supported hosts. For example, the Claude Code plugin ships:
* a `PreToolUse` hook on `EnterPlanMode` that calls `plannotator improve-context`
* a `PermissionRequest` hook on `ExitPlanMode` that calls `plannotator` and waits for the review decision
On Claude Code 2.1.287 or later, the plugin's [Plannotator mod](/open-source/agents/claude-code#the-plannotator-mod) handles `ExitPlanMode` instead of that hook, and Claude does not wait. The hook still runs on older Claude Code, in `claude -p` and SDK runs, on Windows, and when the mod is turned off.
Codex uses its experimental `Stop` hook on macOS, Linux, and WSL. Copilot CLI uses its plugin's pre-tool hook for `exit_plan_mode`. Those plan hooks use host-specific event schemas and should normally be managed by the installer or plugin.
Restart the agent after changing hook configuration. Desktop applications may not inherit your shell `PATH`; use the absolute path to the Plannotator binary if a hook reports that the command is missing.
## Timeouts
A review is intentionally long-running. The shipped plan hooks use a timeout of 345600 seconds. If you write a custom hook, choose a timeout that allows a person to review without leaving an orphaned process.
Last verified on July 31, 2026, using Plannotator product commit `7cd023c`. Maintained by the Plannotator project.
# Automate and Customize Plannotator
Source: https://docs.plannotator.ai/open-source/reference/index
Connect Plannotator to coding agents, customize feedback, run it from hooks, and add annotations from scripts and other tools.
Follow the setup guide for Claude Code, Codex, OpenCode, Copilot CLI, Gemini CLI, and other supported tools.
Change the message Plannotator sends after plan review, document annotation, or code review.
Send findings from linters, scripts, and other local tools into an open Plannotator session.
Call Plannotator from an agent or editor hook and return plain text or structured JSON.
See what stays local and which automatic or optional features contact another service.
Check the unauthenticated local API, remote binding, and session lifetime.
## Choose the right guide
| If you want to | Start here |
| - | - |
| Use Plannotator with a coding agent | [Choose your agent](/open-source/agents/) |
| Install core or extra Agent Skills | [Install and manage skills](/open-source/start/skills) |
| Install, update, or remove the local executable | [Installation](/open-source/start/installation) |
| Read release notes or reinstall a tagged version | [Release notes and version pinning](/open-source/start/installation#read-release-notes) |
| Change the feedback sent to an agent | [Customize feedback](/open-source/reference/custom-feedback) |
| Add findings from a script, linter, or other tool | [Add external annotations](/open-source/reference/external-annotations) |
| Run Plannotator from a host hook | [Use automation hooks](/open-source/reference/hooks) |
| Build against the local session server | [Read the local API reference](/open-source/reference/local-api) |
| Check storage, telemetry, and outbound requests | [Read privacy and data flow](/open-source/reference/privacy-and-data-flow) |
| Change paths, ports, or runtime behavior | [Check configuration](/open-source/reference/configuration) and [environment variables](/open-source/reference/environment-variables) |
Plannotator's local API has no authentication. Keep it on your computer or behind trusted port forwarding. Start with [external annotations](/open-source/reference/external-annotations) when another tool only needs to add findings to the current session.
Last verified on July 31, 2026, using Plannotator product commit `7cd023c`. Maintained by the Plannotator project.
# Plannotator keyboard shortcuts
Source: https://docs.plannotator.ai/open-source/reference/keyboard-shortcuts
Keyboard shortcuts for plan review, document annotation, code review, images, search, and AI panels.
`Mod` means Command on macOS and Control on Windows and Linux. `Alt` is Option on macOS. Shortcuts that act on a file, annotation, search result, or panel require that item to be active.
## Plan review and document annotation
| Shortcut | Action |
| - | - |
| `Mod` + `Enter` | Approve or send feedback |
| `Mod` + `S` | Save or export notes when no default save destination is set |
| `Mod` + `P` | Print |
| `Mod` + `B` | Toggle the document contents sidebar |
| `Mod` + `Shift` + `B` | Toggle the folder file browser when available |
| `Shift`, `Shift` | Toggle the embedded agent terminal when available |
| Hold `Alt` | Temporarily switch between Select and Pinpoint annotation modes |
| Press `Alt` twice | Keep the alternate annotation mode selected |
| `Escape` | Close the current modal, editor, lightbox, or plan diff |
When the annotation label picker is open, press `1` through `0` to choose a label. Press `A` through `Z` to start a comment with the corresponding toolbar shortcut, or `Alt` plus `1` through `0` to start one with a label. The available labels determine which keys are active.
## Vim controls
Turn on **Vim controls** in Settings to navigate and annotate plan, document, and raw HTML views without a mouse. Turn the same setting off to return to standard navigation. The mode is off by default. Press `?` while it is active to open the complete key map.
The optional **Vim HUD** shows a target reticle and navigation context. Enable the HUD before you enable **Key panel**. The **Key panel** setting adds a live keypress legend and command panel.
| Key | Action |
| - | - |
| `j` / `k` | Next or previous block. In text, move down or up one line. |
| `gg` / `G` | First or last block |
| `h` / `l` | Move left or right in text. In nested document structure, move out or in. |
| `v` / `V` | Start character or whole-block visual selection |
| `w` / `b` / `e` | Move by word |
| `0` / `$` | Start or end of line |
| `{` / `}` | Previous or next paragraph |
| `o` | Swap visual-selection ends |
| `Enter` | Use the active selection mode |
| `Space` | Open the annotation menu |
| `c` | Add a comment |
| `d` | Request deletion |
| `m` | Open markup actions |
| `t` | Apply a quick label |
| `y` | Copy the selection |
| `Escape` | Step out of selection or navigation state |
Vim controls yield to text inputs, dialogs, editors, and other focused controls. Use the regular shortcuts in those surfaces.
## Comment and image editing
| Shortcut | Action |
| - | - |
| `Mod` + `Enter` | Submit or save the current comment |
| `Escape` | Cancel the current editor |
| `1` | Select the pen tool in image annotation |
| `2` | Select the arrow tool in image annotation |
| `3` | Select the circle tool in image annotation |
| `Mod` + `Z` | Undo the last image mark |
| `Enter` | Save and close an image annotation when a text field is not active |
## Code review
| Shortcut | Action |
| - | - |
| `Mod` + `Enter` | Approve or send review feedback |
| `Mod` + `F` | Open search |
| `Enter` or `F3` | Next search match |
| `Shift` + `Enter` or `Shift` + `F3` | Previous search match |
| `Escape` | Clear or close search |
| `Mod` + `B` | Toggle the file tree |
| `Mod` + `.` | Toggle the review sidebar |
| `Mod` + `Shift` + `G` | Start or stop guided review |
| `Mod` + `Shift` + `F` | Focus search while the pull request comments tab is open |
| Press `Alt` twice | Toggle the review destination between the code host and the calling agent when both are available |
| `V` | Mark the active file viewed or unviewed |
| `A` | Stage the active local file when staging is available |
| `J` or `Down Arrow` | Move to the next file |
| `K` or `Up Arrow` | Move to the previous file |
| `Home` | Move to the first file |
| `End` | Move to the last file |
In the all-files diff, `X` collapses the active file, `Z` reopens the nearest collapsed file, `C` starts a file-level comment, `]` moves to the next file, and `[` moves to the previous file.
Inside a code comment or suggestion editor, `Mod` + `Enter` submits, `Tab` indents, and `Escape` closes the editor. In Ask AI, `Mod` + `Enter` sends the prompt. `Escape` closes the inline panel.
## Goal setup
`Mod` + `Enter` submits the current interview answers or accepted facts.
Last verified against Plannotator OSS v0.25.0 on July 27, 2026. Maintained by the Plannotator project.
# Plannotator Local Server and API
Source: https://docs.plannotator.ai/open-source/reference/local-api
Security, remote binding, session lifetime, and HTTP routes for Plannotator plan, document annotation, and code review servers.
Each Plannotator session runs a temporary HTTP server for its browser UI and local integrations. The API is session-scoped, unauthenticated, and not a versioned public web API.
Use the URL printed in the terminal, such as `http://localhost:49152`. You can also find a running session with:
```bash theme={null}
plannotator sessions
```
## Security boundary
Local mode binds to `127.0.0.1`. Remote mode binds to `0.0.0.0` so SSH and development-container port forwarding can reach it. The API has no authentication in either mode.
Do not expose a remote Plannotator port to the public internet or an untrusted network. Forward it to your own machine through SSH or a trusted development environment.
Enable `PLANNOTATOR_AGENT_TERMINAL_REMOTE` only on a trusted connection. The embedded terminal can run commands on the remote machine.
## Stable integration surface
External tools should normally use `/api/external-annotations`. It is available in plan, document annotation, and code review sessions and has a tested schema. See [External annotations](/open-source/reference/external-annotations).
The remaining routes support the bundled browser UI. They can change with a Plannotator release, and the available set depends on the session mode.
## Common route families
Availability varies by session mode.
| Route | Purpose |
| - | - |
| `GET /api/plan` | Current plan or document payload and session metadata |
| `GET /api/config` | Settings shared with the server |
| `POST /api/config` | Persist supported UI settings to `config.json` |
| `GET /api/external-annotations` | Current external annotation snapshot |
| `POST /api/external-annotations` | Add one or more external annotations |
| `GET /api/external-annotations/stream` | Stream external annotation updates with server-sent events |
| `POST /api/feedback` | Submit annotations from a document or review session |
| `POST /api/exit` | Close a session without submitting feedback |
Unknown `/api/*` routes return a JSON `404` response rather than the browser application HTML.
## Plan review routes
Plan sessions expose routes for the current plan, previous versions, approval or denial, draft annotations, references, uploaded images, saved notes, and plan history. The decision routes are called by the UI and return their result to the agent process that started the session.
## Document annotation routes
Document sessions expose routes for source content, versions, source-file saving, drafts, references, uploads, feedback, and sharing. Raw local HTML also uses a restricted asset route to load supported files from the HTML file's directory. Assets outside that directory are refused.
## Code review routes
Code review sessions expose routes for:
* diffs, commits, file contents, and diff-scope switching
* staging and viewed-file state when supported by the repository provider
* GitHub pull request and GitLab merge request context
* pull request comments, artifacts, stacks, and revision selection
* semantic diff and code navigation
* Ask AI sessions and launched review jobs
* review skills and capabilities
The exact payloads depend on Git, GitButler, Jujutsu, Perforce, GitHub, or GitLab state. Treat them as same-version UI contracts, not as long-lived automation contracts.
## AI routes
Sessions with AI support can expose `GET /api/ai/capabilities`, session management, a streaming query route, abort, and permission-response routes. Code review sessions can also expose job, job-event, review-skill, Guided Review history, and capability routes.
`PLANNOTATOR_AI=disabled` prevents AI runtime construction and makes provider and job launch routes unavailable. Ordinary review routes and saved guide data remain intact, though the in-app guide browser is hidden.
These routes run local agent tools and may ask for permission. Do not proxy them to another user or network.
## Session lifetime
The server normally exits when you approve, send feedback, or close the session. The browser can keep showing the completion page after the server ends. **Settings > General > Auto-close Tab** controls whether that tab stays open or closes immediately, after three seconds, or after five seconds.
A random local port can be different on every run. Do not store a session URL as durable configuration. Get the current URL from the launching process or `plannotator sessions`. See [Privacy and data flow](/open-source/reference/privacy-and-data-flow) for local storage and outbound network behavior.
Last verified on July 31, 2026, using Plannotator product commit `7cd023c`. Maintained by the Plannotator project.
# Plannotator OSS Privacy and Data Flow
Source: https://docs.plannotator.ai/open-source/reference/privacy-and-data-flow
What Plannotator OSS keeps locally, which automatic and optional network requests it makes, and how sharing and hosted products change the data boundary.
Plannotator OSS runs locally and does not send Plannotator usage telemetry or analytics. Plans, documents, diffs, annotations, drafts, history, and configuration stay on your computer by default. Some automatic and optional features contact GitHub, your Git remote, a URL, an AI provider, or a hosted sharing service.
This page covers the open-source CLI and browser UI. [Workspaces](https://help.plannotator.ai/workspaces/) is a hosted product. Documents created or uploaded there are sent to its service, so the local-only statements on this page do not apply to that workflow.
## What stays local
Each review runs through a temporary HTTP server on your computer. Local mode binds to `127.0.0.1`. The browser reads the document or diff from that server and returns your decision to it.
Plannotator can write these local records:
| Data | Local location or lifetime |
| - | - |
| Configuration, session records, saved plans, document history, drafts, and Guided Reviews | Under the active Plannotator data directory. This is normally `~/.plannotator`. |
| Theme, layout, panel state, and other browser preferences or recovery data | Browser storage for each Plannotator origin and port. This can include functional cookies, `localStorage`, and tab-scoped `sessionStorage`. |
| Pasted or uploaded feedback images | Temporary local files. The returned feedback contains the image name and path. |
| Pull request or merge request checkout | A temporary Git worktree or shallow clone when local checkout is enabled. Plannotator removes it when the review session ends. |
Document history can contain full copies of opened files. Disable it before opening sensitive files when those copies are not acceptable. See [Version history](/open-source/workflows/version-history#disable-document-annotation-history).
Remote mode binds the unauthenticated server to `0.0.0.0`. Do not expose that port to the public internet or an untrusted network. Use SSH forwarding or a trusted development environment. See [Local server and API](/open-source/reference/local-api#security-boundary).
## Automatic GitHub release check
Each time a plan review, annotate, archive, share-portal, or code-review surface loads, it requests the latest release record from:
```text theme={null}
https://api.github.com/repos/backnotprop/plannotator/releases/latest
```
The request compares the installed version with the current GitHub release. It does not include the reviewed document, diff, annotations, or a usage-event payload. GitHub receives the request and the network metadata normally sent with it. Plannotator OSS does not currently provide a setting to disable this release check. Dismissing an update notice hides that release notice but does not stop later checks.
This request is an update check, not usage telemetry. Plannotator does not send a separate event when you open a review, add an annotation, approve, dismiss, or send feedback.
## Other automatic network access
For a local Git review, Plannotator may run `git ls-remote origin` in the background to identify the remote default branch and report a stale local baseline. This contacts the Git host configured as `origin`, but it does not send the local diff. Choosing the in-app fetch action runs `git fetch`.
The installer downloads the selected Plannotator binary and checksum from GitHub Releases. Installing the latest version first queries GitHub's API to resolve the release tag. If available, it sends a token from `GITHUB_TOKEN`, `GH_TOKEN`, or `gh auth token` to that API. Pinning `--version` skips that API lookup, but the binary and checksum still come from GitHub Releases.
A full install can also contact GitHub for integration files, Ataraxy-Labs/sem for the optional `sem` sidecar, and npm for Pi, selected skills, or the managed agent-terminal runtime. Provenance verification, when enabled, also contacts GitHub through `gh`. Minimal mode and the applicable skip flags omit their optional components.
## Optional outbound requests
| Feature you choose | Where data can go |
| - | - |
| Annotate a public URL | Plannotator can request the URL directly for content negotiation and send it to Jina Reader for conversion when Jina is enabled. If Jina fails or is disabled, Plannotator fetches the target directly. Local and private-network URLs skip Jina. Browser authentication cookies are not forwarded. |
| Review a GitHub pull request or GitLab merge request | The authenticated `gh` or `glab` CLI and Git configuration retrieve provider metadata, diffs, comments, checks, content, and related refs. Posting a review or changing provider-side state sends the selected action to that provider. |
| Ask AI, Agent Reviews, Code Tour, or Guided Review | Plannotator launches a configured AI provider or installed agent CLI. It can send prompts, selected review context, and repository content to that provider. Plannotator does not route the request through a Plannotator-operated model proxy. Provider permissions and retention follow that CLI and account. Claude Ask AI allows WebSearch by default, so a question can also send a search query to Anthropic's search service and return third-party web results. With [Ask this session](/open-source/workflows/ask-this-session), on Claude Code with the Plannotator mod, Pi, or OpenCode 2, Ask AI questions and their review context go to the agent session that opened Plannotator instead. The question and the answer become part of that session's conversation, except for the quick answers in OpenCode 2 plan review. |
| Start the embedded annotate terminal | Plannotator launches a new local agent CLI process in the review directory. The agent can contact its configured provider. It is not the original agent session that opened Plannotator. |
| Use the deprecated OSS sharing flow | The share portal serves the browser application. A URL-fragment share keeps the review payload in the fragment. Markdown short links upload encrypted ciphertext after confirmation. Local raw HTML can upload through a share or callback action. For remote raw HTML, the compiled CLI uploads encrypted ciphertext at session creation. Pi does not upload automatically at startup. See [Sharing](/open-source/workflows/sharing). |
| Use Workspaces | Documents and collaboration activity use the hosted Workspaces service. See [Workspaces Help](https://help.plannotator.ai/workspaces/) for that product's behavior. |
Local Git commit review can look up commit-author avatars.
For GitHub remotes, Plannotator fetches recent commit metadata and matches returned email addresses locally. It does not send the local commit-author email to GitHub for that match.
For GitLab remotes, Plannotator sends commit-author emails to the configured GitLab avatar endpoint. It sends one email per request and up to ten requests in parallel. It retries overflow in later rounds.
If either provider returns a match, the browser requests the image from GitHub, GitLab, Gravatar, or another avatar host.
Raw local HTML has another boundary: scripts inside the sandboxed document can still make outbound network requests. Open only HTML you trust, or use `--markdown` to remove scripts before annotation. See [Annotate HTML](/open-source/workflows/html#open-rendered-html).
Rendered plans, documents, raw HTML, and hosted pull-request descriptions can request remote images, video, fonts, or other assets they reference. Selecting a hosted code-review font can contact Google Fonts or jsDelivr. Opening an in-app help video loads a privacy-enhanced YouTube embed.
A share-link creator can configure an HTTP or HTTPS callback and a token. Choosing **Approve** or **Send Feedback** in that shared review posts the action, token, and annotated share URL to the callback. For an encrypted short link, that URL can include the fragment decryption key. Trust the callback with the shared content and key, and prefer HTTPS.
## Reduce outbound access
* Use local files instead of URL annotation.
* Set `PLANNOTATOR_AI=disabled` to remove Ask AI, Agent Reviews, and Guided Review.
* Set `PLANNOTATOR_SHARE=disabled` to hide OSS share and import actions.
* Review local code changes instead of a provider pull-request URL.
* [Self-host the share portal and paste service](/open-source/self-hosting) when the deprecated OSS sharing flow is still required.
These controls do not disable the automatic GitHub release check.
Last verified on August 10, 2026, using Plannotator product commit `f8951cd`. Maintained by the Plannotator project.
# Open Plannotator on Another Device
Source: https://docs.plannotator.ai/open-source/remote-access
Open a Plannotator session from a phone, tablet, local browser, or another computer through Tailscale, a trusted private network, SSH, or a development-container port forward.
Use remote access when Plannotator runs on one machine but you want to review from a phone, tablet, or another computer. You are not deploying a persistent Plannotator server. Each command starts a temporary session that normally exits after you approve, send feedback, or close it.
## Choose a connection
| Method | Use it when | Connection |
| - | - | - |
| Tailscale Serve | The machine running Plannotator and the review device can join the same tailnet | HTTPS through Tailscale, while Plannotator stays bound to `127.0.0.1` |
| Trusted Wi-Fi, LAN, or private VPN | The review device can reach the machine running Plannotator directly | Plain HTTP to an unauthenticated server bound to `0.0.0.0` |
| SSH or development-container forwarding | Plannotator runs on a remote host or inside a container and the browser runs on your local computer | Plain HTTP through a forwarded local port |
Plannotator does not add a login screen or per-request authentication to a remote session. Do not expose its port to the public internet or an untrusted network.
## Use Tailscale
Before you start:
* Install Plannotator `v0.27.0` or later on the machine that runs your agent.
* Install Tailscale and connect the agent host and review device to the same tailnet.
* Enable HTTPS certificates for the tailnet.
* Permit the review device to reach the agent host through your Tailscale access rules.
Then start the session with `--tailscale`:
```bash theme={null}
plannotator review --tailscale
```
The same flag works for document annotation and the last-message picker:
```bash theme={null}
plannotator annotate path/to/spec.md --tailscale
plannotator annotate-last --tailscale
```
Plannotator prints an HTTPS URL and displays a QR code in an interactive terminal. It keeps the temporary server on `127.0.0.1` and uses Tailscale Serve as the HTTPS proxy.
`--tailscale` works in the compiled Plannotator CLI. The Pi extension does not accept this flag.
See [Set up and troubleshoot Tailscale remote reviews](/open-source/tailscale) for installation links, HTTPS approval, Serve conflicts, cleanup behavior, access failures, and command limits.
## Use trusted Wi-Fi, a LAN, or another private VPN
Set remote mode and advertise a hostname or IP address that the other device can reach:
```bash theme={null}
PLANNOTATOR_REMOTE=1 \
PLANNOTATOR_URL_HOST=devbox.internal \
plannotator review
```
Replace `devbox.internal` with a resolvable hostname, an IPv4 address such as `192.168.1.42`, or a bracketed IPv6 address such as `[fd7a:115c:a1e0::42]`.
`PLANNOTATOR_REMOTE=1` binds the temporary server to `0.0.0.0`. `PLANNOTATOR_URL_HOST` changes only the URL that Plannotator prints. It does not change the bind address. The value must contain only a hostname or IP address, with no scheme, port, path, credentials, or whitespace.
Remote mode uses port `19432` by default. Set a fixed port or a range when you need different network or concurrency behavior:
```bash theme={null}
PLANNOTATOR_PORT=19432-19463 \
PLANNOTATOR_REMOTE=1 \
PLANNOTATOR_URL_HOST=devbox.internal \
plannotator review
```
The compiled CLI prints the complete URL and displays its QR code when standard error is an interactive terminal. Pi reports the reachable URL but does not display the QR code.
The core review, annotation, and approval flows work over plain HTTP. Browser features that require a secure context, including creating an encrypted short share link, require HTTPS.
`PLANNOTATOR_URL_HOST=auto` detects a Tailscale MagicDNS name or tailnet IPv4 address. For WireGuard, ZeroTier, a corporate VPN, or a LAN, set the hostname or IP address explicitly.
## Forward a session over SSH
From your local computer, connect with the same local and remote port:
```bash theme={null}
ssh -L 19432:127.0.0.1:19432 user@host
```
Inside that SSH session, start Plannotator with a fixed port:
```bash theme={null}
PLANNOTATOR_REMOTE=1 \
PLANNOTATOR_PORT=19432 \
plannotator review
```
Open `http://localhost:19432` on your local computer if Plannotator does not open it automatically.
Remote mode listens on every interface of the remote host. The SSH tunnel does not stop another network peer from reaching port `19432` through a different interface. Keep the port blocked by the host firewall and network policy.
## Forward a development-container port
Add the fixed port and remote mode to `devcontainer.json`:
```json theme={null}
{
"containerEnv": {
"PLANNOTATOR_REMOTE": "1",
"PLANNOTATOR_PORT": "19432"
},
"forwardPorts": [19432]
}
```
Rebuild the container, start a review, and open the forwarded port from the editor's **Ports** view. Keep its visibility private. Setting `PLANNOTATOR_PORT` without `PLANNOTATOR_REMOTE=1` is not enough because local mode binds to `127.0.0.1` inside the container.
VS Code Remote and development containers usually provide a `BROWSER` helper that opens the forwarded URL on your local computer. Plannotator uses that helper when it is available. You can also set [`PLANNOTATOR_BROWSER`](/open-source/reference/environment-variables#session-and-browser) to a browser or script.
## Control deprecated link sharing
Remote access and link sharing are separate features. A live remote session lets another browser make the decision while the agent waits. The deprecated OSS sharing flow creates an asynchronous link that another person returns later.
Disable link sharing when you only need the live remote session:
```bash theme={null}
export PLANNOTATOR_SHARE=disabled
```
The variable applies to the compiled CLI, Pi, and integrations that use Plannotator's shared configuration resolver. An explicit OpenCode `share` setting takes precedence.
When sharing remains enabled, a remote Markdown session can produce a complete share URL in addition to the live session URL. The Markdown is inside that complete URL and can remain in terminal logs or shell capture.
With sharing enabled, remote raw HTML uses the paste service because it cannot use the hash-only Markdown format. The compiled CLI encrypts and uploads the HTML when the remote session starts. Pi serves the HTML through the forwarded live session but does not upload it automatically at startup. Disable sharing before opening sensitive remote HTML when that upload is not intended.
## Protect the annotate-mode agent terminal
The embedded agent terminal in annotate mode is disabled during remote and `--tailscale` sessions. Enabling it allows the browser to run commands on the machine that hosts Plannotator:
```bash theme={null}
PLANNOTATOR_AGENT_TERMINAL_REMOTE=1 \
PLANNOTATOR_REMOTE=1 \
plannotator annotate path/to/spec.md
```
Use this setting only when every device and network path that can reach the session is trusted. The terminal token is not an authentication boundary.
## Troubleshoot the connection
During a session, check the server on the machine running Plannotator:
```bash theme={null}
curl -fsS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:19432/
```
A working session returns `200`. Replace `19432` if you selected another port. If the other device cannot connect, check these items:
* The process that started Plannotator inherited `PLANNOTATOR_REMOTE=1`.
* The hostname or IP address resolves from the review device.
* The firewall permits only the intended private path to the selected port.
* An SSH or development-container forward uses the same port as Plannotator.
* Tailscale is connected on both devices and its access rules permit the connection.
See [Troubleshooting](/open-source/troubleshooting#remote-ssh-and-development-containers) for port conflicts and host-specific checks.
Last verified on August 12, 2026, against Plannotator `v0.27.1` and product commits `b69742c`, `5f33b72`, and `ed6f44b`. Maintained by the Plannotator project.
# Plannotator Open Source Security
Source: https://docs.plannotator.ai/open-source/security
How Plannotator OSS keeps review data local, protects release artifacts, runs automated security checks, and accepts private vulnerability reports.
Plannotator OSS runs on your computer by default. It does not collect usage telemetry or analytics, and an ordinary local review does not upload your plan, document, diff, annotations, or feedback to Plannotator.
The project also publishes verifiable release artifacts and runs automated security checks against its source, dependencies, secrets, and GitHub configuration.
## Data and network boundaries
A normal session uses a temporary HTTP server bound to `127.0.0.1`. Review content and local records stay on your computer.
Plannotator OSS does not send usage events or analytics when you open, annotate, approve, dismiss, or send feedback.
Remote mode changes the bind address and does not add authentication. Use a trusted path such as [Tailscale](/open-source/tailscale) or [SSH forwarding](/open-source/remote-access).
URL annotation, hosted pull requests, AI providers, sharing, and Workspaces can contact another service when you choose to use them.
Plannotator checks GitHub for the latest release when an app surface loads, and a local Git review can contact its configured `origin`. These requests do not include the reviewed content. See [Privacy and data flow](/open-source/reference/privacy-and-data-flow) for the complete list of automatic and optional network requests.
Set `PLANNOTATOR_SHARE=disabled` to hide OSS share and import actions. Set `PLANNOTATOR_AI=disabled` to remove AI-backed features and their provider routes. Ordinary local plan, document, and code review still work.
## Release integrity
For a release tag, the workflow builds and tests the artifacts, generates and scans the SBOM, attests the release, and then publishes it.
Runs the public release workflow from a version tag on `main`.
Type-checks, tests, builds, and runs binaries and installers on Linux, macOS, and Windows.
Generates a matching checksum file for every release binary.
Creates GitHub attestations for build provenance and the release SBOM.
Publishes release assets only after tests, smoke runs, the Grype policy, and attestations complete.
Publishes prebuilt package tarballs from a separate OIDC-authorized job with npm provenance.
The workflow uses Syft to generate a CycloneDX SBOM. Grype must pass the release policy before the workflow creates the attestations.
Release tags must point to a commit on `main` and match the version in the release manifests. The GitHub Release is published only after the attestations exist.
[`v0.27.3`](https://github.com/backnotprop/plannotator/releases/tag/v0.27.3) was the first release to complete this pipeline. It published a CycloneDX 1.6 SBOM and a matching checksum. Its binaries have SLSA provenance and CycloneDX SBOM attestations.
The SBOM describes the release-wide inventory of locked inputs and dependencies. 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 [Pin or verify a release](/open-source/start/installation#pin-or-verify-a-release) to verify installer provenance or download and verify the SBOM evidence.
## Automated security checks
On every pull request to `main` and every push to `main`, the [Security Scanning workflow](https://github.com/backnotprop/plannotator/actions/workflows/security.yml) runs Gitleaks, zizmor, Semgrep, and Trivy. A weekly scheduled run checks for drift. Trusted runs upload SARIF results to GitHub Code Scanning.
Detects known secret formats. Push protection stops matched credentials before they land.
Monitors dependencies, opens security updates, and runs routine Bun update checks each week.
Checks pull-request and push commit ranges for secrets, with scheduled full-history scans.
Audits GitHub Actions workflows, local actions, and Dependabot configuration offline.
Runs repository-owned source rules offline with no Semgrep Cloud upload.
Checks committed dependency locks and filesystem or infrastructure configuration against pinned scanner and policy versions.
OWASP ZAP runs a passive baseline each week. A maintainer can also start the workflow manually. The workflow uses a disposable annotate session on an internal-only Docker network. A read-only guard rejects state-changing requests and unapproved paths.
The Security Scanning and ZAP DAST workflows are in monitor mode. Tool and evidence failures fail their jobs. Findings appear in GitHub Code Scanning or retained workflow artifacts, but they do not block a merge or release.
## Report a vulnerability privately
Do not open a public issue for a suspected vulnerability.
Send the affected version, reproduction steps, impact, required preconditions, and any known workaround through GitHub's private reporting form.
Security fixes are provided for the latest released version. See the repository [security policy](https://github.com/backnotprop/plannotator/blob/main/SECURITY.md) for the supported-version and disclosure policy.
## Evidence and limitations
* [Latest release artifacts and checksums](https://github.com/backnotprop/plannotator/releases/latest)
* [First SBOM-enabled release: v0.27.3](https://github.com/backnotprop/plannotator/releases/tag/v0.27.3)
* [Release attestations](https://github.com/backnotprop/plannotator/attestations)
* [Release and security workflow source](https://github.com/backnotprop/plannotator/tree/main/.github/workflows)
* [ZAP DAST workflow and run history](https://github.com/backnotprop/plannotator/actions/workflows/dast.yml)
* [GitHub Actions history](https://github.com/backnotprop/plannotator/actions)
* [OSS privacy and data flow](/open-source/reference/privacy-and-data-flow)
Automated checks reduce risk; they do not prove that the software has no vulnerabilities. Plannotator does not claim SOC 2, ISO 27001, or another security certification for the OSS project. The support policy covers the latest release, and this page does not describe the hosted Workspaces product.
## Appendix: security pipeline
These diagrams show when each security control runs and how its evidence moves through the project.
### Release trust chain
A release tag generates the SBOM and runs the Grype policy before the workflow creates attestations and publishes the release.
![A vertical release trust chain shows a version tag building artifacts, generating a Syft SBOM, passing a Grype scan, creating Sigstore attestations, publishing, and user verification.]()
![A vertical release trust chain shows a version tag building artifacts, generating a Syft SBOM, passing a Grype scan, creating Sigstore attestations, publishing, and user verification.]()
### Security on every code change
The build and security workflows start from the same pull request or push. The security scanners run independently from the build workflow.
![A pull request or push starts build tests and four security scans: Gitleaks for secrets, Semgrep for source code, Trivy for dependencies, and zizmor for workflows. Findings upload to GitHub Code Scanning.]()
![A pull request or push starts build tests and four security scans: Gitleaks for secrets, Semgrep for source code, Trivy for dependencies, and zizmor for workflows. Findings upload to GitHub Code Scanning.]()
### Scheduled security testing
The weekly workflows scan the repository and a disposable application instance. The ZAP workflow scans only the disposable instance inside an isolated CI network.
![Weekly security testing runs a full repository scan and an OWASP ZAP passive scan against a disposable application inside an isolated CI network, then retains the reports.]()
![Weekly security testing runs a full repository scan and an OWASP ZAP passive scan against a disposable application inside an isolated CI network, then retains the reports.]()
Last verified on August 13, 2026, using Plannotator product commit `aa0bf86`. Maintained by the Plannotator project.
# Self-Host Plannotator's Deprecated Share Services
Source: https://docs.plannotator.ai/open-source/self-hosting
Deploy the deprecated OSS share portal and encrypted paste service for compatibility with asynchronous Plannotator share links.
Plannotator has two self-hostable services for the deprecated OSS share-link flow:
| Service | Deploy it when |
| - | - |
| Share portal | You need your own static site to open hash-based Markdown share links. |
| Paste service | You need encrypted short links for large Markdown reviews or raw HTML. |
The OSS share-link flow is deprecated and retained for compatibility. No removal date has been announced. For new team sharing and collaboration, [sign up for Workspaces](https://plannotator.ai/workspaces).
You do not need either service for normal local reviews or to open a temporary session from another device. Install Plannotator and run it beside your coding agent for local use. See [Remote access](/open-source/remote-access) for phones, tablets, Tailscale, private networks, SSH, and development containers.
## Understand the sharing services
The share portal is a static browser application. It has no application database, accounts, or built-in access control.
For a normal Markdown share, Plannotator compresses the review into the complete URL after `#`. The browser does not send that fragment to the portal in its HTTP request. The portal loads the application, then the browser decodes the review locally. The fragment is not encrypted, so anyone with the complete URL can read the review.
Large Markdown reviews and raw HTML use the paste service. The Plannotator client encrypts the payload before upload. The paste service stores ciphertext, while the decryption key stays in the complete share URL after `#`. Anyone with the complete link can fetch and decrypt the content.
Deploy only the portal when hash-based Markdown links are enough. Deploy both services when you need encrypted short links or raw HTML sharing.
Neither service provides application authentication or certificates. Your hosting layer must provide HTTPS, access controls, rate limits, and network isolation where required.
## Deploy the share portal
Build the portal from a Plannotator source checkout. Check out the release tag or reviewed commit you intend to operate before installing dependencies:
```bash theme={null}
git clone https://github.com/backnotprop/plannotator.git
cd plannotator
git checkout
bun install
bun run build:portal
```
Deploy the contents of `apps/portal/dist/` to a static host. Configure unknown paths, including `/p/`, to return `index.html` so direct short-link visits load the application. The hosting layer must provide HTTPS, access logs, caching rules, and any access control you require.
Point new Plannotator sessions at the portal:
```bash theme={null}
export PLANNOTATOR_SHARE_URL=https://share.example.com
```
The process that starts Plannotator must inherit this variable. Existing sessions do not change their share base URL.
The portal performs Plannotator's automatic GitHub release check when it loads. Rendered shared content can also request remote images, fonts, scripts, or other resources it references. There is no setting that disables the release check.
## Deploy the paste service
The paste service exposes `POST /api/paste` and `GET /api/paste/:id`. The repository includes two targets:
* A Bun server with filesystem storage.
* A Cloudflare Worker with KV storage.
Neither target authenticates callers. CORS controls which browser origins can use responses. It does not authenticate callers or block direct HTTP clients.
The shared CORS helper always allows `http://localhost` and `https://localhost` origins, including ports. Setting an explicit origin list does not remove that localhost exception.
### Run the Bun filesystem target
From the Plannotator source checkout:
```bash theme={null}
PASTE_PORT=19433 \
PASTE_DATA_DIR=/var/lib/plannotator-paste \
PASTE_TTL_DAYS=7 \
PASTE_MAX_SIZE=5242880 \
PASTE_ALLOWED_ORIGINS=https://share.example.com \
bun run apps/paste-service/targets/bun.ts
```
Run the process under your normal service supervisor. The Bun target listens on all interfaces by default, even though its startup message prints a `localhost` URL. Enforce firewall or private-network isolation and put it behind an HTTPS reverse proxy. Do not leave port `19433` directly reachable from an untrusted network.
The API has no authentication. If it is reachable beyond a trusted private network, add authentication and request-rate controls at the proxy or edge. The payload limit caps each upload, not the number of uploads or total storage growth.
The data directory must have the ownership and backup policy you want. The process creates it when it is absent. The default maximum is 5 MiB of encrypted payload data. Each filesystem paste records its expiry time. An expired file is deleted when that paste is read or when the service next starts, so expired bytes can remain on disk past their logical expiry while a long-running service is idle.
GitHub releases also include `plannotator-paste-*` binaries and matching `.sha256` files for macOS, Linux, and Windows. Download the binary and same-named checksum file from the same release. Verify them before running the binary with the same `PASTE_*` variables:
```bash theme={null}
# Linux
sha256sum -c plannotator-paste-linux-x64.sha256
# macOS
shasum -a 256 -c plannotator-paste-darwin-arm64.sha256
```
On Windows, run `Get-FileHash .\plannotator-paste-win32-x64.exe -Algorithm SHA256` and compare the result with `plannotator-paste-win32-x64.exe.sha256`.
### Run the Cloudflare KV target
The repository's `apps/paste-service/wrangler.toml` is a deployment example, not a namespace allocation for your account. Create your own KV namespace, replace both namespace IDs, and set `ALLOWED_ORIGINS` to your portal origin before deployment. Do not deploy the checked-in hosted namespace IDs into another environment.
```bash theme={null}
cd apps/paste-service
bunx wrangler kv namespace create PASTE_KV
bunx wrangler kv namespace create PASTE_KV --preview
bun run deploy:cf
```
Put the first command's namespace ID in `id` and the preview command's ID in `preview_id` before deploying.
The current Worker target uses Cloudflare KV expiry with a fixed seven-day TTL and a fixed 5 MiB encrypted payload limit. Its supported runtime setting is `ALLOWED_ORIGINS`. The Bun-only `PASTE_TTL_DAYS`, `PASTE_DATA_DIR`, and `PASTE_MAX_SIZE` variables do not configure the Worker target.
## Connect Plannotator to both services
Set both URLs in the environment that starts your coding agent:
```bash theme={null}
export PLANNOTATOR_SHARE_URL=https://share.example.com
export PLANNOTATOR_PASTE_URL=https://paste.example.com
```
Custom short links include the paste-service origin in the URL fragment so the static portal knows where to fetch the ciphertext. Anyone with the complete link has the paste ID and decryption key.
## Deployment variables
| Variable | Default | Applies to |
| - | - | - |
| `PLANNOTATOR_SHARE_URL` | `https://share.plannotator.ai` | Share portal used in generated links |
| `PLANNOTATOR_PASTE_URL` | `https://plannotator-paste.plannotator.workers.dev` | Paste API used for short links and raw HTML |
| `PASTE_PORT` | `19433` | Bun paste-service port |
| `PASTE_DATA_DIR` | `~/.plannotator/pastes` | Bun filesystem paste storage |
| `PASTE_TTL_DAYS` | `7` | Bun paste logical expiry |
| `PASTE_MAX_SIZE` | `5242880` | Bun maximum encrypted payload bytes |
| `PASTE_ALLOWED_ORIGINS` | `https://share.plannotator.ai,http://localhost:3001` | Bun CORS allowlist |
| `ALLOWED_ORIGINS` | `https://share.plannotator.ai,http://localhost:3001` | Cloudflare Worker CORS allowlist |
See [Environment variables](/open-source/reference/environment-variables) for general `PLANNOTATOR_*` precedence and the setting that disables sharing.
## Operator responsibilities
### Authentication and network exposure
* The static portal and paste API have no application authentication. Add access control at your hosting layer if your reviewers require it, then test the complete redirect and URL-fragment flow.
* CORS is a browser boundary, not caller authentication.
* A public paste API needs rate limits or equivalent abuse controls. The payload-size limit alone does not prevent repeated uploads.
### TLS and link handling
* The repository does not provision certificates or an HTTPS reverse proxy. The operator owns TLS for the portal and paste API.
* Treat every complete share URL as a credential. Hash-based Markdown is readable from the URL. Short links contain the decryption key in the fragment.
* Avoid putting complete share URLs in analytics, support tickets, screenshots, or logs with broader retention than the review.
### Persistence, retention, and backup
* Keep the Bun paste data directory on persistent storage only if short links must survive restarts.
* Decide whether ephemeral ciphertext belongs in backups. A backup can retain bytes after the live paste expires, so its deletion schedule must match your policy.
* Monitor disk use for the Bun target. Logical expiry does not guarantee immediate file removal from an idle, continuously running service.
## Verify the deployment
**1. Check the portal.** Confirm that a direct portal route reaches the static application:
```bash theme={null}
curl -fsS -o /dev/null -w '%{http_code}\n' https://share.example.com/p/test
```
A working single-page application fallback returns `200`.
**2. Check the paste API.** Send harmless data and inspect the CORS response:
```bash theme={null}
curl -i https://paste.example.com/api/paste \
-H 'Origin: https://share.example.com' \
-H 'Content-Type: application/json' \
--data '{"data":"deployment-check"}'
```
Expect `201`, an `Access-Control-Allow-Origin` header for the portal, and a JSON paste ID.
**3. Test the deprecated sharing flow.** Start a new Plannotator session with the custom variables. Create a normal Markdown link and an explicit short link. Confirm both use your portal, the short link fetches from your paste API, and an imported returned link restores the review annotations.
For failures, check [Troubleshooting](/open-source/troubleshooting), the browser network panel, the static host's single-page application fallback, and the exact origin in the paste-service CORS setting.
## What this deployment does not provide
The share portal and paste service do not provide a persistent Plannotator review server, account system, built-in authentication, certificate management, live collaborative editing, or centrally managed document history. They support asynchronous links for a deprecated OSS workflow.
For new team sharing, durable documents, access management, and live collaboration, [sign up for Workspaces](https://plannotator.ai/workspaces).
Last verified on August 10, 2026, against Plannotator product commit `f8951cd` and release `v0.26.7`. Maintained by the Plannotator project.
# Review Your First Code Change
Source: https://docs.plannotator.ai/open-source/start/code-review-quickstart
Open a local code diff in Plannotator, comment on changed lines, and send clear feedback to your coding agent.
Use a project where you or your coding agent has changed code. Plannotator opens the diff in your browser so you can comment on exact lines and send feedback to your agent.
In your terminal, go to a Git, GitButler, Jujutsu, or Perforce project with changes to review.
For your first review, use a project where an agent has just finished a task. You do not need to commit the changes first.
Run:
```bash theme={null}
plannotator review
```
Plannotator detects the project and opens the diff in your browser.
In Git projects, the default view approximates a pull request. In an active GitButler workspace, **Workspace** shows all applied work and working-tree changes. See [Review Local Code Changes](/open-source/workflows/local-changes) for the complete inclusion rules.
Select one or more changed lines. Add a comment, request a deletion, or suggest replacement code.
Keep the feedback specific. State what should change and why.
Select **Send Feedback**.
A direct terminal run prints structured feedback that you can copy. When your coding agent starts the review, Plannotator returns the same feedback to that agent session.
## Start the review from your coding agent
Most command-based agents use:
```text theme={null}
/plannotator-review
```
Codex can run `!plannotator review` or use `$plannotator-review`. See [Agents](/open-source/agents) for the command and setup for Claude Code, Codex, OpenCode, Copilot CLI, Gemini CLI, Pi, Amp, Droid, and Kiro CLI.
## Review a pull request or merge request
Pass Plannotator a GitHub pull request or GitLab merge request URL:
```bash theme={null}
plannotator review https://github.com/owner/repository/pull/123
```
GitButler users can continue with [Review GitButler Workspaces, Stacks, and Branches](/open-source/workflows/gitbutler). For provider setup and posting feedback, see [Review Pull Requests and Merge Requests](/open-source/workflows/pull-requests).
Last verified against Plannotator OSS v0.25.0 on July 27, 2026. Maintained by the Plannotator project.
# Turn Plannotator Feedback into Agent Skills
Source: https://docs.plannotator.ai/open-source/start/compound-value
Use feedback from plan reviews, document annotations, and code reviews to create agent skills that match your preferences.
Plannotator sends your comments back to the agent that asked for the review. Save the feedback you want to reuse in one folder, then point your agent at that folder. The agent can find repeated preferences and turn them into a skill for writing plans, writing code, or reviewing code.
## Collect the feedback you want to reuse
Use feedback from any Plannotator workflow:
* plan reviews
* document annotations
* local code reviews
* pull request and merge request reviews
Completed document and code-review feedback can return to the active agent. Save the results you want to reuse in a local folder. Plan reviews can also save final decisions under `/plans/` when **Save plans** is enabled.
Feedback may contain private plans, code, comments, file paths, and repository details. Keep the folder local unless you have reviewed its contents.
## Ask your agent to create a skill
Point the agent at your feedback folder and state what you want to improve:
```text theme={null}
Review the Plannotator feedback in .
Find preferences that appear across several reviews. Use them to create a
reusable skill for .
Cite the feedback behind each rule. Ignore one-off comments and old guidance.
Show me the proposed skill before you create or install it.
```
Use the same process to create separate skills for planning, coding, and code review. Separate skills keep each set of instructions focused on the task.
## Reuse the skill
Use the skill when you ask an agent to plan, write code, or review changes. If your agent supports hooks, commands, or scheduled jobs, you can also run the skill through those tools.
Review the skill as your preferences change. Remove rules that no longer match your work, and add new rules only when the feedback supports them.
Last verified against Plannotator OSS v0.25.0 on July 27, 2026. Maintained by the Plannotator project.
# Install Plannotator
Source: https://docs.plannotator.ai/open-source/start/installation
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
```bash theme={null}
curl -fsSL https://plannotator.ai/install.sh | bash
```
```powershell theme={null}
irm https://plannotator.ai/install.ps1 | iex
```
```bat theme={null}
curl -fsSL https://plannotator.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
```
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 `, 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.
```bash theme={null}
curl -fsSL https://plannotator.ai/install.sh | bash -s -- --minimal
```
```powershell theme={null}
& ([scriptblock]::Create((irm https://plannotator.ai/install.ps1))) -Minimal
```
`--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:
```bash theme={null}
curl -fsSL https://plannotator.ai/install.sh | bash -s -- --version vX.Y.Z
```
```powershell theme={null}
& ([scriptblock]::Create((irm https://plannotator.ai/install.ps1))) -Version vX.Y.Z
```
```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
```
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.
```bash theme={null}
curl -fsSL https://plannotator.ai/install.sh | bash -s -- --version vX.Y.Z --verify-attestation
```
```powershell theme={null}
& ([scriptblock]::Create((irm https://plannotator.ai/install.ps1))) -Version vX.Y.Z -VerifyAttestation
```
```bat theme={null}
curl -fsSL https://plannotator.ai/install.cmd -o install.cmd
install.cmd --version vX.Y.Z --verify-attestation
del install.cmd
```
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
Use `--purge` only when you intend to delete known local Plannotator data. The deleted data cannot be recovered.
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.
# Open Plannotator
Source: https://docs.plannotator.ai/open-source/start/open-plannotator
Start Plannotator from a supported coding agent or run it directly from the command line.
Start Plannotator from your coding agent when you want feedback returned to that agent. Run the `plannotator` command directly for terminal workflows and automation.
## Start from your coding agent
Choose your agent for its exact setup and commands:
| Agent | Open a plan | Open code changes |
| - | - | - |
| [Claude Code](/open-source/agents/claude-code) | Opens at `ExitPlanMode` | `/plannotator-review` |
| [Codex](/open-source/agents/codex) | Experimental `Stop` hook | `!plannotator review` or `$plannotator-review` |
| [OpenCode](/open-source/agents/opencode) | Planning agents call `submit_plan` | `/plannotator-review` |
| [Copilot CLI](/open-source/agents/copilot-cli) | Opens at `exit_plan_mode` | `/plannotator-review` |
| [Gemini CLI](/open-source/agents/gemini-cli) | Opens before `exit_plan_mode` | `/plannotator-review` |
| [Pi](/open-source/agents/pi) | `/plannotator-plan-mode`, `Ctrl+Alt+P`, or `pi --plan` | `/plannotator-review` |
| [Amp](/open-source/agents/amp) | Manual command | Command palette |
| [Droid](/open-source/agents/droid) | Manual command | `/plannotator-review` |
| [Kiro CLI](/open-source/agents/kiro-cli) | Installed skill or example agent | Installed skill |
Most command-based agents also provide `/plannotator-annotate` for a file or URL and `/plannotator-last` for the latest assistant message. See [Agents](/open-source/agents) to choose an agent, editor, or note app.
## Run it directly
| Command | Current behavior |
| - | - |
| `plannotator review` | Opens local changes from the detected Git, GitButler, Jujutsu, or Perforce project. |
| `plannotator review ` | Opens a GitHub pull request or GitLab merge request. |
| `plannotator annotate ` | Opens a supported document, plain-text config or data file, HTML file, web URL, or folder. |
| `plannotator annotate-last` | Opens the latest assistant message from the current supported agent session. |
| `plannotator last` | Short alias for `annotate-last`. |
| `plannotator archive` | Opens saved plan decisions in a read-only browser. |
| `plannotator sessions` | Lists active Plannotator server sessions. |
| `plannotator sessions --open N` | Reopens active session number `N`. |
| `plannotator --help` | Prints the command list. |
| `plannotator --version` | Prints the installed version. |
Local files opened for annotation must be 2 MiB or smaller. Eligible text files selected from a folder receive per-file version history just like supported files opened directly.
Run command-specific help before scripting a workflow:
```bash theme={null}
plannotator review --help
plannotator annotate --help
plannotator annotate-last --help
plannotator sessions --help
```
## Common options
`plannotator review` accepts `--git` or `--gitbutler` to force the provider. Pull request review uses a local checkout by default. Use `--no-local` when you only want the provider diff.
`plannotator annotate` accepts:
* `--markdown` to convert HTML input to Markdown instead of rendering it as HTML
* `--no-jina` to fetch a URL without Jina Reader
* `--gate` to add an approval action
* `--json` to emit a structured decision
* `--hook` to emit hook-native block or pass JSON
* `--require-approval` to make annotations and dismissal exit `1` in a strict `--gate --json` workflow
* `--result-file ` to atomically publish the structured result without overwriting an existing file
`--require-approval` and `--result-file` work only with direct `annotate --gate --json` calls. `plannotator annotate-last` accepts `--stdin`, `--gate`, `--json`, and `--hook`.
Running `plannotator` with no arguments is reserved for hook input. It expects JSON on standard input and is not the interactive entry point.
Last verified against Plannotator OSS v0.25.0 on July 27, 2026. Maintained by the Plannotator project.
# Annotate Your First Plan
Source: https://docs.plannotator.ai/open-source/start/quickstart
Annotate a Markdown plan, then open a folder to browse and annotate plans, specs, ADRs, and notes in one Plannotator session.
This quickstart shows two flows: annotate one Markdown plan, then open a folder and move between files in Plannotator's file browser. The first file checks your installation without depending on an agent hook.
Save this file as `plan.md`:
```md theme={null}
# Add request logging
1. Add a request ID to the HTTP middleware.
2. Log the method, path, status, and duration.
3. Add tests for successful requests.
```
Run:
```bash theme={null}
plannotator annotate plan.md --gate
```
Plannotator starts a temporary local server and opens the document in your browser. `--gate` adds an **Approve** action.
Select `Add tests for successful requests` and add this comment:
> Include a failed request so the test covers the error status and request ID.
The comment remains attached to the selected text.
Select **Send Feedback**. A direct terminal run writes the feedback to standard output.
Run the command again and select **Approve** to check the approval path.
Point Plannotator at a folder that contains your documents:
```bash theme={null}
plannotator annotate docs/
```
Plannotator opens a file browser for supported documents, plain-text configuration and data files, and HTML. Open a file. Add annotations. Then choose another file without starting a new session.
Try the folder flow with documentation or a local knowledge base that contains plans, specifications, ADRs, and notes. See [Annotate a Folder](/open-source/workflows/folders) for the full format list and workflow.
## Try it inside your agent
After completing the setup for your host, use its manual review command:
* Most command-based agents use `/plannotator-annotate plan.md`.
* Codex can run `!plannotator annotate plan.md` or use `$plannotator-annotate`.
* Amp exposes **Plannotator: Annotate file** in its command palette.
Agent plan review is host-specific. Claude Code, Copilot CLI, Gemini CLI, OpenCode, Pi, and Codex provide automatic or plan-mode review flows. Amp, Droid, and Kiro CLI use manual commands. See [Agents](/open-source/agents) for the exact behavior.
## Try the other entry points
```bash theme={null}
plannotator review
plannotator annotate-last
```
Use `review` inside a version-controlled project. `annotate-last` reads the most recent assistant message for supported agent sessions.
See [Open Plannotator](/open-source/start/open-plannotator) for the complete user-facing command list.
Last verified against Plannotator OSS v0.25.0 on July 27, 2026. Maintained by the Plannotator project.
# Install and Manage Plannotator Skills
Source: https://docs.plannotator.ai/open-source/start/skills
Install Plannotator's core or extra agent skills, choose specific skills and hosts, update them, and remove them.
The standard Plannotator installer already installs three core skills: `plannotator-review`, `plannotator-annotate`, and `plannotator-last`. Run a separate `npx skills` command only when you want the extra skills or an explicit subset of them.
## Core and extra skills
| Skill | Set | Installed by the standard installer | Purpose |
| - | - | - | - |
| `plannotator-review` | Core | Yes | Review local changes or a pull request. |
| `plannotator-annotate` | Core | Yes | Annotate a file, folder, or URL. |
| `plannotator-last` | Core | Yes | Annotate the latest agent message. |
| `plannotator-compound` | Extra | No | Analyze denied plans and produce a planning report. |
| `plannotator-setup-goal` | Extra | No, except for Kiro CLI | Set up goal-workflow files. |
| `plannotator-visual-explainer` | Extra | No, except for Kiro CLI | Create a visual HTML explanation. |
The full installer places core skills in Claude Code's directory and the shared Agent Skills directory. When it detects Kiro, it also installs `plannotator-setup-goal` and `plannotator-visual-explainer` for Kiro.
A [minimal installation](/open-source/start/installation#install-only-the-binary) skips every skill, command file, hook, agent integration setup, and optional runtime.
## Install the core skills
Use the [standard installer](/open-source/start/installation). It installs the binary and the host-specific skill bodies together, then replaces those managed copies when you run it again.
If you previously used a minimal installation, rerun the installer without `--minimal`. You do not need to remove the existing binary first.
The installer manages all three core skills together. It does not provide a flag for installing only one core skill.
## Install all extra skills
The guided installer can launch the Agent Skills CLI for you. You can also run it directly:
```bash theme={null}
npx skills add backnotprop/plannotator/apps/skills/extra --global
```
The interactive flow lets you choose which supported agents receive the skills.
## Install a specific set
Repeat `--skill` to select only the extras you want:
```bash theme={null}
npx skills add backnotprop/plannotator/apps/skills/extra \
--global \
--skill plannotator-compound \
--skill plannotator-visual-explainer
```
Add one or more `--agent` values for a repeatable host-specific install:
```bash theme={null}
npx skills add backnotprop/plannotator/apps/skills/extra \
--global \
--skill plannotator-compound \
--agent claude-code \
--yes
```
Omit `--agent` and `--yes` when you want the interactive host selector. The Agent Skills CLI [README](https://github.com/vercel-labs/skills) documents its current `--skill`, `--agent`, `--global`, and `--yes` options.
## Choose whether the model can start a skill
Plannotator's Claude Code and shared Agent Skill copies are user-started by default. During a guided install, you can choose which of those installed skills the model may start without an explicit skill command.
Run the guided questions again:
```bash theme={null}
curl -fsSL https://plannotator.ai/install.sh | bash -s -- --reconfigure
```
```powershell theme={null}
& ([scriptblock]::Create((irm https://plannotator.ai/install.ps1))) -Reconfigure
```
```bat theme={null}
curl -fsSL https://plannotator.ai/install.cmd -o install.cmd
install.cmd --reconfigure
del install.cmd
```
For an automated install, pass a comma-separated list:
```bash theme={null}
curl -fsSL https://plannotator.ai/install.sh | bash -s -- \
--non-interactive \
--model-invocable plannotator-review,plannotator-compound
```
`--model-invocable` changes how an installed Claude Code or shared Agent Skill may be started. It does not install a missing extra skill. Use `--model-invocable none` to keep those managed copies user-started.
## Understand host-specific files
The same `/plannotator-*` command name can refer to different host features. Check the host before editing or removing files.
| Host | What provides the command | Location or package |
| - | - | - |
| Claude Code | Claude-specific agent skills that also appear as slash commands | `~/.claude/skills/plannotator-*`, or `$CLAUDE_CONFIG_DIR/skills/plannotator-*` when set |
| Codex | Shared Agent Skills, started with `$plannotator-*` | `~/.agents/skills/plannotator-*` |
| Kiro CLI | Kiro-specific skills and an example custom agent | `~/.kiro/skills/plannotator-*` and `~/.kiro/agents/plannotator.json` |
| OpenCode | Native Markdown command files plus the separately configured OpenCode plugin | On macOS, Linux, and WSL: `${XDG_CONFIG_HOME:-$HOME/.config}/opencode/commands`. On Windows PowerShell and Command Prompt: `%USERPROFILE%\.config\opencode\commands`. The plugin is `@plannotator/opencode`. |
| Gemini CLI | Native TOML command files plus a policy and hook | `~/.gemini/commands`, `~/.gemini/policies`, and `~/.gemini/settings.json` |
| Claude Code, Copilot CLI, and Droid | Host marketplace plugins can add hooks or commands | Managed by that host's plugin system |
| Pi | Commands and plan mode come from the Pi extension | `@plannotator/pi-extension` |
| Amp | Command-palette actions come from an Amp plugin file | `~/.config/amp/plugins/plannotator.ts` or `.amp/plugins/plannotator.ts` |
Installing an Agent Skill does not install or update a host plugin, extension, or native command file.
## Distinguish skills from Plannotator packages
| Item | What it is | How users install it |
| - | - | - |
| `plannotator` | The local executable that starts the review server and browser UI | The Plannotator installer |
| Agent skill | A `SKILL.md` instruction package that tells an agent how to run a Plannotator workflow | The Plannotator installer or `npx skills add` |
| Slash command | A host-visible command. In Claude Code it can be backed by a skill; in other hosts it can be a native command file or plugin command | The installer, a plugin, or an extension |
| Plugin or extension | Host integration code for hooks, tools, plan mode, or command registration | The host's plugin or package manager |
| `@plannotator/ui` | React components, hooks, and styles for embedding Plannotator's document UI in another application | `npm install @plannotator/ui @plannotator/core` |
| `@plannotator/core` | Browser-safe types and utilities used by `@plannotator/ui` | Installed as an npm library, normally with `@plannotator/ui` |
`@plannotator/ui` and `@plannotator/core` are for application developers. They do not install the `plannotator` command, Agent Skills, or host plugins.
The standard installer downloads the `plannotator` executable from GitHub Releases. It does not install either reusable npm package. Update `@plannotator/ui` and `@plannotator/core` through the package manager for the application that embeds them.
## Update skills
Rerun the standard Plannotator installer to replace its managed core skills with the copies from the selected Plannotator release. This also refreshes the binary and other installer-managed files.
Update extra skills installed through the Agent Skills CLI:
```bash theme={null}
npx skills update plannotator-compound plannotator-setup-goal \
plannotator-visual-explainer --global
```
You can name one skill instead. Updating an extra skill does not update the Plannotator binary or a host plugin.
## Remove skills
If you enabled extras through the guided installer, first save `no extras` as the installer preference. Otherwise a later installer run can offer to add them again:
```bash theme={null}
curl -fsSL https://plannotator.ai/install.sh | bash -s -- --no-extras
```
```powershell theme={null}
& ([scriptblock]::Create((irm https://plannotator.ai/install.ps1))) -NoExtras
```
```bat theme={null}
curl -fsSL https://plannotator.ai/install.cmd -o install.cmd
install.cmd --no-extras
del install.cmd
```
Then remove extras installed through the Agent Skills CLI:
```bash theme={null}
npx skills remove --global \
plannotator-compound \
plannotator-setup-goal \
plannotator-visual-explainer
```
To remove installer-managed core skills manually, delete only these directories:
| Copy | macOS, Linux, or WSL | Windows PowerShell or Command Prompt |
| - | - | - |
| Claude Code | `plannotator-review`, `plannotator-annotate`, and `plannotator-last` under `$CLAUDE_CONFIG_DIR/skills` when that variable is set, or under `~/.claude/skills` otherwise | The same three directories under `%CLAUDE_CONFIG_DIR%\skills` when that variable is set, or under `%USERPROFILE%\.claude\skills` otherwise |
| Shared Agent Skills for Codex and compatible hosts | The same three directories under `~/.agents/skills` | The same three directories under `%USERPROFILE%\.agents\skills` |
A later full installer run restores all three managed core skills.
For Kiro CLI, remove only the Plannotator skill directories under `~/.kiro/skills`. Remove `~/.kiro/agents/plannotator.json` separately if you no longer want the example agent. Removing a skill does not remove the Plannotator binary, a host plugin, or saved Plannotator data.
See [Installation](/open-source/start/installation#remove-plannotator) to remove the executable or local data.
Last verified against Plannotator OSS v0.25.1 on July 31, 2026. Maintained by the Plannotator project.
# Review Plannotator Sessions over Tailscale
Source: https://docs.plannotator.ai/open-source/tailscale
Open Plannotator review and annotation sessions from another device through Tailscale Serve without binding the server beyond localhost.
Use `--tailscale` to open a Plannotator session from another device on your tailnet. Plannotator keeps its server on `127.0.0.1` and publishes an HTTPS proxy through [Tailscale Serve](https://tailscale.com/docs/features/tailscale-serve).
The session is available only through your tailnet. Plannotator uses Serve, never Tailscale Funnel.
## Prerequisites
Before you start, verify this configuration:
* [Install or update Plannotator](/open-source/start/installation) on the machine that runs your agent.
* Run `plannotator --version` and verify `v0.27.0` or later.
* [Install Tailscale](https://tailscale.com/download) on the agent host and review device.
* Connect both devices to the same tailnet.
* Permit the review device to reach the agent host through your Tailscale access rules.
* Enable HTTPS certificates for the tailnet. On first use, Tailscale can open an administrator consent flow.
The review device needs Tailscale and a browser. It does not need the Plannotator CLI.
Run `tailscale status` on the agent host. Before you start Plannotator, resolve any login or daemon error.
## Start a remote review
Run Plannotator on the agent host:
```bash theme={null}
plannotator review --tailscale
```
The same flag works with document annotation and the last-message picker:
```bash theme={null}
plannotator annotate path/to/spec.md --tailscale
plannotator annotate-last --tailscale
```
Plannotator prints the HTTPS session URL to standard error. An interactive terminal also displays a QR code.
Verify that Tailscale is connected on the review device. Scan the QR code or open the printed URL.
`--tailscale` works in the compiled Plannotator CLI. The Pi extension does not accept this flag.
## How the connection works
Plannotator performs these steps for each `--tailscale` session:
1. It starts the review server on `127.0.0.1`.
2. It reads the current Tailscale Serve configuration.
3. It refuses to replace an existing Serve mapping on the selected port.
4. It runs the following command with the session port:
```bash theme={null}
tailscale serve --bg --https= http://127.0.0.1:
```
5. Tailscale terminates HTTPS and proxies requests to the loopback server.
6. Plannotator prints the Serve URL and displays a QR code in an interactive terminal.
7. Plannotator removes its Serve mapping at normal session exit.
Mappings on other ports remain unchanged. A pre-existing mapping on the selected port stops startup instead of being replaced.
`--tailscale` forces local mode for that session. It overrides `PLANNOTATOR_REMOTE`, SSH detection, and `PLANNOTATOR_URL_HOST`.
## Understand the security boundary
Tailscale Serve makes the session reachable through the tailnet, not the public internet. Tailscale access rules still govern which devices can reach the host.
Plannotator does not add a login screen or per-request authentication. Every permitted tailnet peer can use the session UI and its local API.
The embedded agent terminal is disabled for `--tailscale` sessions. Enable it only for a tailnet where every permitted peer is trusted:
```bash theme={null}
PLANNOTATOR_AGENT_TERMINAL_REMOTE=1 plannotator annotate path/to/spec.md --tailscale
```
This variable exposes command execution through the session UI. Its terminal token is not an authentication boundary.
## Advertise a Tailscale host in remote mode
`PLANNOTATOR_URL_HOST=auto` solves a different problem. It produces a reachable URL for Plannotator remote mode without starting Tailscale Serve.
When another system already provides private routing or port forwarding, use this configuration:
```bash theme={null}
export PLANNOTATOR_REMOTE=1
export PLANNOTATOR_URL_HOST=auto
plannotator review
```
Plannotator first reads the machine's Tailscale MagicDNS name. A fallback requires exactly one Tailscale IPv4 address in `100.64.0.0/10`.
Detection runs once per process. Detection failure prints a warning and falls back to `localhost`.
This value changes only the advertised URL. Remote mode still binds to `0.0.0.0`, and you remain responsible for network access.
To make the value persistent, save it in `~/.plannotator/config.json`:
```json theme={null}
{
"urlHost": "auto"
}
```
`PLANNOTATOR_URL_HOST` takes precedence over `urlHost` in the configuration file. An empty environment value suppresses the saved value.
## Remove a stale Serve mapping
Plannotator removes its mapping after normal exit, `SIGINT`, `SIGTERM`, or `SIGHUP`. Failed cleanup retries once and prints the manual command.
`SIGKILL` or a host restart can leave the background mapping active. Inspect the current configuration:
```bash theme={null}
tailscale serve status
```
Remove the mapping for the affected port:
```bash theme={null}
tailscale serve --https= off
```
Do not remove mappings for unrelated ports.
## Troubleshoot startup and access
### The Tailscale CLI is unavailable or logged out
Run:
```bash theme={null}
tailscale status
```
Install Tailscale or restore the daemon and sign in. Then run the Plannotator command again.
### Tailscale requests HTTPS approval
Complete the administrator consent flow that Tailscale displays. Then run the Plannotator command again.
See [Set up HTTPS certificates](https://tailscale.com/docs/how-to/set-up-https-certificates) for the tailnet requirement.
### The selected port already has a Serve mapping
Inspect the Serve configuration:
```bash theme={null}
tailscale serve status
```
Remove a stale mapping with the exact command above. Keep an intentional mapping and select another Plannotator port:
```bash theme={null}
PLANNOTATOR_PORT=19433 plannotator review --tailscale
```
### The URL does not open on the review device
Verify that both devices are connected to Tailscale. Verify that access rules permit the review device to reach the host.
Then inspect the active mapping:
```bash theme={null}
tailscale serve status
```
Tailscale documents Serve status and removal commands in its [Serve CLI reference](https://tailscale.com/docs/reference/tailscale-cli/serve).
### The QR code is absent
When standard error is an interactive terminal, Plannotator displays the QR code. Use the printed HTTPS URL in other environments.
### A gated annotation cannot start
A Tailscale publishing failure returns exit code `1` for a normal command. A strict annotation gate returns exit code `2`.
Strict gates use `--require-approval` or `--result-file`. A startup failure does not create a result file.
## Integration limits
Only `review`, `annotate`, `annotate-last`, and its `last` alias accept `--tailscale`. Other subcommands reject the flag.
Agent hooks do not add `--tailscale` automatically. When you need tailnet access, start a file gate directly:
```bash theme={null}
plannotator annotate path/to/plan.md --tailscale --gate
```
See [Remote access](/open-source/remote-access) for trusted private networks, SSH tunnels, and development-container forwarding.
Last verified on August 12, 2026, against Plannotator `v0.27.0` and product commits `5f33b72` and `ed6f44b`. Maintained by the Plannotator project.
# Troubleshoot Plannotator
Source: https://docs.plannotator.ai/open-source/troubleshooting
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 | On Claude Code 2.1.287 or later, the plugin's Plannotator mod opens the review when Claude calls `ExitPlanMode`, and Claude does not wait. On older versions, in `claude -p` and SDK runs, on Windows, or with the mod off, the plugin intercepts `ExitPlanMode` through a `PermissionRequest` hook, and Claude waits. 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-plan-mode`. |
| 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.
## Claude Code still waits for my review
On Claude Code 2.1.287 or later, the [Plannotator mod](/open-source/agents/claude-code#the-plannotator-mod) lets Claude keep going while you review. If Claude still waits:
1. Update the plugin. In a terminal, run `claude plugin marketplace update plannotator`, then `claude plugin update plannotator@plannotator`, then restart Claude Code. Refreshing the marketplace alone does not update the plugin.
2. Update the `plannotator` binary by running the installer again. With an older binary, plan review falls back to the waiting flow.
3. Check that `PLANNOTATOR_CLAUDE_MOD` is not set to `0` and that `~/.plannotator/config.json` has no `"claudeCodeMod": false`.
4. The mod does not run in `claude -p` or SDK runs, or on Windows. Those always wait.
5. To report a problem, start Claude Code with `PLANNOTATOR_MOD_DEBUG=1` and attach `~/.plannotator/claude-code-mod/debug.log`.
## Remote SSH and development containers
Confirm that the agent process inherited both remote settings:
```bash theme={null}
env | grep '^PLANNOTATOR_REMOTE='
env | grep '^PLANNOTATOR_PORT='
```
With the default remote port, forward the session from your local machine:
```bash theme={null}
ssh -L 19432:127.0.0.1:19432 user@host
```
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.
Follow [Remote access](/open-source/remote-access) for the SSH command, development-container configuration, direct private-network access, verification steps, and remote-sharing boundary.
The embedded agent terminal is disabled in remote mode by default.
Set `PLANNOTATOR_AGENT_TERMINAL_REMOTE=1` only on a trusted connection. This setting enables command execution through the forwarded UI.
## 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 fails, use 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`.
## A local annotation file is too large
Single-file and folder annotation accept local files up to 2 MiB. A larger file fails with `File too large to annotate (max 2MB)`. Reduce or split the file before reopening it. In a strict `annotate --gate --json` workflow, this startup failure exits `2`.
## A large untracked file appears as binary
Code review loads and diffs untracked text files up to 5 MiB. An untracked file over that limit appears as a binary addition and Plannotator refuses to load its contents. Exclude, reduce, or commit the file if you need to inspect it through another comparison.
## Sharing fails
Check whether sharing is disabled:
```bash theme={null}
env | grep '^PLANNOTATOR_SHARE='
```
`PLANNOTATOR_SHARE=disabled` overrides `config.json` for integrations that use Plannotator's shared configuration resolver. OpenCode checks an explicit OpenCode `share` setting first, so set that value to `"disabled"` as well. For other integrations, remove the environment variable or set an enabled value for a new session when sharing is intended.
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 `config.json` in the active data directory. Plannotator chooses that directory in this order:
1. `PLANNOTATOR_DATA_DIR`, with leading `~` expansion
2. An existing `~/.plannotator`
3. `$XDG_DATA_HOME/plannotator` when `XDG_DATA_HOME` is absolute
4. `~/.plannotator`
An existing `~/.plannotator` wins over XDG. A relative `XDG_DATA_HOME` is ignored, and Plannotator does not implicitly use `~/.local/share`.
If `PLANNOTATOR_DATA_DIR` is relative, Plannotator resolves it from the working directory where that process launched. The installer, agents, and shells can use different directories for the same value. Make sure that you inspect every working directory, not only the environment variable.
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.
## Cursor review jobs fail to start
Cursor review jobs use Ask mode and pass `--sandbox enabled` by default. On systems where Cursor's sandbox cannot start, including some NixOS or AppArmor-restricted Linux setups, retry without the forced sandbox:
```bash theme={null}
PLANNOTATOR_CURSOR_SANDBOX=0 plannotator review
```
For a persistent setting, add `"cursorSandbox": false` to `config.json`. Plannotator then omits the sandbox flag and defers to your Cursor Agent configuration. Write protection depends on `--mode ask` and your Cursor settings in this mode.
## AI panels are missing
Check for an explicit kill switch:
```bash theme={null}
env | grep '^PLANNOTATOR_AI='
```
`PLANNOTATOR_AI=disabled` removes Ask AI, Review Agents, and Guided Review and disables their provider and job endpoints. Remove it or set another value, then start a new session. Ordinary reviews and external annotation submission still work.
## 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.25.1 on July 31, 2026. Maintained by the Plannotator project.
# Run Agent Reviews, Code Tours, and Guided Reviews
Source: https://docs.plannotator.ai/open-source/workflows/agent-reviews
Run a code review, Code Tour, Guided Review, or custom review skill with an installed local agent CLI and understand its provider guardrails.
Open the **Agents** tab in a code review to run a separate agent over the current change. Job progress and logs stream into Plannotator. Completed findings appear as review annotations, where you decide what to keep, edit, copy, or send.
Plannotator does not automatically post completed job findings to GitHub or GitLab or send them to the coding agent. You remain responsible for checking each finding and choosing the review destination. The provider process still has the permissions described below while the job runs.
## Choose a review job
* **Code Review** looks for correctness, security, maintainability, and other concrete problems in the current change.
* **Code Tour** creates a narrated walkthrough with checkpoints. It runs with Claude or Codex.
* **Guided Review** organizes the change into ordered sections with summaries and live diffs. It can run with any supported review engine.
* **Custom review** runs a review profile from an enabled global agent skill.
You can run more than one engine, watch logs while each job runs, stop a running job, and compare their findings in the same review.
## Install and authenticate an agent CLI
Plannotator detects engines by checking for their command on `PATH`. The command must also be authenticated and have a usable model configuration.
| Engine | Command Plannotator detects | Supported jobs |
| - | - | - |
| Claude Code | `claude` | Code Review, Code Tour, Guided Review |
| Codex CLI | `codex` | Code Review, Code Tour, Guided Review |
| Cursor CLI | `agent` | Code Review, Guided Review |
| OpenCode | `opencode` | Code Review, Guided Review |
| Pi | `pi` | Code Review, Guided Review |
| GitHub Copilot CLI | `copilot` | Code Review, Guided Review |
Model choices come from the installed provider where supported. Codex is the exception: Plannotator maintains the Codex model and reasoning-effort choices to match the current Codex CLI. A provider can appear installed but fail to launch if its CLI is signed out, lacks a configured model, or cannot access the repository.
## Understand provider guardrails
Plannotator tells every review job not to modify files or post comments. Those prompt instructions do not enforce read-only execution. The available guardrails depend on the provider:
* Codex runs with `--full-auto` in its workspace-write sandbox.
* Cursor runs in Ask mode with its sandbox enabled by default. If Cursor's sandbox cannot start on a restricted Linux system, set `PLANNOTATOR_CURSOR_SANDBOX=0` or set `"cursorSandbox": false` in `config.json` to omit the sandbox flag. In that mode, write protection depends on Ask mode and your Cursor configuration.
* OpenCode runs with its planning agent and retains shell access.
* Pi excludes its direct edit and write tools but retains Bash access.
* Claude receives file-reading tools and inspection-oriented Git and forge command patterns. Direct file-writing tools, WebFetch, WebSearch, and general-purpose shells are denied, but some allowed Git and forge patterns are broader than a strict read-only subcommand list.
* GitHub Copilot denies its direct write tool and specific high-risk version-control and forge operations. It allows Git and forge command families and auto-denies other shell tools.
Treat provider output as untrusted review evidence and inspect each claimed issue. Run a review job only where the selected provider's permissions and your repository isolation are acceptable.
## Run agents on the intended comparison
The job receives the comparison currently open in Plannotator. Choose the correct Git mode, Jujutsu revision, GitButler view, or pull-request scope before launching it.
For GitButler Stack and Branch reviews, the prompt identifies the on-screen patch as authoritative because filesystem reads can see other applied stacks or later branch layers. See [Review GitButler Workspaces, Stacks, and Branches](/open-source/workflows/gitbutler#keep-annotations-tied-to-the-right-comparison) for this comparison boundary. For stacked pull requests, an agent can review either **Layer** or **Full stack** when the local checkout exists.
A GitHub pull request or GitLab merge request needs the temporary local checkout that Plannotator prepares by default. Agent jobs are unavailable with `--no-local` or after checkout preparation fails. See [Review pull requests and merge requests](/open-source/workflows/pull-requests).
## Reopen a Guided Review
Plannotator saves each successfully generated Guided Review under the data directory. Open **Previous guides** in the Agents tab to reopen or delete one. The list shows its title, age, and section progress.
Section completion persists with the saved guide. A completed section starts collapsed when you reopen it, but you can expand it without changing the state of other sections. Selecting a file chip, annotation, or AI citation expands the containing section and file, focuses it, and scrolls it into view.
A saved guide records the repository commit present when it was generated. If the repository has moved to another commit, the saved-guide list and reopened guide mark it **Diff changed**. Treat that warning as a reason to confirm that its summaries and file ranges still match the review.
Disable new guide writes with either setting:
```bash theme={null}
export PLANNOTATOR_GUIDE_HISTORY=0
```
```json theme={null}
{
"guideHistory": false
}
```
Disabling history does not delete saved guides. Existing guide data remains readable through the local API, but the normal guide browser is hidden when AI features are disabled.
## Add a custom review
Choose **Add a review** in the Agents tab to enable a global skill as a review profile. Plannotator searches global skill directories, including:
* `~/.claude/skills`
* `~/.codex/skills`
* `~/.agents/skills`
* The XDG agents skills directory when configured
Repository-local skills are intentionally ignored for custom reviews because a fork or downloaded repository should not be able to supply the prompt that reviews itself.
If the skill contains `SKILL.md`, its body replaces the built-in review prompt for that profile. Plannotator reads it again at launch, so saved edits apply to the next job. The skill can refer the reviewer to supporting files in its own directory. The selected provider's guardrails still apply.
Enabled review profiles are stored in `/review-skills.json`. Use the Agents tab to manage this file instead of editing it by hand.
For quick questions about selected lines instead of a full background review, use [Ask AI during a review](/open-source/workflows/ask-ai).
Last verified on July 31, 2026, using Plannotator product commit `7cd023c`. Maintained by the Plannotator project.
# Add Annotations and Send Feedback
Source: https://docs.plannotator.ai/open-source/workflows/annotations-and-feedback
Comment on exact text, add a global comment, draw on image attachments, and choose whether to request changes, approve, or dismiss a review.
Select the smallest useful passage, add the requested change, then choose **Send Feedback**. Plannotator keeps the selected text with the comment so the agent can locate the issue.
## Annotation types
| Action | Use it for |
| - | - |
| **Delete** | Mark selected text for removal. |
| **Comment** | Explain a change, question, replacement, or missing detail. |
| **Quick label** | Apply a configured label such as a test or scope reminder. |
| **Looks good** | Record that a selected passage needs no change. |
| **Global comment** | Add feedback about the whole plan or document. |
### Find Global Comment
In a rendered Markdown plan or document, **Global comment** is in the document action bar. On a narrower layout, its label shortens to **Comment** or to an icon. It is not shown while the Markdown editor or rendered Markdown diff replaces the normal document view.
In rendered HTML, the equivalent action is labeled **Comment**. Selecting **Hide tools** hides this action with the other HTML annotation controls.
Ordinary rendered Markdown annotate sessions do not intentionally hide Global Comment. If the full text label is missing, look for **Comment** or the speech-bubble icon with the **Add global comment** tooltip. Plannotator chooses the full, short, or icon-only label from the current width of the document action bar.
The standalone archive is read-only. It hides Global Comment, Attachments, selection composers, direct-edit and notes-save actions, and other document mutation controls. Linked documents opened from the archive remain read-only. Both the Bun and Pi servers also reject archive mutation requests, so this boundary does not depend on a client-side flag.
### Attach and mark up images
You can paste or upload an image into a comment or use **Images** for a document-level attachment. Plannotator stores an uploaded image as a temporary local file and includes its name and path in the feedback sent to the agent.
Open an attached image to draw with the pen, arrow, or circle tools. Drawing applies only to that image. Plannotator does not provide a freehand layer over Markdown, rendered HTML, or code diffs.
## Make a direct edit
Open the Markdown editor when rewriting the text is clearer than describing the change. Plannotator records added and removed lines and includes a unified diff in the feedback.
Eligible local Markdown, MDX, and text files can also be saved to disk with `Cmd/Ctrl+S`. The feedback marks those changes as already applied so the agent does not repeat them. See [Annotate documents](/open-source/workflows/documents#edit-markdown) for the write and conflict behavior.
## Check feedback before sending
Open **Export** and select **Annotations** to inspect the generated Markdown. You can copy it or download `annotations.md` without ending the review.
The exported feedback can include:
* source line labels and selected text
* comments, deletions, quick labels, and general feedback
* attached image paths
* direct-edit diffs and file changes already saved to disk
* a marker when an annotation refers to a changed block in the version diff
## Choose the review decision
| Action | What it means |
| - | - |
| **Send Feedback** | Requests another revision. Agent plan flows treat it as the request-changes or rejection path. Direct `--json` annotation returns `{"decision":"annotated","feedback":"..."}`. |
| **Approve with Notes** | Approves the current content and sends non-blocking implementation guidance when the active agent or JSON transport supports approval notes. |
| **Approve** | Approves the current content without requesting another revision. It is available only when an agent plan flow or `--gate` provides an approval gate. |
| **Close** in an annotation session | Ends the session without sending feedback. Structured JSON reports `{"decision":"dismissed"}`. |
| **Cancel** in a modal | Closes that confirmation and returns to the review. It does not send feedback, approve, dismiss, or end the session. |
If pending feedback would be dropped by **Approve** or **Close**, Plannotator opens a warning. Choose **Cancel** to keep the session and its pending feedback open.
`--gate` adds **Approve**, but it does not make every other decision fail the calling process. In hook-native mode, **Approve** and **Close** both produce empty output, which lets the host hook pass. Use direct `--gate --json --require-approval` when approval must be the only successful outcome. See [Approval gates and automation hooks](/open-source/reference/hooks).
## Know where feedback goes
When a supported agent opens Plannotator, **Send Feedback** returns the generated feedback to that agent session. A direct CLI run prints it to standard output.
The embedded terminal is different. Starting it launches a new local agent CLI process in the review's working directory. When that terminal is ready, **Send Feedback** goes to the new agent and the Plannotator window stays open. It does not reconnect to or deliver feedback to the original agent that opened the review.
Plannotator does not keep a completed OSS review session attached to the original agent across multiple feedback rounds.
## End or reopen a session
**Send Feedback**, **Approve**, and **Close** normally end the temporary local server. If the agent revises the content and opens Plannotator again, that is a new review session. The completed page can remain visible when **Auto-close Tab** is off; change that browser preference in **Settings > General**.
Draft annotations and direct edits are saved under the Plannotator data directory while a session is open, so a server or browser interruption can restore them. `plannotator sessions --open` can reopen a server that is still running. Draft recovery, version history, and reopening a live server do not restore a completed connection to the original agent.
Last verified on August 1, 2026, using Plannotator product commit `d53cbfb`. Maintained by the Plannotator project.
# Ask AI during a review
Source: https://docs.plannotator.ai/open-source/workflows/ask-ai
Ask a configured local AI provider about selected diff lines while keeping its answers separate from submitted review feedback.
Select lines in a code diff and choose **Ask AI** to ask a question about that code. The answer streams into the AI sidebar and stays attached to the file in the chat history.
You can also ask a general question from the AI tab. Plannotator includes the current comparison in the request, such as uncommitted changes, a branch comparison, a Jujutsu revision, a GitButler stack, or a pull-request checkout. When you switch the comparison, the next question receives the new review context.
Ask AI is an explanation tool. Its conversation is separate from your annotations and final review. Copy a useful conclusion into a normal annotation if you want it included when you send feedback.
## Ask this session
When Plannotator is opened from Claude Code 2.1.287 or later (with the Plannotator mod), Pi, or OpenCode 2, Ask AI is answered by the agent session that opened it. This is the only Ask AI option there. There is no provider or model picker, and the provider settings below do not apply. Your question shows in the agent's chat, and the agent already knows the conversation. See [Ask this session](/open-source/workflows/ask-this-session).
## Configure a provider
You pick a provider when Ask this session is not available: Claude Code without the mod, OpenCode 1, Codex and the other agents, remote mode, `--tailscale`, or a `plannotator` command you run yourself.
Plannotator detects supported AI providers from their local command-line tools. Install and authenticate or configure at least one provider before opening the review.
| Provider | Local requirement | Permission behavior |
| - | - | - |
| Claude | Install and authenticate the `claude` CLI. | Plannotator starts with read and search tools plus a limited set of inspection commands. Other tool use can require approval. |
| Codex | Install and authenticate the `codex` CLI. | Plannotator pins the Ask AI session to Codex's read-only sandbox. Your configured approval policy still applies. |
| OpenCode | Install and authenticate the `opencode` CLI. | OpenCode handles tool permissions and can show approval requests in the chat. |
| Pi | Install and configure the `pi` CLI and its model providers. | Pi controls tool execution through its own local runtime. Plannotator does not expose a Pi permission gate. |
Plannotator does not create accounts or manage provider API keys. If a provider is detected but cannot answer, verify its authentication and model configuration by running its CLI directly.
Open **Settings > AI** to choose a provider and model. The choice persists across sessions.
For the first session, Plannotator prefers the matching provider when it is available:
| Calling agent | Preferred provider |
| - | - |
| Claude Code | Claude |
| Codex | Codex |
| OpenCode | OpenCode |
| Pi | Pi |
Other agents use the saved provider or the available server default.
Changing the provider or model starts a new AI session. Earlier messages remain visible, but they are not part of the new provider conversation.
## Disable AI features
Set `PLANNOTATOR_AI=disabled` before starting Plannotator to remove Ask AI, Review Agents, and Guided Review from the UI and disable their provider and job endpoints:
```bash theme={null}
PLANNOTATOR_AI=disabled plannotator review
```
Ordinary plan, document, and code review still work. External agents can still open reviews and submit annotations. Saved Guided Review files are retained, but their in-app history browser is hidden while AI is disabled. The annotate-mode agent terminal is separate and keeps its own settings.
## Ask a focused question
1. Select the smallest useful line range in the diff.
2. Choose **Ask AI** in the annotation toolbar.
3. Ask a concrete question about behavior, risk, or intent.
4. Verify the answer against the patch and repository before turning it into review feedback.
For example:
```text theme={null}
Can this error path leave the transaction open? Point to the relevant cleanup code.
```
The selected lines are included even when the overall diff must be shortened to fit the provider's context window.
## Pull requests need a local checkout
Ask AI can read local-change reviews immediately. For a GitHub pull request or GitLab merge request, it needs the temporary local checkout that Plannotator prepares by default. If preparation is still running, retry after it finishes.
Ask AI is unavailable for a pull-request review started with `--no-local`, because that mode intentionally retains only the provider diff. See [Review pull requests and merge requests](/open-source/workflows/pull-requests) for the checkout boundary.
Last verified against Plannotator OSS v0.25.0 on July 27, 2026. Maintained by the Plannotator project.
# Ask This Session: Ask AI Answered by Your Agent
Source: https://docs.plannotator.ai/open-source/workflows/ask-this-session
When Claude Code, Pi, or OpenCode 2 opens Plannotator, Ask AI questions go to that agent session, which already knows the conversation.
Since Plannotator 0.28.0, Ask AI can be answered by the agent session that opened Plannotator. Plannotator calls this **Ask this session**. The agent already knows the conversation, so you do not have to explain the context.
## Where it works
| Agent | Where the session answers |
| - | - |
| [Claude Code](/open-source/agents/claude-code) 2.1.287 or later, with the Plannotator mod on | Plan review, code review, annotate, and `/plannotator-last` |
| [Pi](/open-source/agents/pi) | Plan review, code review, annotate, and `/plannotator-last` |
| [OpenCode](/open-source/agents/opencode) 2 | Code review, annotate, and `/plannotator-last`. Plan review gets a quick answer only. |
In these sessions, Ask this session is the only Ask AI option. There is no provider or model picker, and a provider you saved before is not used.
## How it works
* Your question shows in the agent's chat. The answer streams back into Plannotator.
* The question and the answer become part of the agent's conversation.
* If the agent is busy with a turn, Plannotator asks what to do: **Ask when it finishes** or **Interrupt and ask now**.
* Stopping a question stops only that question.
* If the session closes or cannot be reached, Plannotator says so. It does not switch to a different AI.
## OpenCode 2 plan review
During plan review, the OpenCode 2 session is waiting for your plan decision, so it cannot run a full turn. You get a quick answer from the session's context, labeled "Quick answer from this session". Nothing is added to the conversation.
## When you pick a provider instead
Ask AI uses a provider you pick, as described in [Ask AI during a review](/open-source/workflows/ask-ai#configure-a-provider), when:
* the session is in remote mode or published with `--tailscale`
* Plannotator was opened from OpenCode 1
* the Claude Code mod is off, or Claude Code runs without it (versions before 2.1.287, `claude -p`, SDK runs, Windows)
* you run the `plannotator` command yourself, outside an agent session
## What still uses its own models
Agent reviews, Code Tour, and Guided Review are separate from Ask AI. They run their own Claude or Codex models, or another installed agent CLI, even in a session where Ask AI uses the session. See [Run agent reviews](/open-source/workflows/agent-reviews).
Last verified against Plannotator v0.28.0 on October 4, 2026. Maintained by the Plannotator project.
# Open and Annotate Markdown, Documents, URLs, and Folders
Source: https://docs.plannotator.ai/open-source/workflows/documents
Open a Markdown file, plain-text data file, web page, HTML file, or folder in Plannotator, then annotate it or send edits back to your agent.
Use `plannotator annotate` to open a supported document or plain-text config file, a web page, or a folder.
## Open a Markdown or text document
```bash theme={null}
plannotator annotate README.md
plannotator annotate notes.txt
plannotator annotate config.yaml
plannotator annotate https://example.com/guide
plannotator annotate docs/
```
When you run the command directly, Plannotator starts a temporary local server, opens the annotation UI, and waits for your response. **Send Feedback** prints formatted feedback to stdout. Agent skills and commands return the same feedback to the active agent session.
Add `--gate` when the document needs an explicit approval decision:
```bash theme={null}
plannotator annotate specification.md --gate
```
## Open a folder
Pass a folder to open the file browser:
```bash theme={null}
plannotator annotate docs/
```
The browser lists the same supported local formats as direct file annotation:
* documents: `.md`, `.mdx`, and `.txt`
* plain-text config and data: `.yaml`, `.yml`, `.json`, `.jsonc`, `.json5`, `.toml`, `.ini`, `.cfg`, `.conf`, `.properties`, `.csv`, `.tsv`, `.log`, `.xml`, and `.env.example`
* HTML: `.html` and `.htm`
Plain-text config and data files keep their content unchanged and use the standard text annotation view. A bare `.env` file is excluded because it commonly contains secrets and annotation history can store content copies. Source-code extensions are excluded; use [code review](/open-source/workflows/local-changes) for them.
Only Markdown and MDX use Markdown frontmatter rules. A supported non-Markdown file that begins with `---` keeps those lines as document content.
Each local file must be 2 MiB or smaller. Select a file to annotate it, then move to another file without starting a new Plannotator session. Common generated and dependency directories, including `node_modules`, `dist`, and `build`, are skipped.
See [Annotate a Folder](/open-source/workflows/folders) for file-browser shortcuts, folder feedback, and large-folder limits.
## Follow links between local documents
In rendered Markdown, Plannotator opens relative links to `.md`, `.mdx`, `.txt`, `.html`, and `.htm` files inside the same review UI. It also opens `[[wiki-links]]`; a wiki-link without an extension resolves as a Markdown file. Relative paths are resolved from the active document.
Use the file badge or sidebar to return to the previous document. Annotations on linked documents are included when you send the review's combined feedback.
Links to a heading in another local document open the document but do not scroll to that heading. Plannotator strips the link fragment before opening the linked document. A file selected from a folder can receive per-file version history, while an ordinary document opened only through a link does not. See [Version history](/open-source/workflows/version-history).
## Open a web page
Plannotator converts web pages to Markdown before annotation. Jina Reader is used by default for public pages. URLs on localhost or private networks use a direct fetch because Jina cannot reach them.
Use direct fetch for any URL with `--no-jina`:
```bash theme={null}
plannotator annotate https://internal.example.com/guide --no-jina
```
Direct fetch converts the returned HTML with Turndown. URLs ending in `.md` or `.mdx` are read as text when the response is Markdown.
Plannotator annotates an imported copy of a web page, not the live page. For live-site annotation, use [App Notes in the Chrome Web Store](https://chromewebstore.google.com/detail/app-notes/lkknpieefdjpoancolcioblkpgnhpffl). The [latest GitHub release](https://github.com/plannotator/app-notes/releases/latest) provides separate Chrome and Firefox packages with checksums.
## Edit Markdown
The Markdown editor supports two outcomes:
* For a plan, agent message, URL conversion, or other non-writable source, Plannotator sends your changes to the agent as a unified diff.
* For an eligible local Markdown, MDX, or supported plain-text file, save with `Cmd/Ctrl+S` to replace the file atomically. Plannotator confines the write to the opened source file, checks whether it changed on disk, and asks you to resolve a conflict when needed.
Saved file changes are included with submitted feedback as context so the agent knows they are already applied. Unsaved edits are not written to disk.
Local HTML has its own rendered workflow. See [Annotate HTML](/open-source/workflows/html). To change the message returned by supported agent wrappers, see [Customize Feedback](/open-source/reference/custom-feedback#plan-and-document-feedback).
Last verified on July 31, 2026, using Plannotator product commit `7cd023c`. Maintained by the Plannotator project.
# Annotate a Folder with Plannotator
Source: https://docs.plannotator.ai/open-source/workflows/folders
Open a folder of supported documents, plain-text config and data files, and HTML in one Plannotator session.
Pass a folder to `plannotator annotate` to browse and annotate its supported documents in one session. This works well for a documentation folder or a local knowledge base containing plans, PRDs, specifications, ADRs, RFCs, and notes.
## Open the folder
```bash theme={null}
plannotator annotate docs/
```
Plannotator starts a temporary local server and opens the folder file browser. The files remain on your computer.
The browser lists these file types:
* Markdown: `.md` and `.mdx`
* Text: `.txt`
* Config and data: `.yaml`, `.yml`, `.json`, `.jsonc`, `.json5`, `.toml`, `.ini`, `.cfg`, `.conf`, `.properties`, `.csv`, `.tsv`, `.log`, `.xml`, and `.env.example`
* HTML: `.html` and `.htm`
A bare `.env` file and source-code extensions are excluded. Each file must be 2 MiB or smaller. Common generated and dependency directories, including `node_modules`, `dist`, and `build`, are skipped.
## Move between files
Choose a file in the browser, add annotations, then choose another file. You do not need to start a new Plannotator session for each document.
Press `Mod` + `Shift` + `B` to show or hide the folder browser. `Mod` means Command on macOS and Control on Windows and Linux.
Opening an eligible local text file from the folder browser records per-file annotation history. The history remains grouped by the file's stable path, unchanged content does not create a duplicate version, and later sessions can show a diff against a saved version.
Rendered HTML, converted URLs, agent messages, and ordinary documents opened through links inside another review do not receive folder-session history.
## Send the folder feedback
Select **Send Feedback** after you finish annotating. A direct terminal run prints the formatted feedback to standard output. A supported agent command or skill returns it to the active agent session.
Use `--gate` when the folder review also needs an **Approve** action:
```bash theme={null}
plannotator annotate docs/ --gate
```
## Open a large folder
The file browser returns up to 5,000 supported files by default. Set `PLANNOTATOR_FILE_BROWSER_MAX_FILES` to a positive integer when you need a different limit. See [Environment Variables](/open-source/reference/environment-variables#files-diagnostics-and-local-tools) for the setting.
See [Annotate documents](/open-source/workflows/documents) for local-file editing, web URLs, HTML rendering, and save behavior.
Last verified against Plannotator OSS v0.25.0 on July 27, 2026. Maintained by the Plannotator project.
# Review GitButler Workspaces, Stacks, and Branches
Source: https://docs.plannotator.ai/open-source/workflows/gitbutler
Review a GitButler workspace, stacked branches, or one branch layer in Plannotator, with exact detection rules, limits, and troubleshooting.
Run `plannotator review` inside an active GitButler workspace. Plannotator detects GitButler and opens the **Workspace** view, which shows all applied committed work, working-tree changes, and untracked files.
```bash theme={null}
cd path/to/gitbutler-workspace
plannotator review
```
![Plannotator GitButler Workspace view showing all applied committed and working-tree changes in the file tree and diff.]()
Plannotator reviews local GitButler state. It does not use GitButler's older cloud **Butler Review** feature, which [GitButler says is currently paused](https://docs.gitbutler.com/review/overview).
## Requirements and automatic detection
Use Plannotator v0.24.0 or newer. Put the GitButler `but` CLI on `PATH`. Version 0.21.0 or newer is required.
Run:
```bash theme={null}
plannotator --version
but --version
```
`plannotator --version` must report v0.24.0 or newer. `but --version` must report v0.21.0 or newer. GitButler documents the CLI in the [GitButler CLI overview](https://docs.gitbutler.com/cli-overview).
Plannotator selects GitButler only when both checks pass:
1. Symbolic `HEAD` is `refs/heads/gitbutler/workspace`. Plannotator also accepts the legacy `refs/heads/gitbutler/integration` ref.
2. The repository has a local `gitbutler.project.targetref` value that starts with `refs/`.
The reserved branch name alone is not enough. A stale GitButler database does not trigger detection by itself. Neither does a normal branch merely named `gitbutler/workspace` without the local target-ref configuration. GitButler explains why its client maintains the synthetic workspace commit in [Workspace Branch](https://docs.gitbutler.com/workspace-branch).
If Plannotator detects the workspace ref and target configuration but cannot use `but`, it stops with a clear error. It does not fall back to a plain Git diff of GitButler's synthetic workspace commit.
## Choose Workspace, Stack, or Branch
Open the comparison picker to move between the GitButler views available for the current workspace.
![Plannotator comparison picker listing Workspace, Stack, and Branch views for an active GitButler workspace.]()
| View | What Plannotator shows |
| - | - |
| **Workspace** | All applied committed work from GitButler's reported merge base, plus assigned and unassigned working-tree changes and untracked files. This is the default. |
| **Stack** | Committed work from the workspace merge base through the selected stack tip. It does not include assigned or unassigned working-tree changes. |
| **Branch** | The committed commits in one branch layer. The previous layer, or the workspace merge base for the bottom layer, forms the comparison base. |
GitButler defines stacked branches as dependent branches that build on the branches below them. See [Stacked Branches](https://docs.gitbutler.com/features/branch-management/stacked-branches) for GitButler's branch model.
Assigned but uncommitted changes appear only in **Workspace**. GitButler does not expose one authoritative combined patch for a stack plus those assigned changes, so Plannotator does not guess.
## Know the limits of GitButler sessions
GitButler assignments are not the Git index. Plannotator therefore hides stage and unstage controls, Git-status sections, and the commits panel in GitButler sessions.
Committed **Stack** and **Branch** views describe Git objects that may not match the live working tree. Other stacks or later layers can be applied at the same time. In these two views, Plannotator disables:
* Opening a file in an editor or another app
* Code navigation
* Semantic diff
* VS Code annotations
When you expand a file, Plannotator still reads it from the exact committed comparison, not from the live workspace.
When you start a multi-repository review from a parent folder, a GitButler child repository participates only in the aggregate **Current changes** view. Staged, unstaged, and last-change aggregate modes are unavailable when a GitButler child is present.
## Force GitButler or plain Git
Force the GitButler provider when automatic detection is unavailable or when you want a clear setup error:
```bash theme={null}
plannotator review --gitbutler
```
Force the plain Git provider when you intentionally want Git's view of the repository:
```bash theme={null}
plannotator review --git
```
Plain Git can expose the synthetic workspace commit and union index that GitButler maintains. Use the Git escape hatch only when that is the comparison you want.
## Keep annotations tied to the right comparison
Each annotation records the GitButler view, label, merge base, and exact diff snapshot that supplied its line numbers. If you annotate a branch, switch to another view, and then send feedback, Plannotator labels the annotation with the branch comparison where you made it.
![GitButler Branch view selector with an annotation badge on token.ts in the Plannotator file tree.]()
Ask AI and launched agent reviews receive the comparison currently open in Plannotator. For committed Stack and Branch views, the prompt includes the displayed patch and tells the agent to treat it as authoritative. Ordinary filesystem reads or `git diff` can include other applied stacks or later branch layers.
See [Run agent reviews](/open-source/workflows/agent-reviews#run-agents-on-the-intended-comparison) for provider permissions and review behavior.
## Troubleshoot GitButler review
### `but` is missing
Plannotator reports:
```text theme={null}
GitButler workspace detected, but the `but` CLI is not on PATH (requires 0.21.0 or newer).
```
Install GitButler's CLI, or expose the `but` command installed with GitButler Desktop, then confirm it is available in the same shell:
```bash theme={null}
but --version
```
### `but` is too old
For an installed v0.20.0 CLI, Plannotator reports:
```text theme={null}
GitButler 0.20.0 is unsupported; Plannotator requires 0.21.0 or newer.
```
Update GitButler until `but --version` reports v0.21.0 or newer. A prerelease such as `0.21.0-beta.1` does not satisfy the minimum.
### Automatic detection does not trigger
Check the two values Plannotator uses:
```bash theme={null}
git symbolic-ref --quiet HEAD
git config --local --get gitbutler.project.targetref
```
The first command should print the GitButler workspace ref. The second should print a configured ref such as `refs/remotes/origin/main`. If either is absent, return to an active GitButler workspace or use `plannotator review --gitbutler` to get the direct provider error.
### Assigned changes are absent from Stack or Branch
This is expected. Select **Workspace** to review assigned or unassigned working-tree changes and untracked files. Stack and Branch remain committed-only.
GitButler support shipped in [Plannotator OSS v0.24.0](https://github.com/backnotprop/plannotator/releases/tag/v0.24.0) through [PR #1067](https://github.com/backnotprop/plannotator/pull/1067). This page was verified against [v0.25.0](https://github.com/backnotprop/plannotator/releases/tag/v0.25.0) on July 27, 2026. Maintained by the Plannotator project.
# Annotate HTML in Plannotator
Source: https://docs.plannotator.ai/open-source/workflows/html
Render a local HTML file in Plannotator, annotate text or elements, compare versions, and share an encrypted portable copy.
Plannotator renders local `.html` and `.htm` files as pages by default. You can annotate visible text or point to an element without converting the page to Markdown.
For URL imports, folders, and the separate live-page workflow, see [How to annotate a website or HTML file](/learn/annotate-any-web-page-or-html-file).
## Open rendered HTML
Open only HTML that you trust. A script in the sandbox can make outbound network requests. Use `--markdown` to remove scripts before annotation.
```bash theme={null}
plannotator annotate report.html
```
The page runs in a sandboxed iframe. Plannotator allows the page's scripts to run inside that sandbox but does not grant it same-origin access to the annotation UI.
The sandbox does not block outbound network requests. A script can send its content or other readable data to a remote server.
Relative support files such as stylesheets, scripts, images, fonts, audio, and video are served from the HTML file's directory. Plannotator blocks path traversal and does not follow a symlink that escapes that directory.
## Add HTML annotations
Use either input method in the annotation UI:
* Select visible text, then add a comment, deletion, quick label, or looks-good mark.
* Switch to pinpoint mode and select a page element that is easier to identify by position than by text.
Use the document comment action for feedback about the whole page. **Send Feedback** returns the annotations to the active agent or prints them to stdout when you launched the CLI directly.
Optional Vim controls work in the raw rendered HTML view. Turn them on in Settings, then use the same navigation, visual-selection, and annotation keys as plan and document review. Press `?` for the key-reference panel.
## Convert HTML to Markdown
Use `--markdown` when you want to annotate the page as converted Markdown instead of rendered HTML:
```bash theme={null}
plannotator annotate report.html --markdown
```
Plannotator uses Turndown with GitHub Flavored Markdown table support. It removes `script`, `style`, and `noscript` elements during conversion. Edits to the converted Markdown describe the requested content change, but they do not overwrite the HTML source file.
Converted HTML uses the normal Markdown viewer and its Vim controls. Raw HTML uses the iframe-aware controls that navigate the rendered page.
## Compare HTML versions
When annotation history is enabled, reopening the same HTML file creates a new local version if the content changed. **Show changes** renders the current page with inline insertions and deletions for changed text. Script and style contents are not marked up by the HTML diff.
See [Version history](/open-source/workflows/version-history) to control these local copies.
## Share rendered HTML
Rendered HTML does not use the URL-only sharing format. In **Export** > **Share**, select **Create short link**. Plannotator prepares a portable copy, inlines eligible local support assets, encrypts the payload in your browser, and uploads only ciphertext to the configured paste service.
See [Share an annotation session](/open-source/workflows/sharing) for the encryption and retention details.
Last verified against Plannotator OSS v0.25.0 on July 27, 2026. Maintained by the Plannotator project.
# Review local code changes
Source: https://docs.plannotator.ai/open-source/workflows/local-changes
Open a browser review for local Git, GitButler, Jujutsu, or Perforce changes and send line-specific feedback to your coding agent.
Run a local review from your coding agent:
```text theme={null}
/plannotator-review
```
Or start the same review from a terminal:
```bash theme={null}
plannotator review
```
Plannotator detects the repository and opens the diff in your browser. When an agent starts the command, it captures your submitted annotations. When you start the command directly, Plannotator prints the result in the terminal. The available comparison modes depend on the source-control system.
## Git reviews start with everything since the base branch
In a Git repository, the default **All changes** view uses Plannotator's `since-base` comparison. Plannotator compares the merge base of your branch and its base branch with the current working tree.
This comparison approximates the change that a pull request would contain if you committed and pushed now. It includes:
* Commits on your branch
* Staged and unstaged changes
* Untracked files
Plannotator tries the repository's default branch first, then common `main` and `master` references. If it cannot resolve a base branch, it opens the uncommitted changes instead. This fallback avoids hiding committed work behind an invalid comparison.
Use the comparison picker to review only uncommitted, staged, or unstaged changes, the last commit, a specific commit, all files at `HEAD`, or committed branch changes. The base picker can compare against another local or remote reference.
The **Git status** panel groups committed changes, working-tree changes, and untracked files in the default All changes view. Staging controls and the commit-history rail are available only for ordinary local Git reviews.
### Large untracked files
Plannotator loads and diffs an untracked text file only when it is 5 MiB or smaller. A larger untracked file appears as a binary addition, and its full content is not available in the review. This limit prevents a single generated or data file from consuming the review session.
## Choose the source-control provider
Plannotator uses the nearest supported repository root. When a folder contains nested Git, GitButler, or Jujutsu repositories, it can show their workspace changes together with repository-prefixed paths.
| Provider | Default view | Important boundaries |
| - | - | - |
| Git | All changes (`since-base`) | Supports staging controls, Git status groups, commit history, base selection, and stale-diff checks. |
| GitButler | Workspace | Requires `but` 0.21.0 or newer. Stack and Branch views are committed-only. Git staging, commit history, and base-fetch controls are unavailable. |
| Jujutsu | Current | Uses Jujutsu revisions rather than the Git index. No stage or unstage controls. |
| Perforce | Default changelist | Shows opened text files from the default or a numbered pending changelist. Binary opened files are skipped. No staging controls or nested-repository aggregation. |
### Force Git or GitButler
Use a flag when you need to choose explicitly:
```bash theme={null}
plannotator review --gitbutler
plannotator review --git
```
Automatic detection opens **Workspace**, which includes all applied committed work, working-tree changes, and untracked files. `--gitbutler` fails clearly if `but` is missing or older than v0.21.0; it does not silently fall back to Git.
See [Review GitButler Workspaces, Stacks, and Branches](/open-source/workflows/gitbutler) for the exact detection rules, committed-only views, session limits, escape hatches, annotations, agent reviews, and troubleshooting.
### Review Jujutsu changes
Plannotator detects a Jujutsu workspace through the installed `jj` command. The comparison picker offers:
* **Current** for `@` compared with its parent
* **Last** for the previous change
* **Line** for the current line of work back to the selected target
* **Evolution** for the current change compared with an older evolution entry
* **All** for the repository root through `@`
Line mode can target local or remote bookmarks. Plannotator does not expose a separate `--jj` flag.
### Review Perforce changelists
Plannotator detects Perforce after Git by running `p4 info` and reading the current client root. The default view contains files opened in the default changelist. Use the comparison picker to open another pending numbered changelist owned by the current user and client.
Perforce support is available in Plannotator's main CLI-backed agent setups. The Pi extension's review server does not provide a Perforce provider.
## Annotate and return the review
Select changed lines to add comments, quick labels, deletion requests, or an approval mark. **Send Feedback** produces structured file and line references. **Approve** produces the configured code-review approval prompt. The agent that opened Plannotator captures that output; a direct terminal launch prints it.
See [Customize Feedback](/open-source/reference/custom-feedback#code-review-feedback) to change the approval message or the instructions appended after submitted findings.
For a GitHub pull request or GitLab merge request, use a URL instead. See [Review pull requests and merge requests](/open-source/workflows/pull-requests).
Last verified against Plannotator OSS v0.25.0 on July 27, 2026. Maintained by the Plannotator project.
# Review an AI Coding Plan with Plannotator
Source: https://docs.plannotator.ai/open-source/workflows/plan-review
Annotate an AI coding plan, send exact feedback to the agent, approve it, and compare the next revision.
Plannotator opens an agent's plan in a local review UI. Comment on exact text, mark text for removal, edit the Markdown, or add a general comment. Choose **Send Feedback** when the agent should revise the plan, or **Approve** when it can continue.
## Open a plan review
Supported agents can open Plannotator at their plan handoff point. The exact trigger depends on the agent. Claude Code intercepts `ExitPlanMode`, while other agents use their own hooks, plugins, or commands.
On Claude Code 2.1.287 or later (with the [Plannotator mod](/open-source/agents/claude-code#the-plannotator-mod)) and on [Pi](/open-source/agents/pi), the agent does not wait while you review. Your decision arrives later as a message, and a revised plan updates the same tab.
To review a plan file without an automatic hook, run:
```bash theme={null}
plannotator annotate plan.md --gate
```
The `--gate` flag adds **Approve** to the document annotation UI. See [Agents](/open-source/agents) for the setup and plan-review trigger used by each agent.
## Review and respond
1. Read the rendered plan.
2. Select text to add a comment, request deletion, apply a quick label, or mark the selection as looking good.
3. Use a global comment for feedback that does not belong to one passage.
4. Choose **Send Feedback** when the plan must change before implementation.
5. Choose **Approve with Notes** when the plan can proceed and the remaining feedback is non-blocking implementation guidance.
6. Choose **Approve** when the plan can proceed without notes.
Some agent protocols cannot attach notes to approval. Plannotator warns before an approval would discard unsent feedback. Use **Send Feedback** for blocking changes.
Plannotator exports anchored feedback as structured Markdown. It includes the selected text, the comment or requested deletion, and source line information when available. Direct Markdown edits are included as a unified diff.
## Review a revised plan
Plannotator saves each plan submission before opening the review. When the agent resubmits the same plan, a change badge shows added and removed lines.
Open the diff to switch between:
* a rendered view with added, removed, and modified blocks
* a raw Markdown diff with `+` and `-` lines
You can annotate changed blocks in the rendered diff. Use the Version Browser to compare the current plan with an earlier saved version.
See [Annotations and feedback](/open-source/workflows/annotations-and-feedback#choose-the-review-decision) for the exact behavior of Send Feedback, Approve, Close, and Cancel. See [Customize Feedback](/open-source/reference/custom-feedback#plan-and-document-feedback) to change the returned message and [Version history](/open-source/workflows/version-history) for local storage details.
Last verified on July 31, 2026, using Plannotator product commit `7cd023c`. Maintained by the Plannotator project.
# Review pull requests and merge requests
Source: https://docs.plannotator.ai/open-source/workflows/pull-requests
Review GitHub pull requests or GitLab merge requests locally, then send feedback to your agent or post it to the provider.
Pass a GitHub pull request or GitLab merge request URL to Plannotator:
```text theme={null}
/plannotator-review https://github.com/owner/repository/pull/123
```
```text theme={null}
/plannotator-review https://gitlab.com/group/project/-/merge_requests/42
```
From a terminal, use `plannotator review` followed by the same URL. GitHub Enterprise hosts and GitLab instances on custom domains are supported when their URLs follow the provider's standard pull-request or merge-request path.
## Install and authenticate the provider CLI
Plannotator uses the provider's command-line tool for authentication, metadata, and diff retrieval.
| Provider | Requirement | Authentication check |
| - | - | - |
| GitHub | Install `gh` | Run `gh auth login`, then confirm with `gh auth status`. For GitHub Enterprise, add `--hostname github.example.com`. |
| GitLab | Install `glab` | Run `glab auth login`, then confirm with `glab auth status`. For a custom domain, add `--hostname gitlab.example.com`. |
The authenticated account must be able to read the repository. Private repositories work when the corresponding CLI account has access.
## Local checkout is the default
Plannotator first loads the provider diff so the browser can open promptly. In the background, it prepares a temporary local checkout for the pull request or merge request.
If the current repository matches the URL's host, owner, and repository, Plannotator fetches the review head into a detached Git worktree. For another repository, it creates a shallow temporary clone with the provider CLI. The temporary checkout is removed when the review session ends.
The checkout enables features that need repository files:
* Ask AI
* Background agent reviews, Code Tours, and Guided Reviews
* Code navigation and semantic diff
* Full-stack comparison for a stacked pull request or merge request
If checkout preparation is still running, these features can become available after the diff opens. If it fails, Plannotator keeps the provider diff available and reports that local-file features are unavailable.
Use `--no-local` when you intentionally want a diff-only review:
```bash theme={null}
plannotator review --no-local https://github.com/owner/repository/pull/123
```
`--no-local` skips the temporary checkout. You can still inspect and annotate the provider diff, but file-aware AI, agent reviews, code navigation, semantic diff, and full-stack comparison are unavailable. `--local` states the default behavior explicitly.
## Choose where the review goes
The review destination appears in the browser. Choose one of these destinations before submitting:
* **Agent** produces structured feedback for the coding-agent session that opened Plannotator. A direct terminal launch prints the same result. It does not post to GitHub or GitLab.
* **GitHub** or **GitLab** posts review comments or approval through the authenticated provider CLI. Plannotator reports the completed submission to the invoking agent or terminal.
A new provider review defaults to GitHub or GitLab unless you previously selected Agent. Plannotator remembers the destination for later review sessions. You can switch it in the review controls; pressing Option or Alt twice also toggles the destination.
Provider posting applies only to the current pull request or merge request layer. Inline comments must map to lines in that provider diff.
If a stacked change offers **Full stack**, use it to inspect or run agents over the whole chain. Before you post inline comments, return to **Layer**. An annotation that cannot map to the provider diff can still be copied or sent to the agent as Markdown.
## GitHub and GitLab differences
Both providers support URL review, local checkout, annotations, review submission, and approval. Their platform APIs differ:
* GitHub can synchronize each file's viewed state with the pull request. GitLab viewed state stays local to Plannotator.
* GitHub supports listing and switching pull requests from the review UI. GitLab does not currently provide the equivalent in-session merge-request switcher.
* GitHub can show a pull-request stack tree. GitLab can identify a stacked merge request and offer Layer or Full stack when a local checkout is available, but it does not show the GitHub-style stack tree.
* GitLab posts a general note, inline discussions, and approval through separate APIs. If only part of a submission succeeds, Plannotator reports what posted and narrows **Retry Unposted** to the failed comments or approval. It does not resend the general note or inline comments that already posted.
* If Plannotator cannot confirm whether a provider accepted part of a review, it blocks automatic retry to avoid duplicates. Inspect the pull request or merge request before starting another submission. GitLab can also save unposted comment bodies under the Plannotator data directory as a recovery copy.
For help understanding unfamiliar code before you annotate it, see [Ask AI during a review](/open-source/workflows/ask-ai). To run a separate review agent over the change, see [Run agent reviews](/open-source/workflows/agent-reviews). To change the message returned to your agent, see [Customize Feedback](/open-source/reference/custom-feedback#code-review-feedback).
Last verified on July 31, 2026, using Plannotator product commit `7cd023c`. Maintained by the Plannotator project.
# Answer Your Agent's Questions Asynchronously
Source: https://docs.plannotator.ai/open-source/workflows/questions
Answer your agent's questions asynchronously in Plannotator: question cards you fill in on your own time, a quality interface for terminal and desktop agents alike.
Your agent has questions for you. Instead of asking them one at a time in a chat prompt, it writes them into its plan or document, and Plannotator shows each one as a card. You answer them all in one place, on your own time, and send them back together.
A modern model has no reason to sit blocked on a prompt. Terminal agents and desktop agent apps both lack a good interface for answering questions. Plannotator works with both.
The post [An interactive UI for the grill-me skill](https://plannotator.ai/blog/an-interactive-ui-for-the-grill-me-skill), written before question blocks existed, shows the same idea through `/plannotator-last` (a tool for annotating your agent's last message, useful for CLI agents).
## How to use
**With the skill.** The Plannotator installer adds a `plannotator` skill for Claude Code, Codex, and other agents that read `~/.agents/skills`. It teaches the agent the question syntax. Nothing to set up. Ask your agent to use it:
```text theme={null}
Use the plannotator skill. Write your questions for me as question blocks in a Markdown file, then open it with plannotator annotate.
```
**Without the skill.** Copy this prompt into your agent's `AGENTS.md`, `CLAUDE.md`, or a skill of your own:
````markdown expandable theme={null}
## Asking the reviewer questions
When a decision needs the reviewer (a trade-off you cannot settle from the code or the conversation), write it as a question block. The reviewer answers in place, and the answers come back to you in an "Answers to your questions" section at the top of their feedback, with the questions they left open listed under "Unanswered".
```markdown
:::question
Where should losing conflict versions be kept?
Last-write-wins silently drops the loser unless we keep it somewhere.
- [ ] Local only, purged after 30 days — cheap, no server change
- [ ] Server-side per user — survives reinstall, needs a retention policy
- [ ] Nowhere — accept silent loss for v1
Recommended: Local only, purged after 30 days
:::
```
- `:::question` picks one choice, `:::question-multi` picks any number, `:::question-text` asks for free text (a block with no choices is free text too).
- The first line is the question. Other prose lines are context. Most reviewers answer faster with a sentence or two of it: what the choice affects and what you already know. Context can include an image (``), which helps when the question is about something visual, such as a screen.
- Choices are task-list items: `- [ ] label`, optionally `- [ ] label — why`. The reviewer can always answer "Other", add a note, or skip.
- `Recommended:
Evidence topology
One index, six source records
Approved request
Intent and constraints
Exact revision
SHA, diff, change map
Validation
Checks and runtime proof
Review artifacts
UI, video, traces
Handoff index
Points to evidence
Risks and questions
What remains unresolved
Documentation
Maintained truth changed
> **Revision:** PR #219 at `71be993`.
> **Changed:** Corrected the cursor offset in `pagination.ts`; added the boundary case in `pagination.test.ts`.
> **Validated:** Targeted test file, 18 passed; type-check passed.
> **Open questions / risks:** None identified.
> **Documentation:** None; the public behavior now matches the existing API documentation. These six lines identify the request, code, and validation claim. A formal planning package or long session transcript would not help the reviewer decide whether to merge this fix. ## Use the full handoff for a cross-cutting change Now suppose a team replaces a synchronous customer-data export endpoint with a queued export service. The implementation touches the public API, a jobs table, a background worker, encrypted object storage, download authorization, the account UI, audit events, retention cleanup, and operator documentation. A useful handoff might say: * **Request:** Export-service plan version 6, approved by product, data, and security. The agent deviated from emailing export files after the security review required a short-lived authenticated download. * **Revision:** Pull request head `c4a912e` in the API repository plus `7b21d0a` in the web repository. * **Change map:** Read the export state machine first, then the jobs migration, worker, object-storage adapter, download authorization, account UI, and retention cleanup. * **Validation:** Unit and integration suites passed; the migration was rehearsed against a sanitized production-shape snapshot; expired and cross-organization download links were rejected; the browser flow passed with screenshots attached. Queue-saturation testing was not run because the staging capacity was unavailable. * **Open questions and risks:** Download links expire after 24 hours. Rollback disables new export requests but allows already queued jobs to finish. Security review and an alert on failed retention cleanup remain required before launch. * **Documentation:** Updated `PRODUCT.md` with the customer-visible lifecycle, `TECH.md` with the storage and authorization boundaries, and the operator runbook with rollout, rollback, queue recovery, and retention steps. Several teams must verify different claims and operate the export service, so the handoff needs more evidence. It remains a map, not an agent transcript. The project's issue, plan, or review system records what was authorized; the handoff records what the agent produced and any deviations. Plannotator's [local plan review loop](/learn/code-context/approve-ai-coding-plan-before-execution) can help refine the plan before that external record is made. After merge, durable decisions should enter [living codebase documentation](/learn/code-context/living-documentation-for-ai-agents). For the complete path from request through team decision, implementation evidence, and shipping, read [How Teams Understand AI-Generated Code Before Shipping It](/learn/code-context/understand-ai-generated-code-before-shipping). ## What a handoff cannot establish * It is authored by the same agent that may have misunderstood the request or missed a failure. Treat its claims as review leads, not independent verification. * Passing tests demonstrate only the paths and assertions they cover. They do not prove the change satisfies the product decision. * A commit SHA identifies code, not every external dependency, service response, or mutable artifact used during validation. * Logs and artifacts can expose secrets or customer data. Redact and retain them according to the repository's access rules. * A large handoff cannot rescue a pull request that is too broad to review. Split the implementation when reviewers cannot form a reliable mental model. Anthropic's long-running agent harnesses used structured updates alongside Git history so the next session could resume the work. A team handoff uses the same practice to prepare an implementation for review. See [Anthropic's long-running agent harness research](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents). ## Frequently asked questions ### What should an AI coding agent include in a pull request? Include the authorizing request, exact head revision, a change map, validation commands and results, unresolved questions and risks, and documentation impact. Add screenshots, HTML, migration evidence, rollout instructions, or security notes only when the change requires them. ### How detailed should an AI coding agent handoff be? Use the smallest handoff that lets another engineer verify the work without reconstructing the agent session. A local fix may need six short lines; a cross-service migration needs more evidence. ### Should the agent include every command and log? No. Include decision-relevant commands and results, note anything skipped or failing, and link to complete logs when useful. Large pasted logs hide signal and can leak sensitive data. ### How can a reviewer verify an agent's handoff? Confirm the request and revision, inspect the diff in the suggested order, open the linked evidence, check that CI belongs to the current commit, and rerun consequential validation when appropriate. Resolve discrepancies against the code and executable behavior, not the agent's prose. ### Who owns the accuracy of an AI coding agent handoff? The person or team delegating the change owns the handoff presented for review. The agent can draft and update it, but it should not certify its own work as correct or ready to merge. ## Check the handoff A reviewer should be able to identify the exact request and revision, inspect the supporting evidence, see what remains uncertain, and find any documentation impact without reopening the private agent session.
Documentation roles
Two records, two questions
Current documentation
What is true now?
- PRODUCT.md
- TECH.md
- API contract
- Handbook and runbooks
Decision history
How did we get here?
- RFC and approved plan
- Review thread
- Progress log
- Superseded decisions
Link current truth to its rationale without forcing agents to reconstruct the present from old discussions.
Iterative planning loop
Turn a request into verified work
-
01 · Request
State the outcome and boundaries.
-
02 · Explore
Inspect code, history, tests, and decisions.
-
03 · Ask
Surface unknowns and interview the human.
-
04 · Prototype
Make options visible and cheap to change.
-
05 · Refine
Write the current plan and finish line.
-
06 · Prove
Test the riskiest assumption on a small slice.
-
07 · Record
Log discoveries and deviations while building.
-
08 · Revise
Update the plan when evidence changes it.
-
09 · Verify
Use tests, domain evidence, and a fresh reviewer to check the result.
Planning continues during implementation. New evidence can send the work back to exploration, a prototype, or a revised plan.
**Default:** Detect SSH from `SSH_TTY` or `SSH_CONNECTION`. | | `PLANNOTATOR_URL_HOST` | **Values:** A hostname, IPv4 address, bracketed IPv6 address, or `auto`.
**Effect:** Changes the advertised remote URL without changing the server bind address.
**Auto:** Uses the Tailscale MagicDNS name, then exactly one Tailscale IPv4 address.
**Precedence:** The environment value overrides `urlHost` in `config.json`. | | `PLANNOTATOR_PORT` | **Values:** A fixed port such as `19432`, or a range such as `19432-19463`.
**Default:** A random available port locally and `19432` remotely. | | `PLANNOTATOR_BROWSER` | **Value:** A browser app name or path on macOS, or an executable on Linux and Windows.
**Precedence:** The CLI `--browser` flag wins. | | `BROWSER` | **Effect:** Supplies the fallback browser command when `PLANNOTATOR_BROWSER` is unset.
**No browser:** `none`, `false`, `0`, and `:` do not launch one. | | `PLANNOTATOR_GLIMPSE` | **Values:** `1` or `true` enables the Glimpse window when available. Other values disable it.
**Default:** Enabled. | | `PLANNOTATOR_GLIMPSE_WIDTH` | **Effect:** Sets the initial Glimpse window width.
**Default:** `1280`. | | `PLANNOTATOR_GLIMPSE_HEIGHT` | **Effect:** Sets the initial Glimpse window height.
**Default:** `900`. | Remote mode binds the unauthenticated local server to `0.0.0.0`. Forward it through SSH or your development environment and do not expose that port to an untrusted network. See [Troubleshooting](/open-source/troubleshooting#remote-ssh-and-development-containers). Use [Tailscale remote reviews](/open-source/tailscale) for tailnet-only HTTPS access that keeps the server on `127.0.0.1`. See [Remote access](/open-source/remote-access) for trusted private networks, SSH, development containers, and opening a session from another device. ## Annotation, history, and sharing | Variable | Accepted value and behavior | | - | - | | `PLANNOTATOR_JINA` | **Values:** `1` or `true` uses Jina Reader. Other values use direct fetch and local conversion.
**Precedence:** The `--no-jina` flag wins. | | `JINA_API_KEY` | Optional bearer token sent to Jina Reader. | | `PLANNOTATOR_ANNOTATE_HISTORY` | **Values:** `1` or `true` saves per-file annotation history. Other values disable it.
**Default:** Enabled. | | `PLANNOTATOR_GUIDE_HISTORY` | **Values:** `1` or `true` saves successful Guided Reviews. Other values disable new writes.
**Default:** Enabled.
**Existing data:** Saved guides remain readable. | | `PLANNOTATOR_SHARE` | **Values:** `disabled` hides sharing. Any other value enables it.
**Precedence:** Overrides `share` in `config.json` for integrations that use Plannotator's shared configuration resolver. An explicit OpenCode `share` setting takes precedence over this variable. | | `PLANNOTATOR_SHARE_URL` | **Effect:** Sets the share portal base URL.
**Default:** `https://share.plannotator.ai`. | | `PLANNOTATOR_PASTE_URL` | Paste API used for encrypted short links and raw HTML sharing. | The portal and paste-service deployment variables are documented in [Self-host Plannotator's deprecated share services](/open-source/self-hosting#deployment-variables). ## Files, diagnostics, and local tools | Variable | Accepted value and behavior | | - | - | | `PLANNOTATOR_DATA_DIR` | **Effect:** Selects the data directory for configuration, plans, history, sessions, and installed runtime state.
**Path:** Expands a leading `~`. Resolves a relative value from the launch working directory.
**Default:** An existing `~/.plannotator`, then an absolute `$XDG_DATA_HOME/plannotator`, then `~/.plannotator`. | | `PLANNOTATOR_FILE_BROWSER_MAX_FILES` | **Value:** A positive integer.
**Effect:** Limits files returned by the file browser.
**Default:** `5000`. | | `PLANNOTATOR_SEM_PATH` | Explicit path to the optional `sem` semantic-diff binary. | | `PLANNOTATOR_GIT_TIMEOUT_MS` | **Value:** A timeout in milliseconds.
**Use:** Set it only when you diagnose an unusually slow repository. | | `PLANNOTATOR_DEBUG` | Any non-empty value enables additional diagnostic output. | | `PLANNOTATOR_AGENT_TERMINAL_REMOTE` | **Values:** `1`, `true`, or `yes` enables the embedded agent terminal in remote mode or a `--tailscale` session.
**Default:** Disabled for both session types.
**Risk:** The terminal can run commands on the remote machine. | | `PLANNOTATOR_AI` | **Value:** `disabled` removes Ask AI, Review Agents, and Guided Review. It also disables their provider and job endpoints.
**Other features:** Ordinary reviews remain available. | | `PLANNOTATOR_CURSOR_SANDBOX` | **Values:** `0`, `false`, or `disabled` omits Cursor's `--sandbox enabled` flag.
**Default:** Enabled.
**Risk:** Without the flag, write protection depends on Ask mode and Cursor configuration. | Relative `XDG_DATA_HOME` values are ignored. Plannotator does not apply the XDG specification's implicit `~/.local/share` default. ## Agent setup Most users should let the installer set these values for supported agents. | Variable | Accepted value and behavior | | - | - | | `PLANNOTATOR_ORIGIN` | **Values:** `claude-code`, `amp`, `droid`, `opencode`, `codex`, `copilot-cli`, `gemini-cli`, `kiro-cli`, or `pi`.
**Effect:** Forces the calling agent.
**Invalid value:** Falls back to detection. | | `PLANNOTATOR_CWD` | Original project directory supplied by an integration wrapper. | | `PLANNOTATOR_BIN` | **Effect:** Sets the Plannotator executable for integrations that launch the CLI.
**Default:** `plannotator` from `PATH`. | | `PLANNOTATOR_PLAN_TIMEOUT_SECONDS` | **Effect:** Sets the maximum wait for OpenCode `submit_plan`.
**Default:** `345600`.
**No timeout:** Set `0`. | | `PLANNOTATOR_ALLOW_SUBAGENTS` | **Value:** `1` lets OpenCode subagents use `submit_plan`.
**Default:** Off. | ## Claude Code These apply to the [Plannotator mod](/open-source/agents/claude-code#the-plannotator-mod) on Claude Code 2.1.287 or later. Set them in the shell that starts Claude Code or in the `env` block of Claude Code's `settings.json`. Claude Code reads them when it starts, so restart it after a change. | Variable | Accepted value and behavior | | - | - | | `PLANNOTATOR_CLAUDE_MOD` | **Off:** `0`, `false`, `off`, or `disabled` turns the mod off. Claude then waits for your decision, and Ask AI uses a provider you pick.
**On:** `1`, `true`, or `on`. An empty or other value counts as unset.
**Default:** On.
**Precedence:** Overrides `claudeCodeMod` in `config.json`.
**Always off:** In `claude -p` and SDK runs, and on Windows. | | `PLANNOTATOR_MOD_DEBUG` | **Value:** `1` makes the mod write a debug log to `~/.plannotator/claude-code-mod/debug.log`, or under `PLANNOTATOR_DATA_DIR` when set.
**Default:** Off.
**Use:** Attach the log when you report a problem with the mod. | Other `PLANNOTATOR_*` values in the source tree coordinate child processes, tests, or packaged integrations. They are not stable user configuration. ## Installer controls | Variable | Accepted value and behavior | | - | - | | `PLANNOTATOR_MINIMAL` | **Values:** `1`, `true`, or `yes` installs only the CLI binary.
**Omitted components:** Hooks, skills, and sidecar tools. | | `PLANNOTATOR_VERIFY_ATTESTATION` | **Enable:** `1`, `true`, or `yes` requires build-provenance verification.
**Disable:** `0`, `false`, or `no`. | | `PLANNOTATOR_SKIP_SEM_INSTALL` | **Values:** `1`, `true`, or `yes` skips the semantic-diff sidecar. | | `PLANNOTATOR_SKIP_AGENT_TERMINAL_INSTALL` | **Values:** `1`, `true`, or `yes` skips the agent-terminal runtime. | | `PLANNOTATOR_PROMPT_TIMEOUT` | **Effect:** Sets the wait for an interactive integration choice in seconds.
**Default:** `30`.
**No timeout:** Set `0`. | The installer reads `PLANNOTATOR_DATA_DIR` and `PLANNOTATOR_VERIFY_ATTESTATION` too. See [Privacy and data flow](/open-source/reference/privacy-and-data-flow) for the network and storage consequences of these settings. Last verified on July 31, 2026, using Plannotator product commit `7cd023c`. Maintained by the Plannotator project. # Add external annotations to Plannotator Source: https://docs.plannotator.ai/open-source/reference/external-annotations Tested HTTP schemas for adding tool findings to a live Plannotator plan, document, or code review session. External annotations let a local tool add findings to an open Plannotator session. The user sees them immediately and they are included when Plannotator exports feedback.