ste-guard

A Claude Code plugin that keeps Claude's replies in Simplified Technical English.

Claude talks too much. This makes it talk less.

What it does

1. A SessionStart hook injects a short rule card one time.
2. A Stop hook checks each reply. When a rule fails, the hook blocks once and returns the violations. Claude rewrites and sends the clean version.
3. A UserPromptSubmit hook injects the full rule text with the exact banned strings. In the default lazy mode this hook stays silent until the Stop hook blocks once.
4. A PreToolUse hook checks the markdown a Write or an Edit puts on disk. When a rule fails, the hook denies the call and returns the violations. It reads markdown only.
5. A ste-check command lets Claude lint a draft before it sends the draft.

The rules come from ASD-STE100, adapted for chat. This is not certified conformance. The ASD licenses the official approved dictionary, so this repository does not carry it.

Why the injection is lazy

An always-on rule injection costs about 1,000 tokens per turn. A 50-turn session pays 50,000 tokens to repeat rules that Claude read at the start.

The lazy mode pays once at session start, then nothing. When Claude breaks a rule, the hook arms itself and injects the full contract for the rest of the session. A clean session pays nothing beyond the opening card.

Set injection to always when you prefer the predictable cost.

Install

claude plugin marketplace add https://github.com/ofrusch/ste-guard.git
claude plugin install ste-guard@ste-guard

The owner/repo shorthand also works, but Claude Code clones that form over SSH. The full HTTPS URL above clones over HTTPS instead, so it works without an SSH key. To keep the shorthand and still clone over HTTPS, set CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1.

Optionally set the output style to STE with /output-style. The hooks work without it.

Install for Codex

Codex reads the same marketplace file, so the first two steps match.

codex plugin marketplace add https://github.com/ofrusch/ste-guard.git
codex plugin add ste-guard@ste-guard
python3 ~/.codex/plugins/cache/ste-guard/ste-guard/<version>/scripts/codex-install.py

The third step exists because Codex v0.147 installs a plugin's skills but does not load the hooks the plugin ships. The script writes the four hook entries into ~/.codex/hooks.json by absolute path. It backs the file up first, it leaves your other hooks alone, and it never stacks duplicates. Run it again after a plugin update, because the version sits in the path.

Codex asks you to trust each new hook command on the next interactive run. Until you approve them, Codex skips the hooks without a warning. Run codex once and accept the four prompts.

Remove the entries with --uninstall.

What differs on Codex

• A Codex Stop hook that blocks does not reject the reply. Codex continues the turn with the violations as a new prompt, so the first draft stays in the transcript.
• The ste skill loads from the plugin with no extra step.

Install for pi

pi install npm:ste-guard

The package carries the extension and the skill. pi loads the TypeScript through jiti, so no build step runs. Install from a checkout with pi install ./ste-guard, or try it for one session with pi -e ./extensions/ste-guard.ts.

What differs on pi

• pi has no block primitive on an assistant message. The extension asks for a rewrite through a follow-up user message instead. The model regenerates, and both the first draft and the correction stay in the transcript.
• pi streams the reply before the check runs, so you see the first draft appear.
• The extension holds no rules of its own. It runs the same Python checker the other two agents run.

Pick your features

Run the setup script for the questions. It writes ~/.claude/ste-guard.json, and it backs up the file it replaces.

python3 ~/.claude/plugins/ste-guard/scripts/ste-setup.py

Inside a session, run /ste-setup instead. Claude asks the questions and runs the script.

| Flag | Effect | | :-- | :-- | | --show | Prints the current config | | --profile default\|peer-eng | The register to extend | | --write-guard deny\|warn\|off | What the write guard does with a failing file | | --injection lazy\|always\|never | When the hook injects the full rule text | | --telemetry on\|off | Records one line per turn, with no message text | | --rules-off a,b | Turns named rules off | | --rules-on a,b | Turns named rules on | | --write-suffixes .md,.mdx | The file types the write guard reads | | --reset | Deletes the config and falls back to the bundled default |

STE_GUARD_PROFILE wins over this file. Unset it before you run the setup script.

Configuration

ste-guard resolves the active profile in this order:

1. The STE_GUARD_PROFILE environment variable, read as a bundled profile name or a file path.
2. The file at ~/.claude/ste-guard.json.
3. The bundled profiles/default.json.

A user profile does not need to restate the whole schema. Name a parent with extends, then override only the keys you want.

Profile schema

| Key | Type | Meaning | | :-- | :-- | :-- | | extends | string | A bundled profile name to inherit from | | injection | string | lazy, always, or never. off is an alias for never | | min_words_to_lint | number | Replies shorter than this are never checked | | soft_block_threshold | number | Soft violations needed to block on their own | | max_blocks_per_message | number | Blocks allowed against one message digest | | max_blocks_per_chain | number | Consecutive blocks before the hook gives up | | budget.words | number or null | Word ceiling per reply. null removes the cap | | budget.sentence_words | number or null | Word ceiling per sentence | | budget.uncapped_on_heading | boolean | A markdown heading lifts the word ceiling | | rules.* | boolean | One switch per rule. See the table below | | lists.* | array | Replaces a phrase list | | lists_add.* | array | Appends to a phrase list | | lists_remove.* | array | Removes entries from a phrase list | | autofix_adjectives | array | Extra words the --fix pass may delete before a noun | | write_guard.enabled | boolean | The write guard switch | | write_guard.mode | string | deny blocks the write. warn reports and lets it land | | write_guard.profile | string | The profile the write guard lints with | | write_guard.suffixes | array | The file types the write guard reads |

Rule switches

| Switch | What it catches | | :-- | :-- | | openers | Filler openers such as a warm-up compliment | | closers | Hollow sign-offs | | puffery | Marketing adjectives | | not_just | The "not just X, it is Y" construction | | asides | Mid-sentence parenthetical and em-dash interruptions | | gerund | A sentence that opens with an -ing form | | passive | Passive voice | | narration | Process narration, which reports the search instead of the finding | | flourish | Wordplay and rhetorical symmetry | | prose_wall | A long reply with dense paragraphs and no bullets |

Bundled profiles

• default — the ASD-STE100 chat subset with a 250-word ceiling. Grammar only, no voice.
• peer-eng — a blunt senior-engineer register. A 130-word ceiling, bullets by default, every rule on.
• docs — full STE for a file on disk. No word ceiling, every phrase rule on. The write guard always runs this profile, whatever the session runs.

Example

Write ~/.claude/ste-guard.json to keep the grammar rules and drop the word ceiling:

{
  "extends": "default",
  "budget": { "words": null },
  "lists_add": { "puffery": ["ecosystem", "journey"] }
}

Fix the reflex failures without a rewrite

ste-check --fix draft.md
echo "$DRAFT" | ste-check --fix

The fixer deletes a filler opener, a hollow closing sentence, and a puffery adjective that stands before a noun. It never rewrites a sentence. It reports every fix on stderr, and it lists what still needs a person.

The fixer is deliberately timid. It leaves a predicate use such as "the parser is robust" alone, because a deletion there breaks the sentence. It leaves a hyphenated entry alone, because the phrase list holds stems.

Two rules keep the fixer from deleting meaning:

• It deletes a known adjective only. A word that also reads as a noun or a verb stays, so "the leverage ratio" never becomes "the ratio". Name your own safe words with autofix_adjectives in a profile.
• It deletes a closing sentence only when the rest of that sentence is filler. A sentence that also carries a number, a path, or an imperative verb stays whole.

Measure the rules

Telemetry is off by default. Turn it on with "telemetry": true in your profile, or with STE_GUARD_TELEMETRY=1. Each turn appends one line to telemetry.jsonl in the state directory. The line holds counts and rule numbers only. It never holds your message text.

scripts/ste-stats.py

The reader prints the block rate, the mean words per turn, the violations per 100 words, and the share each rule contributes. Use it to find the rules that only nag, then switch them off in your profile.

Quoted text is exempt

The checker blanks any run inside double quotes before it applies the phrase lists. Claude can therefore name a banned phrase when it explains the phrase to you. Claude cannot use one. Inline code, fenced code, block quotes, links, and file paths are also exempt.

Environment variables

| Variable | Effect | | :-- | :-- | | STE_GUARD_OFF=1 | Disables every hook | | STE_GUARD_WRITE_OFF=1 | Disables the write guard, and leaves the reply guard on | | STE_GUARD_DEBUG=1 | Writes the hard and soft counts to stderr | | STE_GUARD_PROFILE | Selects a bundled profile by name, or a profile file by path | | STE_GUARD_TELEMETRY=1 | Records one line per turn, without the message text | | STE_GUARD_STATE_DIR | Moves the block counters and the telemetry log |

Limits

• No Claude Code hook rewrites a reply in place. The Stop hook can only block and hand back the violations. A rewrite therefore costs a second generation.
• The word ceiling and the bullets rule need judgment, so a regular expression cannot fix them. Only a rewrite can.
• The checker matches fixed strings. A model that invents a new filler phrase gets through until you add the phrase to a list.
• The write guard reads .md, .markdown, and .mdx only. A comment in a source file, a commit message, and a PR body all pass with no check.
• The write guard reconstructs the file the tool is about to write, then reports only the violations that call introduces. A defect already on disk never blocks an unrelated edit.
• The write guard reads the tool names Write, Edit, and MultiEdit. Another agent that edits a file under a different tool name gets through.

Tests

Both suites use only what the runtime ships, so neither needs an install step.

python3 -m unittest discover -s tests -v
node --test tests/extension.test.ts

Four of the tests run the plugin's own documentation through the checker, so the docs cannot drift out of conformance without a red build.

Related work

• AminBlg/SimpleEnglish — an STE skill and plugin that gates file writes through a PreToolUse hook, with published benchmarks.
• danyuchn/asd-ste100-skill — the ASD-STE100 rules packaged as a skill.

ste-guard differs in one way. It gates the reply, not the file write.

License

MIT