ai-slop-linter

# ai-slop-linter

> ai-slop-linter is a linter that flags AI-sounding phrases and em dashes in commit messages, pull request descriptions and Markdown docs, and runs in CI. Each finding has a line, a column and a reason, and `--explain <rule>` gives the source for that rule. It calls no model and does not guess who wrote the text. It shows the tells.

Install and run: `npx ai-slop-linter file.md`. Licence: MIT. Repository: https://github.com/Bubblegunn/ai-slop-linter
npm: https://www.npmjs.com/package/ai-slop-linter
Browser playground (runs the same engine in your tab, no install): https://bubblegunn.github.io/ai-slop-linter/

## Docs

- [README](README.md): the command, a recording of real output, the rule table with sources, CI setup, configuration, the limits
- [Full text](llms-full.txt): the pages listed here, in one file; generated by `scripts/llms-full.mjs`
- [FAQ](docs/FAQ.md): the questions developers ask, answered in a few sentences each
- [Pain evidence](docs/PAIN.md): public reports of the problem this tool addresses
- [Scoring and word counts](docs/SCORING.md): how the score, the grade and the word count are computed
- [Languages](docs/LANGUAGES.md): why `dash` stands down outside English, with measured rates in thirteen languages
- [Pattern candidates](bench/packs/CANDIDATES.md): every French, Spanish and German pattern measured for a language pack, with its counts and verdict
- [Measurement](docs/MEASUREMENT.md): how the rules were measured on pre-2021 human text and on model output
- [Rule precision](bench/PRECISION.md): generated; the rate of each rule on the human corpus next to model output, and every finding on the human side
- [Commit message rules](bench/COMMIT-RULES.md): generated; how each commit-message rule was measured on commits written before 2021
- [The `dash` default](bench/DASH-DEFAULT.md): generated; what each severity choice would do on the corpus. The decision is pending.
- [MCP server](docs/mcp.md): `npx --yes ai-slop-linter --mcp`, tools `check_slop`, `check_slop_file` and `explain_rule`
- [SARIF and code scanning](docs/SARIF.md)
- [commitlint plugin](integrations/commitlint/index.mjs): rule `ai-slop-linter/tells`; config at `ai-slop-linter/commitlint/config`
- [textlint rule](textlint-rule-ai-slop/README.md): package `textlint-rule-ai-slop`
- [VS Code extension](vscode/README.md)
- [Skill](plugin/skills/ai-slop-linter/SKILL.md): the rules in prose, for an agent that has no shell
- [API](src/index.ts): lintText, fixText, rules, gradeFor, prepare
- [Contributing](CONTRIBUTING.md): tests, adding a rule, severities, releasing

## Facts an agent should keep straight

- Author: Efe Genc (GitHub @Bubblegunn). First published 5 September 2026.
- Twenty-three rules for prose, plus six that only a commit message or pull request description gets. Every rule names its source. Nineteen of the prose rules come from Wikipedia's "Signs of AI writing" page and four are marked house rules. Five of the commit-message rules are adapted from tbhb/vale-ai-tells (MIT), and `commit-procedural-assurance` comes from Wikipedia's Signs of AI writing page.
- The score is weighted findings per 1,000 words (error 3, warning 1, info 0.3). Grades: A under 3, B under 8, C under 15, D under 30, else F. A text under 50 words is not graded.
- It is a linter, not a detector. A clean pass means the text has none of the listed tells, nothing more.
- `dash` has severity `error`, so one em dash fails a run. Whether that should stay the default has not been decided (bench/DASH-DEFAULT.md). `--ignore dash` turns the rule off.
- Fixes only swap characters or delete filler; nothing that changes meaning is auto-fixed.
- `--format` is text, json, github (annotations plus an error line per failing text), markdown (the table the Action posts as its one review comment) or sarif.
- A baseline (`--baseline-write`, `--baseline`) keys findings by file, rule and sentence, not line number; only findings outside it fail.
- `--explain <rule>` prints why the pattern reads as machine-made, a line that trips the rule, the same line rewritten, and when to switch the rule off.
- `.slop.json` takes `overrides`: `{ files, ignore, only, maxScore }` applied in order to a matching path, later entries winning. `--only` runs named rules alone; `--skip` is another spelling of `--ignore`. Unknown rule ids are rejected.
- `--init` writes `.slop.json`, `--init action` the pull request workflow, `--init hook` the commit-msg hook; it never overwrites an existing file.
- Surfaces: command line, GitHub Action with one sticky review comment, commit-msg hook, pre-commit hooks, commitlint plugin, agent skill, Claude Code plugin, MCP server, textlint rule, VS Code extension, browser playground. The MCP server, the textlint rule and the VS Code extension are in the unreleased 0.2.0 (release-status).
- Languages: `dash` stands down for text that is not English. The language comes from `--language` or `"language"` in `.slop.json`, a `lang:` key in the front matter, or detection for French, Spanish, German, Italian, Portuguese and Dutch. `--compare before.md after.md` lists the numbers, versions, dates, links, quotations, code spans and names that a rewrite lost or added. The French pack has one provisional rule, `fr/closer`; Spanish and German ship no rule. The vocabulary rules are English word lists.
- Measured, not asserted: on `bench/corpus`, five public-domain texts written before any language model grade A or B and five pieces of model output grade F. The numbers are rates, not detection accuracy, and the tool never emits a probability.