Ban the words and you have fixed a third of the problem.
clearmode checks the other two thirds: can an outsider follow it, and does it say anything.
clearmode: an anti-AI-slop writing standard and plain-language checker for Claude Code, Cursor, Codex and Vale
CLEAR-100 scores any text 0 to 100 against 43 rules, then names the line that loses the reader.
Four axes, one number. Plain: can an outsider read it once and get it. Human: does it read like a person who did the work. Structured: does the page shape match the information shape. Dense: does every sentence carry something unguessable.
One rule pack, 18 targets.
Claude Code skill. AGENTS.md block. Cursor rule. Vale style. System prompt.
All generated from one JSON file, so they never drift apart.
Zero install. Python 3.10 and the standard library. No pip, no npm, no API key, no network call, no telemetry.
Quickstart → ·
Install ·
The axes ·
All 43 rules ·
Compare ·
FAQ
Real session, real output. Every finding names the rule, the file and the line, and says what to write instead.
If this looks useful, star the repo. It is how other people find it.
Aerospace solved ambiguity in 1986. ASD-STE100 gave maintenance manuals 53 rules and about 900 approved words, because a mechanic under a wing cannot ask the author a follow-up question. It works. It also bans contractions, so it reads like a machine, on purpose.
Two things changed since. Models draft the text now, so the failure mode moved from ambiguity to filler that scans as competent. And the reader sits outside the field, on a phone, deciding in one screen.
clearmode keeps that discipline and adds the 3 axes STE never needed.
| Axis | What it asks | Weight |
|---|---|---|
| Plain | Can someone outside the field read it once and get it? | 30% |
| Human | Does it read like a person who did the work? | 30% |
| Structured | Does the shape of the page match the shape of the information? | 25% |
| Dense | Does every sentence carry something a reader could not guess? | 15% |
git clone https://github.com/eugeniughelbur/clearmode.git
cd clearmode
python3 scripts/clearcheck.py tests/fixtures/bad.mdNo pip, no npm, no config. Python 3.10 and the standard library.
Real output on the two fixtures in this repo:
tests/fixtures/bad.md CLEAR 41.4/100 band F this reads like a model wrote it
Plain 41.5 Human 0 Struc 90.0 Dense 43.0
24 error, 23 warn, 6 review
tests/fixtures/good.md CLEAR 98.0/100 band A ready to publish
Plain 97.0 Human 100.0 Struc 100.0 Dense 92.5
0 error, 1 warn, 1 review
All 18 files below compile from rules/clear-100.json, so they never drift apart.
Fastest path: ./install.sh detects what you have and writes only between markers, so running it twice changes nothing.
./install.sh --dry-run # show what it would touch
./install.sh # do it
./install.sh --hook # and govern Claude's replies to you, not just your filesOr install one surface by hand.
clearmode is a Claude Code skill. Copy the skill and its references, then restart Claude Code.
mkdir -p ~/.claude/skills/clearmode
cp -r SKILL.md references rules scripts ~/.claude/skills/clearmode/Four slash commands come with it: /clear-check, /clear-rewrite, /clear-init, /clear-explain.
Everything above tells the agent how to write. These two make sure it did.
./install.sh --hookcheck_reply.py scores every finished reply. It ships in MODE = "watch": it writes what it caught to the log and stays quiet.
Set MODE = "block" and it sends the reply back to be rewritten. That works, but the first version is already on screen, so the reader gets the draft and then the fix. Two messages for one answer. Watch first, read the log for a week, and switch to block only if the rules alone are not holding.
check_outgoing.py scores text on its way out: a Slack message, an email, a Linear comment, a markdown file. Those reach other people, so the tool call is blocked and retried until the text is clean. Nothing wrong ever leaves.
You never see a score. You stop reading jargon.
Watch what it does:
tail -f ~/.claude/hooks/clearmode/log.txtOne line per reply: pass, BLOCK with the rules it caught, or skip for anything under 40 words.
15 of the 43 rules are watched in chat. 10 hard-block outgoing text, where a retry is invisible. The rest stay advisory, because a chat turn is a different contract from a document, and a judgement-call rule that fires on good writing is worse than no rule. A block shows the reader the draft and the rewrite, so every catch costs a double message. That is why the list is short. It is BLOCK_ON at the top of hooks/check_reply.py, one commented line per rule.
It edits ~/.claude/settings.json and backs it up first. Restart Claude Code after. To switch it off:
python3 scripts/register_hook.py --removeCodex reads AGENTS.md from the repo root.
cp targets/codex/AGENTS.md ./AGENTS.mdAGENTS.md is the cross-tool standard most agents now read. Paste the block into an existing file instead of overwriting it.
cat targets/agents-md-snippet.md >> AGENTS.mdCursor also supports native project rules in .mdc format.
mkdir -p .cursor/rules && cp targets/cursor/clearmode.mdc .cursor/rules/Paste targets/grok/custom-instructions.txt into the custom instructions box. For an API call, use targets/system-prompt.txt as the system prompt.
clearmode ships a Vale style package, so a prose linter you already run in CI can enforce the same rules.
cp -r targets/vale/ClearMode /path/to/your/styles/targets/vale/.vale.ini shows the config.
rules/clear-100.json holds every rule, threshold, and word list. The checker reads it. Every target above is generated from it.
python3 scripts/compile_targets.py # rebuild all 18 targets
python3 scripts/compile_targets.py --check # fail if any target is staleDisagree with a rule? Change the JSON and recompile. Nobody hand-edits a target.
One standard, four reader models.
| Setting | general | technical | social | agent |
|---|---|---|---|---|
| Sentence cap | 25 | 28 | 20 | 20 |
| Sentences per paragraph | 4 | 5 | 2 | 6 |
| Reading grade target | 9 | 11 | 8 | 9 |
python3 scripts/clearcheck.py post.md --profile socialpython3 scripts/clearcheck.py docs/*.md --gate 80 # exits 1 below 80
python3 scripts/clearcheck.py README.md --json # machine-readable
python3 scripts/clearcheck.py post.md --strict # any finding failsA ready workflow sits in .github/workflows/clear.yml.
| Command | What it does |
|---|---|
/clear-check |
Score and report. Changes nothing. |
/clear-rewrite |
Rewrite in five ordered passes until it clears the gate. |
/clear-init |
Wire the standard into this repo's agent files and CI. |
/clear-explain |
Explain one rule, or defend it. |
Feature comparison against the tools people reach for first. Checked 2026-08-28.
| clearmode | anti-ai-slop-writing | the-antislop | ASD-STE100 skills | Vale | |
|---|---|---|---|---|---|
| Bans slop vocabulary | yes | yes, 130+ patterns | yes, 35+ in 3 tiers | no | only if you write the rules |
| Glosses jargon for outsiders | yes, 79 terms | no | no | no | no |
| Checks page structure | yes | partly | no | partly | no |
| Measures information density | yes | no | no | no | no |
| Keeps contractions | yes | yes | yes | no, bans them | n/a |
| Numeric score | yes, 0-100 on 4 axes | no | yes, risk tiers | no | no |
| Deterministic checker | yes, stdlib only | prompt-only | prompt-only | some | yes, needs a style pack |
| Reading grade per audience | yes, 4 profiles | no | no | one audience | configurable |
| One source compiled to every tool | yes, 18 targets | no, one SKILL.md | no | no | n/a |
| Install size | zero deps | zero deps | zero deps | zero deps | binary |
Short version. The word-list tools fix vocabulary. Vale gives you an engine and no opinion. STE fixes ambiguity for a mechanic, not readability for an outsider. clearmode is the only one that scores all four at once and ships the same rules to every agent you use.
Low-quality AI-generated text. The 2026 arXiv paper that first defined it found readers judge slop through latent dimensions like coherence and relevance, not through a word list alone. That is why clearmode scores density and structure, not just vocabulary.
Run python3 scripts/clearcheck.py yourfile.md. Anything under 70 reads like a model wrote it. The report names the exact line and rule.
No. It measures readability, not authorship. A human can write a 41. A model can write a 95.
Yes. targets/ holds a prebuilt file for each. Copy one file, or run ./install.sh.
A word list catches delve and stops. clearmode also asks whether a non-specialist can follow the sentence, whether the page has a shape, and whether the sentence says anything the reader could not guess.
Simplified Technical English solved ambiguity for aerospace manuals in 1986 and still works. It also bans contractions and reads robotic, has no concept of AI slop, and assumes a trained technician as the reader.
Grade 9 or lower for a general audience, 11 for technical docs, 8 for social. The profiles set this for you.
Yes. Edit rules/clear-100.json, then run python3 scripts/compile_targets.py. Never hand-edit a generated target.
Yes. Python 3.10 and the standard library. No API key, no network call, no telemetry.
- It cannot tell you a claim is true. Wrong and clear is still wrong.
- It will not strip a technical term that is the subject. It glosses it once.
- It is not a compliance claim against ASD-STE100. That dictionary is ASD's copyright and is not reproduced here.
- It is not an AI detector. It measures readability, not authorship.
- ASD-STE100 Simplified Technical English, the 53 rules and the one-meaning-per-word discipline
- Wikipedia: Signs of AI writing, the deepest catalogue of tells anyone maintains
- Measuring AI Slop in Text, Shaib et al., which found readers react to information density more than to any word list
- plainlanguage.gov and GOV.UK content design, for the plain-word tables and the evidence that high-literacy readers prefer plain English too
- Vale, whose style format
targets/vale/speaks
The standard is above. This is the rest of the workbench.
obsidian-second-brain
Persistent memory for Claude Code and 6 other CLI agents, stored as plain markdown in your Obsidian vault. 45 commands.
doceo
A personal AI tutor as a skill. Turns any topic, file, folder or URL into a one-screen visual lesson.
From the blog · The AI Operator →
One post per Tuesday on AI agents, second-brain systems, and bringing AI into real work.
If you write about clearmode or use it in research, CITATION.cff has the metadata. GitHub renders a ready citation from the sidebar.
Rules are arguments. If a rule is wrong, open an issue with a sentence it flags that should pass, or a sentence it misses that should fail. That is the most useful bug report this repo can get.
Change rules/clear-100.json, run python3 scripts/compile_targets.py, run the tests, open a pull request. Never hand-edit a file under targets/.
python3 -m unittest discover tests -v
python3 scripts/compile_targets.py --checkMIT. See LICENSE.