mirror of https://github.com/backnotprop/plannotator.git synced 2026-09-14 14:17:26 +08:00

Files

T

Michael Ramos 9b14b19a7b chore: fold in pre-release QA findings (print overlays, doc alignment) (#1245 )

* chore: fold in pre-release QA findings (print overlays, doc alignment)

From the 25-item QA sweep over the v0.26.4..main range (all items passed;
these were the three real minors worth folding into the release):

- The raw-HTML iframe's injected CSS had no print rules, so pin badges
  (and, in a narrow window, the pinpoint outline box) printed into
  hard copies of annotated HTML pages. The overlay elements now carry an
  explicit @media print hide inside the iframe document, where the outer
  print.css cannot reach. Inline annotation marks stay printable on
  purpose, matching markdown documents.
- AGENTS.md/CLAUDE.md now state that PLANNOTATOR_ANNOTATE_HISTORY also
  gates the durable submitted-feedback records from #1237, and the
  Annotation interface listing includes the htmlAnchor field from #1243.
- apps/codex/README.md aligns with the #1241 top-level wording (Windows
  Codex hooks are experimental with printed manual steps, not disabled).
- Marketing docs: annotate page documents the pinpoint-first default and
  minimal-first chrome for raw-HTML sessions; installation page notes
  the old-git plain-clone fallback from #1239.

* chore: drop deprecated marketing-docs edits (canonical docs are Mintlify)

2026-08-09 17:19:50 -07:00

4.5 KiB

Raw Permalink Blame History

Plannotator for Codex

Code review, markdown annotation, and plan review are supported in Codex.

Plan review uses Codex's experimental Stop hook. This is a post-render review flow: when a turn stops, Plannotator reads the current rollout transcript, extracts the latest plan, and opens the normal plan review UI. If you deny the plan, Plannotator returns continuation feedback so Codex revises the plan in the same turn.

Install

macOS / Linux / WSL:

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

The installer adds the plannotator binary and, when Codex is installed or the Codex home already exists, enables Codex Stop hooks automatically. The Codex home is $CODEX_HOME when set, falling back to ~/.codex — both the installer and the plannotator binary (e.g. plannotator last reading Codex sessions) respect it (docs).

Windows PowerShell:

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

Codex hooks on native Windows are experimental. The Windows installer does not enable them automatically; it prints the manual setup steps ([features] hooks = true plus the Stop hook) for users who want to try them.

Enable Codex hooks

The installer handles this automatically on macOS, Linux, and WSL. If you are setting it up manually, Codex hooks require a feature flag.

Add this to ~/.codex/config.toml or <repo>/.codex/config.toml:

[features]
hooks = true

Then create ~/.codex/hooks.json or <repo>/.codex/hooks.json:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "plannotator",
            "timeout": 345600
          }
        ]
      }
    ]
  }
}

Notes:

Codex loads hooks.json next to active config layers, so either the global ~/.codex or repo-local .codex location works.
Prefer an absolute plannotator command path in hooks.json for Codex Desktop, because app-launched processes may not inherit your shell PATH.
This currently depends on Codex hooks, which are experimental and disabled on Windows in the current official docs.
Because this uses Stop, the review happens after Codex renders the plan turn, not at a dedicated ExitPlanMode interception point.
Restart Codex Desktop after installing or changing hooks.

Usage

Plan Review

Once hooks are enabled, plan review opens automatically whenever a Codex turn ends with a plan. Approving keeps the turn completed. Sending feedback returns a Stop continuation reason so Codex revises the plan and Plannotator shows version history and diffs across revisions.

Local End-to-End Harness

From the repo root, you can run a disposable local E2E flow against a real Codex session:

./tests/manual/local/test-codex-plan-review-e2e.sh --keep

This uses a temporary HOME, sample git repo, repo-local Codex CLI, and repo-local plannotator wrapper so it doesn't modify your installed Codex or Plannotator state. If you want to automate the opened review UI with Playwright, set PLANNOTATOR_BROWSER=/usr/bin/true before running the script.

Code Review

Run !plannotator review to open the code review UI for your current changes:

!plannotator review

This captures your git diff, opens a browser with the review UI, and waits for your feedback. When you submit annotations, the feedback is printed to stdout.

Annotate Markdown

Run !plannotator annotate to annotate any markdown file:

!plannotator annotate path/to/file.md

Annotate Last Message

Run !plannotator last to annotate the agent's most recent response:

!plannotator last

The message opens in the annotation UI where you can highlight text, add comments, and send structured feedback back to the agent.

Environment Variables

Variable	Description
`PLANNOTATOR_REMOTE`	Set to `1` / `true` for remote mode, `0` / `false` for local mode, or leave unset for SSH auto-detection. Uses a fixed port in remote mode; browser-opening behavior depends on the environment.
`PLANNOTATOR_PORT`	Fixed port to use. Default: random locally, `19432` for remote sessions.
`PLANNOTATOR_BROWSER`	Custom browser to open. macOS: app name or path. Linux/Windows: executable path.

4.5 KiB Raw Permalink Blame History