plannotator command opens a local review session in your browser. Run plannotator <command> --help for the help text shipped with your installed version.
Review code changes
--git or --gitbutler to override detection. GitButler support requires but 0.21.0 or later; see the GitButler workflow guide 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.
Annotate a file, URL, or folder
--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.
--require-approval and --result-file <path> are strict automation options. They work only with direct annotate --gate --json calls and cannot be combined with --hook.
--require-approvalexits0only for approval. Annotations or dismissal exit1.--result-file <path>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.
{"decision":"approved"}, {"decision":"approved","feedback":"<notes>"}, {"decision":"annotated","feedback":"<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
--stdin to supply the text yourself:
last is an alias for annotate-last.
Reopen a running session
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
<data-directory>/plans/. The default is ~/.plannotator/plans/; see Configuration for data-directory resolution.
Goal setup commands
/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 <name>selects a browser, application, or executable for this run. It can appear with any command.--versionand-vprint the installed version.plannotator improve-contextis called by an installed agent hook. It reads a hook event from standard input and is not intended for direct use.
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.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 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 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.