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

Files

T

History

Michael Ramos 747b5ea7e6 fix(annotate): resolve natural-language arguments or hand off to the agent (#1183 )

* fix(annotate): resolve natural-language arguments or hand off to the agent

Claude Code skills run the CLI through a bash-substitution prefix that
executes before the model sees anything, so any trailing natural language
in /plannotator-annotate died with 'File not found: the'. Worse, a
non-zero exit from that prefix aborts the whole prompt before the model
runs (verified empirically), so the error was never even visible to the
agent.

Three-tier resolution in the binary's annotate argument handling, shared
by every host via packages/shared/annotate-target.ts:

1. Fast path: probe each whitespace-delimited token; exactly one naming
   an existing file, URL, or folder proceeds with it directly.
2. Ambiguity: two or more tokens resolve; error naming every candidate,
   never guess.
3. Handoff: nothing resolves; emit an agent-addressed message echoing
   the words tried and asking the reading agent to interpret the request
   and re-run with a concrete target, preserving flags. In plain mode it
   lands on stdout with exit 0, the only combination that reaches the
   model through the bang prefix; in --json/--hook mode it goes to
   stderr with exit 1 so machine stdout stays clean.

Single-token invocations run the unchanged pipeline first, so bare
correct invocations are byte-identical. Strict gates (--require-approval
or --result-file) bypass the tolerance entirely: a typo'd path stays a
startup failure with exit 2 and no agent-facing prose.

The CLI resolution pipeline moves to apps/hook/server/annotate-resolution.ts
(returns typed outcomes instead of exiting) so the token fallback can run
it once with a selected candidate; OpenCode and Pi wire the same shared
selection into their own not-found paths. Skill bodies gain one line
telling the agent to re-run with a concrete target when the command
reports unresolvable arguments.

Closes #1182

Reported-by: @technicalpickles

* fix(annotate): harden tolerant resolution per review

Review fixes for the three-tier annotate argument handling:

- A single unresolvable token now falls through to the legacy pipeline
  verbatim: 'annotate nope.md' is exit 1 with 'File not found: nope.md'
  again in every non-strict mode, instead of an exit-0 handoff that
  fail-opened scripts gating on the exit code. The handoff fires only
  when two or more words resolve to nothing.
- Unrecognized dash-prefixed tokens disable tolerance instead of being
  skipped, so a typo'd flag ('--no-jna') errors the way it did on base
  rather than silently fetching via Jina. Known flags are stripped
  before selection as before.
- Token selection now receives the original argv tokens, so a quoted
  missing path ('my notes.md') is probed as one token and can never be
  re-split into a silently resolving 'notes.md'.
- Bare directory names only count as fast-path candidates when they are
  the sole argument; a stray word matching a directory (or '.') hands
  off instead of opening folder mode. Explicit paths like 'src/' keep
  resolving, and the bare-existence probe fallback is file-only.
- The handoff re-run suggestion echoes content flags only (--markdown,
  --no-jina, --render-html), never transport flags (--gate, --json,
  --hook).
- New subprocess suite (annotate-cli.test.ts) spawns the real CLI entry
  and pins the contract: single-token typo exit 1, strict invocations
  (--require-approval and --result-file) exit 2 with empty stdout and
  no handoff prose, unknown-flag error, quoted-token preservation, and
  the directory-hijack case. Placeholder dist files are created when a
  build is absent so the suite runs in CI.
- The copilot and gemini annotate command bodies gain the same handoff
  instruction as the Claude, core, and kiro skills.
- AGENTS.md documents the three tiers under Annotate Flow and corrects
  the strict-section sentences that claimed non-strict behavior was
  fully unchanged; the marketing annotate doc mentions the tolerant
  arguments.

Refs #1182

2026-08-03 10:14:37 -07:00

commands

fix(annotate): resolve natural-language arguments or hand off to the agent (#1183 )

2026-08-03 10:14:37 -07:00

hooks

feat(gemini): add Gemini CLI plan review integration

2026-04-02 15:24:10 -07:00

README.md

Add an option to disable AI features (#1129 )

2026-07-26 09:59:15 -07:00

README.md

Plannotator for Gemini CLI

Interactive plan review, code review, and markdown annotation for Google Gemini CLI.

Install

Install the plannotator command:

macOS / Linux / WSL:

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

Windows PowerShell:

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

The installer auto-detects Gemini CLI (checks for ~/.gemini) and configures:

Policy file at ~/.gemini/policies/plannotator.toml — allows exit_plan_mode without the TUI confirmation dialog
Hook in ~/.gemini/settings.json — intercepts exit_plan_mode and opens the browser review UI
Slash commands at ~/.gemini/commands/ — /plannotator-review and /plannotator-annotate

How It Works

Plan Mode Integration

When you use /plan in Gemini CLI:

The agent creates a plan and calls exit_plan_mode
The user policy auto-allows exit_plan_mode (skipping the TUI dialog)
The BeforeTool hook intercepts the call, reads the plan from disk, and opens the Plannotator review UI in your browser
You review the plan, optionally add annotations
Approve → the plan is accepted and the agent proceeds
Deny → the agent receives your feedback and revises the plan

Available Commands

Command	Description
`/plannotator-review`	Open interactive code review for current changes or a PR URL
`/plannotator-review <pr-url>`	Review a GitHub pull request
`/plannotator-annotate <file>`	Open interactive annotation UI for a markdown file

Manual Setup

If the installer didn't auto-configure your settings (e.g. ~/.gemini/settings.json already existed), add the hook manually:

{
  "hooks": {
    "BeforeTool": [
      {
        "matcher": "exit_plan_mode",
        "hooks": [
          {
            "type": "command",
            "command": "plannotator",
            "timeout": 345600
          }
        ]
      }
    ]
  }
}

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.
`PLANNOTATOR_AI`	Set to `disabled` to disable Ask AI, Review Agents, and Guided Review.
`PLANNOTATOR_SHARE`	Set to `disabled` to turn off URL sharing.

Requirements

Gemini CLI 0.36.0 or later
plannotator binary on PATH

README.md

Plannotator for Gemini CLI

Install

How It Works

Plan Mode Integration

Available Commands

Manual Setup

Environment Variables

Requirements

Links