Plan plugins
Plannotator (Plan provider)
Plannotator for VibeControls
Plannotator plan provider — wraps the upstream CLI and configures per-AI-agent hooks.
$
vibe plugin install @vibecontrols/vibe-plugin-plan-plannotator
About this plugin
Plannotator plan provider for the VibeControls agent. Wraps the upstream plannotator CLI:
- Installs the
plannotatorbinary on demand (sha256-pinned). - Spawns a per-session plannotator HTTP server on a dedicated port.
- Reverse-proxies the local UI at
/plan/:sessionId/*, stripping iframe-blocking headers so the agent's vibetunnels URL can embed it. - Configures AI-agent hooks (Claude Code, OpenCode, Codex, Pi, Gemini) so completed plans land in plannotator automatically.
- Registers with the agent's
ServiceRegistryunder the"plan"type so the meta plugin@vibecontrols/vibe-plugin-plancan dispatch to it.
Install
vibe plugin install @vibecontrols/vibe-plugin-plan
vibe plugin install @vibecontrols/vibe-plugin-plan-plannotator
vibe plan-plannotator install # downloads the binary
Or set VIBE_PLANNOTATOR_AUTOINSTALL=1 to auto-install on first plan
request (not recommended for shared agents).
REST API
Mounted under /api/plan-plannotator on the agent (plus /plan/:sessionId/*
as the reverse proxy).
| Method | Path | Description |
|---|---|---|
GET | /status | Binary install status + running sessions |
POST | /install | Run the sha256-pinned installer |
GET | /prereqs | Same as /status (matches meta-plugin contract) |
POST | /prereqs/install | Alias of /install |
POST | /stop?sessionId= | Stop a specific session, or all sessions |
GET | /agents/supported | Detect installed AI agents + hook status |
POST | /agents/:agent/configure-hook | Write the plannotator hook for an agent |
POST | /agents/:agent/unconfigure-hook | Remove the hook |
:agent is one of claude, opencode, codex, pi, gemini.
CLI
vibe plan-plannotator status
vibe plan-plannotator install
vibe plan-plannotator stop [--session <id>]
vibe plan-plannotator agents list
vibe plan-plannotator agents configure <agent>
vibe plan-plannotator agents unconfigure <agent>
Configuration
Environment variables (all optional):
| Name | Default | Meaning |
|---|---|---|
PLANNOTATOR_PORT | 19432 | Preferred port for plannotator. Falls back to a scan of +10. |
VIBE_PLANNOTATOR_AUTOINSTALL | unset | If 1, auto-install the binary on first session start. |
VIBE_PLANNOTATOR_INSTALL_UNPINNED | unset | If 1, bypass the sha256 pin on install.sh (NOT recommended). |
VIBE_PLANNOTATOR_IDLE_MS | 900000 | Kill a session after this many ms of inactivity. |
VIBE_PLANNOTATOR_IDLE_SCAN_MS | 60000 | Idle watchdog scan interval. |
Per-agent hook setup
- Claude Code: writes a
PreToolUsehook matched toExitPlanModein~/.claude/hooks.json. - OpenCode: adds
@plannotator/opencodeto thepluginarray in~/.config/opencode/opencode.json. - Codex CLI: appends a
[hooks.plannotator]block bracketed by marker comments in~/.codex/config.toml. - Pi: drops
~/.pi/hooks/before_agent_start.d/vibe-plan-plannotator.sh. - Gemini CLI: drops
~/.gemini/hooks/vibe-plan-plannotator.sh.
All hooks are idempotent (re-running configure does not duplicate) and
refuse to write outside $HOME.
Troubleshooting
- Port 19432 in use: set
PLANNOTATOR_PORTto another port. The provider scans the next 10 if the preferred port is busy. - Iframe blocked: confirm the agent's reverse proxy mounts cleanly
by hitting
${tunnelUrl}/plan/— expect a 404 placeholder, not a 502. - Hung session:
vibe plan-plannotator stop --session <id>(or the 15 min idle watchdog will reap it).
Development
bun install
bun run sanity # format:check + lint + type:check + test + build
Use it in 30 seconds
- Make sure the agent is running:
vibe start - Install the meta first:
vibe plugin install @vibecontrols/vibe-plugin-plan - Install this plugin:
vibe plugin install @vibecontrols/vibe-plugin-plan-plannotator - List installed plugins:
vibe plugin list