pi-harper-grammar

Type it right, make the agent guess less.

Live grammar checking of the chat input box in Pi and OMP (Oh My Pi), powered by Harper.

It lints what you are about to send — the text in the input editor — and shows issues (with fixes) in a widget just below the editor. It does not read or check your project files, and it never sends anything to the model to do the check: everything runs locally through harper-cli.

Prerequisite: Harper

This extension shells out to the harper-cli binary. Install it first:

• macOS: brew install harper
• Cargo: cargo install harper-cli
• Other: see https://writewithharper.com / the releases

harper-cli must be on your PATH (or point $HARPER_CLI at it). If it's missing, the extension shows a one-line install hint instead of failing silently.

Install

# Pi
pi install npm:pi-harper-grammar

# OMP (Oh My Pi)
omp plugin install npm:pi-harper-grammar

Or straight from git without npm:

pi install git:github.com/LoneExile/pi-harper-grammar

Restart the agent (or open a new session) after installing.

Usage

Just type. As soon as your input is stable for a moment, Harper checks it and lists any issues below the editor. The widget clears when the input is empty, corrected, or a slash command.

• alt+g — apply Harper's suggested fixes to the current input, in place.
• /grammar — toggle the live checker on/off.
• /grammar-allow <term> — never flag <term> again (-<term> to undo, no args to list).

alt+g applies the issues Harper can concretely replace (spelling, agreement, a/an, punctuation, etc.). A lint with no replacement suggestion is left for you to fix by hand — the alt+g to fix hint appears only when something is auto-fixable.

Configuration

• $HARPER_CLI — absolute path to the harper-cli binary, if it isn't on PATH.

• Allow list — terms this extension drops from the results, whatever rule fired. One term per line, # starts a comment, matched case-insensitively against the text Harper flagged (so a multi-word entry like cloud flare works too). Default location ~/.config/harper-grammar/allow.txt; override with $HARPER_GRAMMAR_ALLOW. Use /grammar-allow or edit the file directly — either way the widget refreshes on the next poll, no restart:

  # ~/.config/harper-grammar/allow.txt
  cloudflare
  kubeconfig
  cloud flare

• User dictionary — Harper's own per-user dictionary (one word per line), at the path printed by harper-cli lint --help (--user-dict-path). Adding a word there teaches Harper that it exists, which silences SpellCheck — but other rules can still fire. A lowercase cloudflare in the dictionary trades "Did you mean Cloudflare?" for OrthographicConsistency ("the canonical dictionary spelling is title case"). Use the allow list above when you want a term left alone unconditionally.

Tunables live at the top of extensions/harper-grammar.ts:

• POLL_MS — how often the editor is polled (debounce cadence).
• MAX_LINES — how many issues are shown at once.

How it works

There is no per-keystroke editor event, so the extension polls ctx.ui.getEditorText() on a timer and runs harper-cli once the text has been stable across a tick (a lightweight debounce). Results are parsed from harper-cli lint --format json and rendered via ctx.ui.setWidget(...) in a belowEditor widget. Warm harper-cli runs in well under a second, and a check only fires when the text — or the allow list — actually changes.

This checks your input before you send it. It does not grammar-check the assistant's replies.

License

MIT — see LICENSE.