Grammar Guard

A Claude Code mod for people who write their prompts in English as a second language, often by dictation.

Claude understands broken English fine, so it never tells you about the mistakes. Grammar Guard fixes them before the prompt is sent, if you want it to, and helps you find the right word when you don't have it.

• Auto-fix on send (off by default, per session): grammar rules from LanguageTool, or a light Haiku fix that also catches dictation slips like "their going" or "my names".
• Drafts at three levels (light, medium, complete). Medium and complete know your project's terms, so "chip three" comes back as "chip tree".
• Word tools: from your own language to English (Italian, German, Spanish, any language), synonyms, and "which project term means this?".
• In the terminal: mistakes underlined in the prompt box, and a band of one-key fixes.

Why I built it. I'm Italian, and I dictate most of my prompts. Dictation drops words and mishears others, and I wanted to send correct English and get better at it, without leaving Claude Code. It's a personal tool that I'm sharing as it is. Issues and ideas are welcome.

Status: what has been tested

Being open about this, since it's a young project:

| Part | Status | |---|---| | /grammar-guard auto on and auto ai in the VS Code extension | Work: the corrected text is what gets sent | | /grammar-guard draft light (Haiku) in VS Code | Works | | /grammar-guard terms, project terms in drafts | Work | | draft medium | Works; may need some tuning (once turned a dictated "complete" into "Claude") | | draft complete | Works, but still needs more tuning: it can add words of its own, guessed from the conversation | | LanguageTool idle stop and restart | Works | | Term list deleted when a session ends | Works | | Terminal: underlines, band fixes, Autocorrect, Undo, word tools, draft keys, auto-fix button | Work | | Platforms | Built on Ubuntu 24.04 under WSL2. macOS and other Linux distributions are untested |

Built with Claude Code 2.1.288. It needs a version that loads mods (function hooks).

What each level sends to Haiku

| Level | Your message | Project terms | Recent conversation | |---|---|---|---| | light, and auto ai | yes | no | no | | medium | yes | yes | no | | complete | yes | yes | yes (last 8 messages) |

Light and auto ai are pure grammar fixes: they use only the words of your own message. Medium also rearranges clauses for clarity; complete rewrites freely. None of them may add requests, questions or constraints you didn't write.

Install

1. The local tools (Ubuntu / Debian)

Everything except Haiku runs on your machine. The apt line is the only step that needs root.

# spelling fallback and synonyms
sudo apt install hunspell hunspell-en-us wordnet

# optional: an offline dictionary from your language to English (FreeDict),
# e.g. ita (Italian), deu (German), fra (French), spa (Spanish), por (Portuguese)
sudo apt install dict-freedict-ita-eng

# LanguageTool (grammar and spelling), about 250 MB; it needs Java 17 or later
mkdir -p ~/.local/share/languagetool && cd ~/.local/share/languagetool
curl -LO https://languagetool.org/download/LanguageTool-stable.zip
unzip -q LanguageTool-stable.zip && rm LanguageTool-stable.zip

Each one is optional, and the mod says what's missing:

| Tool | Used for | Without it | |---|---|---| | LanguageTool | grammar and spelling checks, auto on, Autocorrect | hunspell: spelling only, no grammar | | hunspell + en-US | fallback checker; picks unusual words for project terms | project words are picked by shape only (camelCase, snake_case) | | WordNet (wn) | synonyms | "not installed" | | FreeDict <language>-eng | your language→English, offline | translations go to Haiku | | Python 3 | the helper, bin/gp.py (standard library only) | required |

2. The mod

From a Claude Code session:

/plugin marketplace add Ev3nt1ne/grammar-guard
/plugin install grammar-guard@grammar-guard

Or clone it and load it in every session through ~/.claude/settings.json:

{ "env": { "CLAUDE_CODE_PLUGIN_DIRS": "/path/to/grammar-guard" } }

To try it once without changing settings: claude --plugin-dir /path/to/grammar-guard.

The mod starts LanguageTool itself when a session starts (it takes about 10 seconds to come up; checks use hunspell until then). To check the pieces by hand:

P=/path/to/grammar-guard/bin/gp.py
python3 $P lt-start                       # {"status": "starting"} or "running"
echo "I has a apple" | python3 $P fix     # engine: languagetool, "I have an apple"
python3 $P syn big                        # WordNet synonyms
GP_NATIVE_LANG=it python3 $P tr cane      # FreeDict: dog
python3 $P vocab .                        # this folder's project terms

Use

Commands (VS Code and terminal)

/grammar-guard auto on            fix what you send with grammar rules (LanguageTool, no AI)
/grammar-guard auto ai            fix what you send with Haiku's light fix (catches dictation slips)
/grammar-guard auto off
/grammar-guard auto               the setting, and what happened to the last message sent
/grammar-guard draft light <text>      Haiku: fix errors only, including misheard dictation
/grammar-guard draft medium <text>     ...and rearrange clauses for clarity, using project terms
/grammar-guard draft complete <text>   ...rewrite freely, using the chat and project terms
/grammar-guard terms                   the project terms medium and complete send to Haiku

A draft shows as the command's output for you to copy. Claude also reads that output, as it reads any command output.

Auto-fix details. The switch is per session: every session starts with it off, and parallel sessions keep their own. auto ai waits up to 15 s for Haiku, then uses the rules fix instead. It also falls back to the rules fix when Haiku's version looks like an answer rather than an edit (length far from the original), when it changed a code span, or when the message has a fenced code block. Auto-fix skips messages starting with / and messages over 6,000 characters (pasted logs), and never changes code spans, fenced code, URLs, paths, file names or identifier-looking words.

Your language

Tell the mod which language you translate from, with an ISO code in the env of ~/.claude/settings.json:

{ "env": { "GP_NATIVE_LANG": "it" } }

Two-letter (it, de, fr, es…) and three-letter (ita, deu…) codes both work. The translate tool then uses the FreeDict <language>-eng dictionary if you installed it, and Haiku otherwise; the band shows the pair, e.g. Translate IT→EN. Without GP_NATIVE_LANG, Haiku detects the language by itself (Translate any→EN). English is always the language you write in.

In the terminal

The VS Code extension gives mods no drawing surface, so this part is terminal only.

• Underlines in the box: after you stop typing for 0.8 s, problems are underlined: red for spelling and grammar, yellow for style.
• The band above the box: reach it with ctrl+x tab or a click, then:
  • 1 2 3 apply the fix shown for the first three problems
  • a Autocorrect: apply every spelling and grammar fix (no AI)
  • l / m / r Light / Medium / Rewrite: Haiku's draft replaces the box
  • u Undo the last change
  • w word tools for the word under the cursor (see below)
  • x cycle auto-fix on send: off → on (rules) → ai → off
• Word tools: move the cursor onto a word in the box, press ctrl+x tab, then w. The band switches to that word: t Translate to English (dictionary, else Haiku), s Synonyms, p Project term (Haiku matches by meaning), b Back. Then 1–9, or a click, puts a result in place of the word.
• Keys go to the band only while it has the keyboard. If a letter lands in the box instead, press ctrl+x tab again first.

A lowercase letter at the start of a sentence is not flagged (or fixed) by default: many people type prompts that way, and Claude doesn't mind. To flag it, set GP_SENTENCE_CAPS=1 in the env of ~/.claude/settings.json. A lowercase "i" is still flagged.

To stop a word being flagged as misspelled: python3 bin/gp.py ignore WORD (saved in ~/.config/grammar-guard/ignore.txt).

Project terms

Project terms are often plain English phrases ("chip tree", "interview profile") rather than unusual words, so a dictionary alone can't find them. gp.py vocab looks for three things in the folder's files (git's file list, or a walk of the folder), up to 200 entries:

• Phrases (up to 80): a concept named in the code (chipTree, chip_tree, ChipTree) that also appears in plain words in docs or comments ("chip tree"). Also a phrase the docs put in a heading, bold or backticks, or one that appears all over the code.
• Files (up to 30): the folder's name, and file names the files mention.
• Words: words an English dictionary (hunspell en_US) doesn't know, used at least twice, those that also appear in docs or comments first. Code keywords (const, async) and short lowercase abbreviations (cmd) are dropped.

/grammar-guard terms shows the current list. A concept that only lives in prose, without emphasis, isn't found; a concept used only in code is found only when it's frequent.

Privacy, storage and what it can access

• What leaves your machine: your message (and, for medium and complete, the project terms; for complete, the last 8 messages of the conversation) goes to Haiku through your own Claude Code login, the same place your conversation already goes. Nothing goes anywhere else. LanguageTool, hunspell, WordNet and FreeDict run locally.
• Keys stay out of the term list. Files such as .env, *.key, *.pem, lock files and anything named secret, credential or token are skipped, and key-shaped strings (long, with digits or random-looking capitals) are removed before anything is counted.
• Files it writes: term lists in ~/.cache/grammar-guard/terms-<hash of the folder>.json (readable only by you; rebuilt after 10 minutes, deleted when the session ends, and any list older than a day is deleted at the next session start), small timestamp files in the same folder, and ~/.config/grammar-guard/ignore.txt if you use ignore.
• Files it reads: the text files of the project folder (for project terms), and nothing else of yours.
• Processes: python3 bin/gp.py for each check, java for the LanguageTool server, and a small watcher (gp.py lt-watch).
• Network: LanguageTool listens on 127.0.0.1:8081 only. Its log (server.log) records the length and timing of each check, not the text.
• Mods API calls: $.process.run, $.model.complete (Haiku), $.session.messages (complete drafts only), $.session.cwd, $.prompt.read / $.prompt.fill (terminal), state, commands and UI.

Resources

• With auto-fix off, sending a prompt costs nothing. With auto on, a send waits for a LanguageTool check: about 0.3 s, or 1–2 s for the first one after a pause. With auto ai, a send waits for Haiku, up to 15 s.
• A session start waits about 0.1 s for the helper.
• The LanguageTool server uses about 600 MB of memory. A watcher stops it after 30 minutes without a check and then exits; the next session start or check starts both again (that one check is spelling only, and /grammar-guard auto says so). Change the 30 minutes with the GP_LT_IDLE_MIN environment variable. The watcher finds the server through /proc, so the idle stop works on Linux and WSL only.

Known limits

• LanguageTool misses dictation errors made of correctly spelled words ("my names", "their going"). auto ai catches those.
• In VS Code there are no underlines or band: only the commands and auto-fix.
• In the terminal, the band's keys work only after ctrl+x tab gives it the keyboard.
• In the terminal the underline is straight, not a zigzag (the API offers only underline), there's no right-click menu, and the band sits above the prompt box (there's no slot below).

Files

• hooks/register.tsx: the mod (command, auto-fix hook, drafts, box underlines, band with word tools)
• bin/gp.py: the no-AI helper, standard-library Python; every command prints JSON
• types/index.d.ts: the mod's state contract
• tests/grammar-guard.test.tsx: tests, run with claude plugin test .

Development

claude plugin validate .
claude plugin test .
claude --plugin-dir .        # loads it for one session; reload with /reload-plugins

Credits

LanguageTool (LGPL, installed separately, not bundled), hunspell, WordNet and FreeDict do the offline work.

License

MIT