simple_english

Write for human, not for agent.

You can teach an agent plain-English prose with a skill or a
prompt. It writes clean prose in the first paragraph and slop again
by the third. This linter keeps the agent honest: it reads what the
agent wrote and names every broken rule. Send the findings back, and
the agent corrects its own text.

The linter covers Markdown prose plus code comments in Python, Ruby,
JavaScript, TypeScript, Go, Rust, Java, C#, C++, Kotlin, bash, and
YAML. Findings print as plain text, JSON, or SARIF.

If your language is not on the list, open an issue.

Agent integrations

Plug the linter into your coding agent. It writes plain English on
the first pass and checks its own draft before you read the file.

If your agent is not on the list, open an issue.

The rules

• Voice: say who does the action.
• Tense: simple tenses only, no present perfect.
• Modals: can, will, must only.
• Punctuation: no em-dashes, no semicolons.
• Contractions: write every word in full.
• Sentence shape: condition before command, no -ing phrase after a comma.
• Word choice: about 50 substitution rules, from leverage to in conclusion. make sure that keeps its "that".
• Code comments: same pattern rules, with line and column range.
• Counts (Markdown only): 20 words per sentence in list items, 25 in paragraphs, six sentences per paragraph at most.

The full list, with a wrong and a right example for each rule docs/RULES.md.

Install

Ruby gem (macOS arm64, Linux x86-64 and arm64)

gem install simple_english

Homebrew (macOS arm64)

brew install TonyCTHsu/tap/simple-english

Container

docker run --rm -v "$PWD":/work ghcr.io/tonycthsu/simple-english .

Usage

Lint files, directories, or stdin:

se README.md
se docs/            # every .md, .py, .rb, .yaml, .yml, ... under docs/
se - < notes.md     # stdin (Markdown)

Lint only what changed:

git diff --name-only --diff-filter=ACM main | xargs -I{} se {}

Outputs

Pattern findings print an exclusive column range as
file:line:start-end: [RULE_ID] message. A range that crosses lines ends
with end-line:end-column. Columns count UTF-16 code units. Counting findings
identify only the paragraph's first line. JSON and SARIF output expose the same
source ranges:

se --format json docs/
se --format sarif src/ > results.sarif

Exit codes

• 0: no findings
• 1: findings
• 2: input, configuration, installation, or daemon error

MCP server

Start an MCP stdio server with one tool, lint. Any MCP
client can call it.

se mcp

CI

Gate the pull request's prose in GitHub Actions. The lint fails the build on findings:

name: lint-docs
on: [pull_request]
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: TonyCTHsu/[email protected]
        with:
          files: |
            docs/
            README.md

To see the findings inline in the pull request, lint with
format: sarif and upload the report. Add
permissions: {security-events: write} to the workflow:

      - uses: TonyCTHsu/[email protected]
        with:
          format: sarif
      - uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: simple-english.sarif
        if: always()

Any CI can run the lint. Install the gem, run se lint ., and fail the
build on exit code 1.

Git hooks

Install the gem once, then wire your hook runner. The command to run
is se lint.

Pre-commit framework

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/TonyCTHsu/simple-english
    rev: v0.11.1
    hooks:
      - id: se-lint

For Husky with lint-staged, map every staged file to se lint. For
Lefthook, run se lint {staged_files} in a pre-commit command.

Config and suppressions

Config file

.simple-english.yml in the working directory:

ignore:
  - vendor/**
disabled-rules:
  - SE_NO_EMDASH

ignore globs: ** crosses directories, * stays in one segment.

Inline suppressions

A line containing se: ignore suppresses findings reported on that
line. Use se: ignore=RULE1,RULE2 to scope it to rules. Pattern
findings cite the line of the match, so put the directive on the line the
finding reports.

In Markdown:

The daemon keeps it's own lock. <!-- se: ignore=SE_NO_CONTRACTIONS -->

In a code comment:

# Don't touch this constant. se: ignore=SE_NO_CONTRACTIONS

FAQ

Why not Vale?

We ported rules to Vale and ran the corpus on both engines.
About 60 rules behave the same. Vale has no check for the em-dash
and semicolon rules: its checks see words, not punctuation. Its
tagger also mislabels verbs, so the condition-first rule stays
silent. Closing the Vale gaps needs scripts or an external
tagger, and that erases Vale's main advantage: one binary with no
service behind it.

Scope

This tool does not check ASD-STE100 compliance. This repo holds no ASD-STE100 text. If you need full compliance, read the free standard at https://www.asd-ste100.org/.

Develop

To change the linter, add rules, or run the tests, read docs/DEVELOPMENT.md.