plain-english weekly downloads statistics

plain-english

Catch filler and unexplained jargon in your coding agent's writing.

plain-english checks a draft and gives the agent the passage, the rule, and a rewrite hint. It can check documents, commit and pull request text, issues, and completed chat replies. You control the rules and whether findings block a write.

Install in Claude Code

In a Claude Code session, version 2.1.293 or newer:

/plugin install plain-english --marketplace nordscope-fi/plain-english

The plugin runs checks automatically. With no project config, findings are advisory. See the plugin guide for configuration and supported checks. For another agent, see the setup below.

A real draft, checked before it was saved

Claude Code drafted a pull request description. The plugin caught an abbreviation used without an explanation and refused the save. Claude revised it without another user prompt, and the next save succeeded.

First draft, excerpt:

Add SARIF output to plain-english

This PR adds SARIF output to plain-english, the prose linter for Markdown and plain text. Lint results can now be read by tools that accept SARIF, including GitHub code scanning.

The finding returned to Claude:

line 1: "SARIF" (unglossed-term) "SARIF" is not explained. Say what it does, then name it.

The agent's next draft, excerpt:

Add Static Analysis Results Interchange Format (SARIF) output to plain-english

This PR lets plain-english, the prose linter for Markdown and plain text, write its results in SARIF. SARIF is a standard format for reporting results from code analysis tools. With this change, tools that read SARIF, such as GitHub code scanning, can use plain-english results.

The animation replays text captured from a live run. Warning-level blocking was enabled for this example. The recording notes include the full prompt, drafts, configuration, and an earlier task that passed without a rewrite.

Check files yourself

The command-line tool checks Markdown and plain text and reports exact passages and rewrite hints:

npm install -D plain-english
npm pkg set scripts.prose=plain-english
npm run prose -- lint .

The second line adds a prose script to package.json, so every command runs the copy you installed. Node 20 or newer is required. The first run needs no config. Blocking is opt-in. You can tune the rules before they stop a build.

To make blocking findings return a failing exit code, add .plain-english.yml:

version: 1
extends: default
failOn: error

Use failOn: warn to fail on warnings too. Use failOn: never to keep every run advisory.

What it checks

The built-in rules cover:

• stock transitions and filler, such as an opener that announces the conclusion;
• corporate verbs and vague claims that should name a concrete result;
• punctuation patterns strongly associated with generated prose;
• acronyms and product names used before they are explained;
• sentences that are long or show little variation across a document;
• suppressions that give no reason.
• internal citation markers and unfinished template fields;
• clusters of related findings that form one repeated pattern.

plain-english explain lists every rule. Pass a rule name to see its match, exceptions, severity, and rewrite hint:

npm run prose -- explain
npm run prose -- explain unglossed-term

The explanation also shows whether a check is a writing-quality rule, a known machine marker, or both. It includes the review date and supporting source.

The normal scan is deterministic. An optional model-backed check covers sentence shapes that regular expressions cannot judge, such as vague attribution and canned contrasts. Set modelChecks: false in the project config to keep extra checks local to pattern matching. Extra model checks send eligible proposed document text or publishing text, and sometimes the last chat question, through the agent's configured provider and account. Document context can include code examples and quoted material. They use your plan or API usage. Claude calls disable local session persistence; provider retention still follows account settings. Set modelChecks: true to enable the extra checks on other supported agents. The native Claude plugin also adds declared project vocabulary and loaded writing-profile guidance at conversation start. Agent support for that check varies. The agent guide records what each integration can run.

What it ignores

The scanner removes code, frontmatter, blockquotes, link targets, and tables before it checks prose. A code sample that contains a banned word will not produce a finding.

Rules also include exceptions for valid technical uses. For example, a financial term can pass while the same word used as a vague business verb can fail.

The generated rule guide lists the full ruleset, its exceptions, and everything excluded from scanning.

Add it to a coding agent

init adds the selected agent's hooks, a local launcher, project instructions, and a starter config. It merges with files that already exist.

npm run prose -- init --agent codex --dry-run
npm run prose -- init --agent codex

The dry run shows the diff first.…