From 8b5306fce912fd99289ae8109de02e7491fb8671 Mon Sep 17 00:00:00 2001 From: Michael Ramos Date: Mon, 9 Mar 2026 20:41:40 -0700 Subject: [PATCH 1/7] docs: add Codex support documentation Co-Authored-By: Claude Opus 4.6 --- README.md | 32 +++++++++++- apps/codex/README.md | 51 +++++++++++++++++++ .../docs/getting-started/installation.md | 9 +++- 3 files changed, 90 insertions(+), 2 deletions(-) create mode 100644 apps/codex/README.md diff --git a/README.md b/README.md index 60669174..d65c00d5 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ # Plannotator -Interactive Plan Review for AI Coding Agents. Mark up and refine your plans using a visual UI, share for team collaboration, and seamlessly integrate with **Claude Code**, **OpenCode**, and **Pi**. +Interactive Plan Review for AI Coding Agents. Mark up and refine your plans using a visual UI, share for team collaboration, and seamlessly integrate with **Claude Code**, **OpenCode**, **Pi**, and **Codex**. @@ -55,6 +55,7 @@ Plannotator lets you privately share plans, annotations, and feedback with colle - [Claude Code](#install-for-claude-code) - [OpenCode](#install-for-opencode) - [Pi](#install-for-pi) +- [Codex](#install-for-codex) ## Install for Claude Code @@ -122,6 +123,35 @@ See [apps/pi-extension/README.md](apps/pi-extension/README.md) for full usage de --- +## Install for Codex + +**Install the `plannotator` command:** + +**macOS / Linux / WSL:** + +```bash +curl -fsSL https://plannotator.ai/install.sh | bash +``` + +**Windows PowerShell:** + +```powershell +irm https://plannotator.ai/install.ps1 | iex +``` + +**Then in Codex, run directly:** + +```bash +plannotator review # Code review for current changes +plannotator annotate file.md # Annotate a markdown file +``` + +No plugin or skill configuration needed — Codex runs `plannotator` as a normal shell command. + +See [apps/codex/README.md](apps/codex/README.md) for details. + +--- + ## How It Works When your AI agent finishes planning, Plannotator: diff --git a/apps/codex/README.md b/apps/codex/README.md new file mode 100644 index 00000000..77452a64 --- /dev/null +++ b/apps/codex/README.md @@ -0,0 +1,51 @@ +# Plannotator for Codex + +Plannotator works in Codex via the CLI binary — no plugin or skill required. Codex runs `plannotator` as a normal shell command. + +## Install + +**macOS / Linux / WSL:** + +```bash +curl -fsSL https://plannotator.ai/install.sh | bash +``` + +**Windows PowerShell:** + +```powershell +irm https://plannotator.ai/install.ps1 | iex +``` + +## Usage + +### Code Review + +Run `plannotator review` to open the code review UI for your current changes: + +```bash +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: + +```bash +plannotator annotate path/to/file.md +``` + +## Environment Variables + +| Variable | Description | +|----------|-------------| +| `PLANNOTATOR_REMOTE` | Set to `1` for remote mode (devcontainer, SSH). Uses fixed port and skips browser open. | +| `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. | + +## Links + +- [Website](https://plannotator.ai) +- [GitHub](https://github.com/backnotprop/plannotator) +- [Docs](https://plannotator.ai/docs/getting-started/installation/) diff --git a/apps/marketing/src/content/docs/getting-started/installation.md b/apps/marketing/src/content/docs/getting-started/installation.md index 080f75e5..4b4baad5 100644 --- a/apps/marketing/src/content/docs/getting-started/installation.md +++ b/apps/marketing/src/content/docs/getting-started/installation.md @@ -101,4 +101,11 @@ Coming soon. ## Codex -Coming soon. +No plugin or skill required — Codex runs `plannotator` as a normal shell command. + +Install the binary, then use it directly: + +```bash +plannotator review # Code review for current changes +plannotator annotate file.md # Annotate a markdown file +``` From a4b98979ed3bc0f6e06a205a846f85e52d616101 Mon Sep 17 00:00:00 2001 From: Michael Ramos Date: Mon, 9 Mar 2026 20:44:58 -0700 Subject: [PATCH 2/7] docs(codex): note plan mode not yet supported Co-Authored-By: Claude Opus 4.6 --- apps/codex/README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/apps/codex/README.md b/apps/codex/README.md index 77452a64..c8da580d 100644 --- a/apps/codex/README.md +++ b/apps/codex/README.md @@ -36,6 +36,10 @@ Run `plannotator annotate` to annotate any markdown file: plannotator annotate path/to/file.md ``` +## Plan Mode + +Plan review is not yet supported in Codex. Plannotator's plan review UI requires hooks to intercept the agent's plan submission, and Codex does not currently expose a hook system. We're tracking this for future integration. + ## Environment Variables | Variable | Description | From e630e598976d18198201599203ee5fdc349e23fe Mon Sep 17 00:00:00 2001 From: Michael Ramos Date: Mon, 9 Mar 2026 20:47:10 -0700 Subject: [PATCH 3/7] docs(codex): move plan mode notice to top Co-Authored-By: Claude Opus 4.6 --- apps/codex/README.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/apps/codex/README.md b/apps/codex/README.md index c8da580d..cd767348 100644 --- a/apps/codex/README.md +++ b/apps/codex/README.md @@ -1,5 +1,7 @@ # Plannotator for Codex +> **Plan mode is not yet supported.** Plannotator's plan review UI requires hooks to intercept the agent's plan submission, and Codex does not currently expose a hook system. Code review and markdown annotation work today. + Plannotator works in Codex via the CLI binary — no plugin or skill required. Codex runs `plannotator` as a normal shell command. ## Install @@ -36,10 +38,6 @@ Run `plannotator annotate` to annotate any markdown file: plannotator annotate path/to/file.md ``` -## Plan Mode - -Plan review is not yet supported in Codex. Plannotator's plan review UI requires hooks to intercept the agent's plan submission, and Codex does not currently expose a hook system. We're tracking this for future integration. - ## Environment Variables | Variable | Description | From 53c64099b9e4aae82b8ff513fc68d15b9a9e1e8c Mon Sep 17 00:00:00 2001 From: Michael Ramos Date: Mon, 9 Mar 2026 20:47:32 -0700 Subject: [PATCH 4/7] docs: note plan mode not yet supported in Codex sections Co-Authored-By: Claude Opus 4.6 --- README.md | 2 +- apps/marketing/src/content/docs/getting-started/installation.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index d65c00d5..fcefbf6c 100644 --- a/README.md +++ b/README.md @@ -146,7 +146,7 @@ plannotator review # Code review for current changes plannotator annotate file.md # Annotate a markdown file ``` -No plugin or skill configuration needed — Codex runs `plannotator` as a normal shell command. +No plugin or skill configuration needed — Codex runs `plannotator` as a normal shell command. Plan mode is not yet supported. See [apps/codex/README.md](apps/codex/README.md) for details. diff --git a/apps/marketing/src/content/docs/getting-started/installation.md b/apps/marketing/src/content/docs/getting-started/installation.md index 4b4baad5..fbe6f981 100644 --- a/apps/marketing/src/content/docs/getting-started/installation.md +++ b/apps/marketing/src/content/docs/getting-started/installation.md @@ -101,7 +101,7 @@ Coming soon. ## Codex -No plugin or skill required — Codex runs `plannotator` as a normal shell command. +No plugin or skill required — Codex runs `plannotator` as a normal shell command. Plan mode is not yet supported. Install the binary, then use it directly: From 71372a15e8653669fe187d32e4fa96a28bd550f6 Mon Sep 17 00:00:00 2001 From: Michael Ramos Date: Mon, 9 Mar 2026 20:47:48 -0700 Subject: [PATCH 5/7] docs: remove redundant Codex description line Co-Authored-By: Claude Opus 4.6 --- README.md | 2 +- apps/marketing/src/content/docs/getting-started/installation.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index fcefbf6c..34a50151 100644 --- a/README.md +++ b/README.md @@ -146,7 +146,7 @@ plannotator review # Code review for current changes plannotator annotate file.md # Annotate a markdown file ``` -No plugin or skill configuration needed — Codex runs `plannotator` as a normal shell command. Plan mode is not yet supported. +Plan mode is not yet supported. See [apps/codex/README.md](apps/codex/README.md) for details. diff --git a/apps/marketing/src/content/docs/getting-started/installation.md b/apps/marketing/src/content/docs/getting-started/installation.md index fbe6f981..169c3293 100644 --- a/apps/marketing/src/content/docs/getting-started/installation.md +++ b/apps/marketing/src/content/docs/getting-started/installation.md @@ -101,7 +101,7 @@ Coming soon. ## Codex -No plugin or skill required — Codex runs `plannotator` as a normal shell command. Plan mode is not yet supported. +Plan mode is not yet supported. Install the binary, then use it directly: From 1df0f936d6d42d576e43d1e57899ca00869f0f43 Mon Sep 17 00:00:00 2001 From: Michael Ramos Date: Mon, 9 Mar 2026 20:48:06 -0700 Subject: [PATCH 6/7] docs(codex): lead with supported features Co-Authored-By: Claude Opus 4.6 --- apps/codex/README.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/apps/codex/README.md b/apps/codex/README.md index cd767348..c158619b 100644 --- a/apps/codex/README.md +++ b/apps/codex/README.md @@ -1,8 +1,6 @@ # Plannotator for Codex -> **Plan mode is not yet supported.** Plannotator's plan review UI requires hooks to intercept the agent's plan submission, and Codex does not currently expose a hook system. Code review and markdown annotation work today. - -Plannotator works in Codex via the CLI binary — no plugin or skill required. Codex runs `plannotator` as a normal shell command. +Code review and markdown annotation are supported today. Plan mode is not yet supported — it requires hooks to intercept the agent's plan submission, which Codex does not currently expose. ## Install From 53c384b6ad1b9efa7f5ba320ddd440080fa3f26a Mon Sep 17 00:00:00 2001 From: Michael Ramos Date: Mon, 9 Mar 2026 20:48:57 -0700 Subject: [PATCH 7/7] docs(codex): use ! prefix for shell commands Co-Authored-By: Claude Opus 4.6 --- README.md | 6 +++--- apps/codex/README.md | 12 ++++++------ .../src/content/docs/getting-started/installation.md | 6 +++--- 3 files changed, 12 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 34a50151..d9231d6b 100644 --- a/README.md +++ b/README.md @@ -141,9 +141,9 @@ irm https://plannotator.ai/install.ps1 | iex **Then in Codex, run directly:** -```bash -plannotator review # Code review for current changes -plannotator annotate file.md # Annotate a markdown file +``` +!plannotator review # Code review for current changes +!plannotator annotate file.md # Annotate a markdown file ``` Plan mode is not yet supported. diff --git a/apps/codex/README.md b/apps/codex/README.md index c158619b..e9defa08 100644 --- a/apps/codex/README.md +++ b/apps/codex/README.md @@ -20,20 +20,20 @@ irm https://plannotator.ai/install.ps1 | iex ### Code Review -Run `plannotator review` to open the code review UI for your current changes: +Run `!plannotator review` to open the code review UI for your current changes: -```bash -plannotator review +``` +!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: +Run `!plannotator annotate` to annotate any markdown file: -```bash -plannotator annotate path/to/file.md +``` +!plannotator annotate path/to/file.md ``` ## Environment Variables diff --git a/apps/marketing/src/content/docs/getting-started/installation.md b/apps/marketing/src/content/docs/getting-started/installation.md index 169c3293..c984e951 100644 --- a/apps/marketing/src/content/docs/getting-started/installation.md +++ b/apps/marketing/src/content/docs/getting-started/installation.md @@ -105,7 +105,7 @@ Plan mode is not yet supported. Install the binary, then use it directly: -```bash -plannotator review # Code review for current changes -plannotator annotate file.md # Annotate a markdown file +``` +!plannotator review # Code review for current changes +!plannotator annotate file.md # Annotate a markdown file ```