mirror of
https://github.com/backnotprop/plannotator.git
synced 2026-09-14 14:17:26 +08:00
Michael Ramos
fc655beb0e
* feat: extract checklist utilities to shared package Move ChecklistItem, parseChecklist, extractDoneSteps, and markCompletedSteps from Pi extension to @plannotator/shared for reuse by the OpenCode plugin. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * feat: Pi-style iterative planning for OpenCode plugin Rewrite the OpenCode plugin to match Pi's planning methodology: - Inject rich iterative planning prompt when agent is "plan" (explore → update plan → ask user loop, structured plan format) - File-based submit_plan: reads plan from disk instead of requiring it as a string arg. Resolves path from OpenCode's system prompt, falls back to PLAN.md - Suppress plan_exit via tool.definition hook (directs to submit_plan) - Add PLANNOTATOR_ALLOW_SUBAGENTS env var for #289 - Pass planFilePath to denial feedback template - Keep existing subagent/build/title guards intact Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: address review findings in OpenCode plugin - Cache agents list (static per session, was fetched every LLM call) - Remove TOCTOU: drop redundant file.exists() before file.text() - Eliminate duplicate system.join() by reusing joined string - Resolve getSharingEnabled() once in submit_plan instead of twice - Use path.join() instead of string concatenation for file paths Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * feat: session-scoped plan files and tool-neutral prompt Replace plugin-global resolvedPlanFilePath and prompt-path parsing with per-session plan files at ~/.plannotator/session-plans/opencode/{id}/plan.md. Remove resolvePlanFilePath() regex (fixes spaces-in-path and cross-session race). Make planning prompt tool-neutral (no write/edit references) so it works with apply_patch models. Strip OpenCode's native read-only and experimental-mode prompt lines before injecting Plannotator's planning prompt. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * feat: directory-based plan storage with path validation Replace session-scoped plan files with a shared plan directory at ~/.plannotator/session-plans/opencode/. Agent picks the filename, submit_plan takes a path arg and validates it (absolute, inside plan dir, exists, readable, non-empty) with canonical path checks to defeat traversal and symlink escapes. Remove summary and plan string args. Planning prompt is now tool-neutral and directs the agent to reuse the same file on feedback, not create new ones. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: use OpenCode's native plans directory for permission compatibility OpenCode's plan mode permission ruleset only allows edits to .opencode/plans/*.md and $XDG_DATA_HOME/opencode/plans/*.md. Our custom ~/.plannotator/session-plans/opencode/ path was blocked by PermissionDeniedError at the tool level regardless of prompt stripping. Switch to the XDG path that OpenCode already allows. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * feat: exploration-first planning prompt Restructure the planning prompt as a phased workflow: Explore → Ask → Write → Submit. The agent now explores the codebase before creating a plan file or asking questions, producing better-researched plans for existing codebases. Greenfield tasks can skip straight to questions. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * chore: fix stale path in JSDoc header comment Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@plannotator/opencode
Annotate plans. Not in the terminal.
Interactive Plan Review for OpenCode. Select the exact parts of the plan you want to change—mark for deletion, add a comment, or suggest a replacement. Feedback flows back to your agent automatically.
Obsidian users can auto-save approved plans to Obsidian as well. See details
Watch Demo
|
Install
Add to your opencode.json:
{
"$schema": "https://opencode.ai/config.json",
"plugin": ["@plannotator/opencode@latest"]
}
Restart OpenCode. The submit_plan tool is now available.
Slash commands: Run the install script to get
/plannotator-review:curl -fsSL https://plannotator.ai/install.sh | bashThis also clears any cached plugin versions.
How It Works
- Agent calls
submit_plan→ Plannotator opens in your browser - Select text → annotate (delete, replace, comment)
- Approve → Agent proceeds with implementation
- Request changes → Annotations sent back as structured feedback
Features
- Visual annotations: Select text, choose an action, see feedback in the sidebar
- Runs locally: No network requests. Plans never leave your machine.
- Private sharing: Plans and annotations compress into the URL itself—share a link, no accounts or backend required
- Plan Diff: See what changed when the agent revises a plan after feedback
- Obsidian integration: Auto-save approved plans to your vault with frontmatter and tags
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 plans in. macOS: app name or path. Linux/Windows: executable path. |
PLANNOTATOR_SHARE_URL |
Custom share portal URL for self-hosting. Default: https://share.plannotator.ai. |
PLANNOTATOR_PLAN_TIMEOUT_SECONDS |
Timeout for submit_plan review wait. Default: 345600 (96h). Set 0 to disable timeout. |
Devcontainer / Docker
Works in containerized environments. Set the env vars and forward the port:
{
"containerEnv": {
"PLANNOTATOR_REMOTE": "1",
"PLANNOTATOR_PORT": "9999"
},
"forwardPorts": [9999]
}
Then open http://localhost:9999 when submit_plan is called.
See devcontainer.md for full setup details.
Obsidian Integration
Save approved plans directly to your Obsidian vault.
- Open Settings in Plannotator UI
- Enable "Obsidian Integration" and select your vault
- Approved plans save automatically with:
- Human-readable filenames:
Title - Jan 2, 2026 2-30pm.md - YAML frontmatter (
created,source,tags) - Auto-extracted tags from plan title and code languages
- Backlink to
[[Plannotator Plans]]for graph view
- Human-readable filenames:
Links
License
Copyright 2025 backnotprop Licensed under MIT or Apache-2.0.