readcost
readcost finds the sentences in your docs, or in a model's answer, whose construction slows readers down: three or more nouns in a row, a subject far from its verb, a thing doing a person's action, and a few more. For each one it quotes the line, marks the words, and says how to rewrite it.
For example, this sentence from a README:
For store restart measurement, the example prints first snapshot-query cost
with persisted WAND sidecars present versus after deleting those sidecars and
forcing source-segment rebuilds.
warn[stacked-nouns]: three or more nouns in a row
--> notes.md:1:5
|
1 | For store restart measurement, the example prints first snapshot-query cost
| ^^^^^^^^^^^^^^^^^^^^^^^^^ 3 nouns stacked
|
= why: Readers must work out how the nouns group before they can read on, and
the grouping is often ambiguous (Squad Helps Dog Bite Victim).
= help: Keep at most two nouns together. Unpack the rest with a preposition or
a relative clause.
= example: 'forcing source segment rebuilds' -> 'forcing each segment to be
rebuilt from its source'
warn[hyphen-compound]: ad hoc hyphenated noun compound
--> notes.md:3:9
|
3 | forcing source-segment rebuilds.
| ^^^^^^^^^^^^^^^^^^^^^^^ coined compound modifier
|
= why: Coined compounds such as storage-shrink or region-index are rare word
pairs, which the paper links to slower reading.
= help: Write the relationship out.
= example: 'the storage-shrink use case' -> 'the main use: storing ID sets in
less space'
notes.md: advise
2 findings in 1 sentence (26 words), cost index 76.9 per 1,000 words
predicted reading time 7 s, 301 ms per word
More on a rule: readcost explain stacked-nouns
Wrong finding? https://github.com/arclabs561/readcost/issues/new/choose
The rewrite that README adopted keeps every fact and passes:
To measure a store restart, the example reopens a checkpointed store and
prints the duration of its first snapshot query. It does this twice: once
with the persisted WAND sidecars present, and once after deleting those
sidecars, which forces each segment to be rebuilt from its source vectors.
uvx readcost check README.md
The constructions come from "Why is AI-generated language so hard to understand?" (arXiv 2610.29162), which finds that recent language models use them more than people do; earlier reading studies tie each of them to slower reading.
Scope
readcost is for English technical prose: READMEs, documentation, commit messages, doc comments, and text a model writes before you or your users read it. It reports:
- sentences built in a way that costs readers time, with the words marked and a suggested rewrite;
- a verdict per file (pass, advise, block) for CI and hooks;
- a predicted reading time per file, from a model fitted to eye-tracking data.
It does not check grammar, spelling or terminology, enforce a style guide, judge whether text is correct, complete or up to date (which developers rate as the worst documentation failures), or tell who wrote a text.
How it differs
| Tool | Checks | How |
|---|---|---|
| readcost | Sentence constructions tied to slower reading; reading time | A dependency parse of each sentence; a model fitted to eye-tracking data |
| Vale | Your style guide: terms, phrases, capitalization | Rules you write: patterns, word lists, part-of-speech sequences |
| proselint | Usage advice gathered from authors and editors | Built-in checks |
| write-good | Passive voice, weasel words, wordy phrases | Word patterns |
| LanguageTool | Grammar, spelling, punctuation | Grammar rules and models |
| Readability formulas (Flesch-Kincaid) | A grade for a whole text | Word and sentence length |
Vale's part-of-speech rules can match a run of nouns, but Vale, proselint and write-good do not parse which word depends on which, so they cannot measure the distance from a subject to its verb or find an object relative without "that". readcost works next to Vale rather than instead of it. A readability formula tracks how hard a whole text is better than readcost's cost index does (see docs/evaluation.md); readcost's job is to say which sentence to change.
Status: experimental; before 1.0, output and configuration can change between minor versions. docs/research.md has the evidence behind each choice and the roadmap.
Install
uvx readcost check README.md # run without installing
pip install readcost # or install it
Python 3.11 or later. The dependencies are spaCy and markdown-it-py. On first
use readcost downloads spaCy's English model (about 13 MB, checksum verified)
into ~/.cache/readcost; no pip is needed, so it also works under uvx.
readcost setup does the download ahead of time. Set READCOST_NO_DOWNLOAD=1
to forbid it, for example on an offline machine with the model installed as a
package.
Use
readcost check README.md docs/
readcost check --lines 40-80 README.md # only sentences touching these lines; 40- runs to the end
some-model-cli "explain X" | readcost check - # model output on stdin
readcost check --format transcript --last session.jsonl
readcost check --format jsonl --field response --per-record evals.jsonl
readcost check src/lib.rs # doc comments; --format source
readcost explain stacked-nouns
The default output, in the style of the Rust compiler, names the rule, quotes
the line with carets under the words and a label saying what is wrong, and
gives the fix. The first finding of each rule also says why it costs the reader
and shows an example rewrite. Lines stay within 80 columns.
Colour is on in a terminal unless NO_COLOR is set (--color overrides).
-o concise prints one path:line:col line per finding, for editors and grep.
-o json, -o sarif and -o github are for tools, -o agent is short
feedback written for a model, and -o pr-comment is the Markdown summary that
the GitHub Action posts on a pull request. The exit status is
1 when a file reaches the --fail-on verdict (default block), 2 on an error,
and 0 otherwise.
From Python:
from readcost import check_text
result = check_text(answer, fmt="markdown")
if result.verdict != "pass":
for f in result.findings:
print(f.line, f.feature, f.message, f.suggestion)
What it flags
Each example below is a real sentence from a public README, except where the last column says otherwise; each rewrite keeps every fact and passes.
| Feature | Example | Rewrite | Source |
|---|---|---|---|
| stacked-nouns | For store restart measurement, the example prints first snapshot-query cost with persisted WAND sidecars present versus after deleting those sidecars and forcing source-segment rebuilds. | To measure a store restart, the example prints the cost of the first snapshot query twice: with the persisted WAND sidecars present, and after deleting them, which forces each segment to be rebuilt from its source. | a README this rewrite was adopted in |
| long-dependency | Comparisons keep the declared artifact-digest relation and packet-shape evidence as separate claims. | Comparisons keep two claims separate: the relation that the artifact digests declare, and the evidence from packet shapes. | linktop |
| inanimate-subject | It does not decide how text should be split; it records the chosen span. | The caller decides how to split the text; slabs records the span it chose. | slabs |
| reduced-object-relative | compressed_postings compresses an inverted-index posting list with cnk, the storage-shrink use case these ID-set codecs exist for. |
compressed_postings uses cnk to compress the posting list of an inverted index. Storing ID sets in less space is what these codecs are for. |
cnk |
| hyphen-compound | The missing-pattern check in gitignore_audit is a pattern-presence heuristic. |
The missing-pattern check in gitignore_audit only looks for whether a pattern is present. |
devguard |
| inline-list | durability provides filesystem and in-memory directories, atomic writes, WALs, record logs, checkpoint files, CRC validation, and sync helpers. |
a bulleted list | durability |
| participial-clause (opt-in) | The page updates automatically when the file changes on disk, highlighting what changed. | The page updates automatically when the file changes on disk and highlights what changed. | mdpreview |
| denominal-verb (opt-in) | The script will bucket the requests by hour. | The script will group the requests by hour. | constructed: every hit in the sample was wrong |
| nominalization (opt-in) | The tool performs validation of the input. | The tool validates the input. | constructed: no hit in the sample |
| repeated-frame (opt-in) | This change reduces the latency of the cache. This change improves the speed of the parser. This change lowers the cost of the build. | This change makes the cache faster, the parser quicker and the build cheaper. | constructed: no hit in the sample |
The first five come from the paper; denominal-verb is opt-in because on
well-edited prose nearly all its hits were settled verbs. The next two are
rules derived from where those constructions show up in technical writing. A
hyphenated word counts as one noun, so "storage-shrink job" is a hyphen
compound, not three stacked nouns. The other opt-in three are constructions
that language models use more often than people (Reinhart et al. 2025; Shaib
et al. 2024). Turn any opt-in rule on with --enable. long-sentence is also
available but off by default. readcost explain prints why each one costs the
reader and how to fix it. When a long-dependency or inline-list
sentence gives a reason (because, since, so that, otherwise), the suggestion
says to keep that reason when splitting the sentence.
Technical writing repeats compressed terms on purpose, so a stacked or
hyphenated compound is reported once per document, at its first use. An
identifier as a subject (`parse()` returns) is not reported as an
inanimate subject. Code spans, URLs and file paths count as single words.
More real output, from READMEs in the author's public repositories
Checked with the default settings; scripts/readme_gallery.py regenerates
this from pinned commits.
warn[stacked-nouns]: three or more nouns in a row
--> cnk/README.md:61:48
|
61 | ...presses an inverted-index posting list with cnk, the storage-shrink u...
| ^^^^^^^^^^^^^^^^^^ 3 nouns stacked
|
= why: Readers must work out how the nouns group before they can read on, and
the grouping is often ambiguous (Squad Helps Dog Bite Victim).
= help: Keep at most two nouns together. Unpack the rest with a preposition
or a relative clause.
= example: 'forcing source segment rebuilds' -> 'forcing each segment to be
rebuilt from its source'
warn[hyphen-compound]: ad hoc hyphenated noun compound
--> cnk/README.md:61:81
|
61 | ... list with cnk, the storage-shrink use case these ID-set codecs exist...
| ^^^^^^^^^^^^^^^^^^^^^^^ coined compound modifier
|
= why: Coined compounds such as storage-shrink or region-index are rare word
pairs, which the paper links to slower reading.
= help: Write the relationship out.
= example: 'the storage-shrink use case' -> 'the main use: storing ID sets in
less space'
info[reduced-object-relative]: object relative clause without 'that'
--> cnk/README.md:61:100
|
61 | ... with cnk, the storage-shrink use case these ID-set codecs exist for.
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
| object relative without 'that'
|
= why: Object relatives (the house the contractors built) cost more to read
than subject relatives; dropping the optional 'that' removes the cue
that one has started.
= help: Keep the 'that', or turn it into a subject relative or a separate
sentence.
= example: 'the format the reader expects' -> 'the format that the reader
expects'
warn[long-dependency]: related words far apart
--> cnk/README.md:48:1
|
48 | is an experimental rANS-backed sorted-set codec behind the `ans` feat...
| ^^-------------------------------------------------------------------
49 | is not selected by the default chooser.
| -------^^^^^^^^ 'is' and 'selected' are 15 words apart
|
= why: A subject far from its verb, or a verb far from its object, has to be
held in working memory.
= help: Put the subject next to its verb. Move long modifiers after the verb
or into a second sentence.
= example: 'The index, built once from all documents and rebuilt only on
compaction, serves queries.' -> 'The index serves queries. It is
built once and rebuilt only on compaction.'
info[inanimate-subject]: thing doing a person's action
--> lexir/README.md:7:60
|
7 | ...ranks caller-provided token streams. Its in-memory index owns postings
| ^^^^^-^^^^
| a person's verb with a non-person subject
|
= why: Verbs such as own, decide, promise, claim, hide or swallow normally
take a person as subject.
= help: Make the person the subject, or state the fact directly: what is out
of scope, what is returned, what is not guaranteed.
= example: 'It does not own indexing or compaction.' -> 'Indexing and
compaction are left to the caller.'
info[inline-list]: long list inside a sentence
--> durability/README.md:8:68
|
8 | ...y` provides filesystem and in-memory directories, atomic writes, WALs,
| ^^^^^^^^^^^^^
9 | record logs, checkpoint files, CRC validation, and sync helpers.
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
| 6 items listed in one sentence
|
= why: Four or more coordinated items, or items joined by slashes, stretch the
sentence's dependencies and are hard to scan.
= help: Use a bulleted list.
= example: 'It supports standard/Sugeno/Yager negations, OWA, power means, and
uninorms.' -> a bulleted list
Not every finding is right: see Limits and Reporting a false positive.
Verdicts
Each finding counts 0.5 (info), 1 (warn) or 2 (error). The cost index is that count per 1,000 words. A file passes below 15, gets "advise" at 15 or more, and gets "block" at 30 or more with at least 3 weighted findings. Of 110 essays, documentation pages and READMEs by well-regarded writers (150 words or more, held out from the reference profile), 107 pass and 3 get "advise"; the median cost index is 3.2 (measured 2026-10-26).
Commit messages (--format commit, the commit-msg hook) are judged against
their own thresholds, 50 and 100, because they are terser than prose: in 1,000
Go commit messages the 99th percentile cost index is 49, against 8 to 16 for
essays, docs, READMEs and discussion. Benchmark tables, shell commands and the
pkg/path: scope prefix of the subject line are not read as prose.
A rate is noisy for a short text: one finding in a 20-word comment is 50 per 1,000 words. Below 40 words, readcost counts weighted findings instead: 2 or more gets "advise" and 3 or more gets "block".
Dependency length is judged against a reference profile: how far apart
related words usually are, by sentence length, in a swatch of essays,
documentation and READMEs by well-regarded writers (126 texts from 22 sources,
listed in src/readcost/data/default_profile.json). To compare against
writing that you prefer, build your own:
readcost profile build path/to/good/*.md -o myprofile.json --name mine
readcost check --profile myprofile.json README.md
Predicted reading time
Each whole-document check also reports a predicted reading time, for example
predicted reading time 211 s (222 ms per word), and the JSON output has
reading_seconds and reading_ms_per_word. A small tree model predicts how
long readers look at each word from its length, its frequency and its
neighbours. It was fitted to eye-tracking data from 360 native English readers
of newspaper paragraphs (OneStop) and takes about 15 ms for 1,000 words.
On held-out paragraphs its error is about 19 ms per word against a mean of about 200 (OneStop), and 10 ms on a separate corpus (Provo). Always predicting the average would score 22 and 17, so treat it as a document-level estimate, useful for comparing two versions of the same text, not as a judgement of one sentence. When ten models from different labs each rewrote the same 53 paragraphs, every one raised the predicted time per word (by 2 to 19 ms); readcost's findings did not tell the rewrites apart. The number does not affect the verdict. Code spans are left out. See docs/evaluation.md for how it was built and tested.
Configuration
Put a readcost.toml at the repository root, or a [tool.readcost] table in
pyproject.toml. readcost.toml.example lists every key with its default. The
useful ones:
allow: phrases never flagged, such as product names or terms of art.disableandenable: turn features off or on.advise_severity: the verdict is at leastadvisewhen any finding reaches this severity;offturns that rule off.profile: a relative path is read from the config file's directory.hooks.mode:off,adviseorblock.feedback_link:falsedrops the line that text and agent output end with, which points to the false-positive form.
readcost warns about unknown keys and stops with exit code 2 on a value of the wrong type or outside its choices, naming the file and the key.
To skip text, put <!-- readcost: ignore --> before a paragraph, or wrap a
section in <!-- readcost: off --> and <!-- readcost: on -->. Name rules to
turn off only those: <!-- readcost: ignore stacked-nouns --> keeps every
other rule on for the next block, and <!-- readcost: off inline-list -->
lasts until <!-- readcost: on inline-list --> or a bare readcost: on. A
misspelled rule name is reported in the file's notes.
Adopting readcost in an existing repo
Old docs can fail the check before anyone edits them. Record their findings once, commit the file, and point the config at it:
readcost baseline README.md docs # writes .readcost-baseline.json
echo 'baseline = ".readcost-baseline.json"' >> readcost.toml
From then on readcost check and the hooks report only findings that are not
in the baseline, and the verdict and exit status count only those. The text
summary says how many findings the baseline hid, and the JSON output has a
baselined count per file. readcost check --baseline FILE does the same
without the config key.
A finding is matched by its file, its feature and a hash of its sentence, not
by line number, so edits elsewhere in a file do not make old findings new.
A sentence that is reworded but still flagged counts as new, and so does a
second copy of a baselined sentence. The file holds hashes only, sorted one entry per
line, and paths relative to its own directory, so keep it at the repository
root. Run readcost baseline again after a cleanup to shrink it.
Hooks
docs/hooks.md describes each adapter, what it sends back, and the rules that
they share: advisory by default, only edited lines, fail open, at most one revision
per turn. In short:
- Claude Code:
integrations/claude-code-plugin/, or the settings snippet inintegrations/claude-code/. - piku:
integrations/piku/hooks.json. - git:
.pre-commit-hooks.yaml, or the scripts inintegrations/git/. - GitHub Actions:
action.yml; see the next section. - Anything else:
readcost hook genericreads JSON on stdin and writes JSON.
GitHub Action
The action annotates the lines it flags. On a pull request it checks only the
Markdown, reStructuredText and text files that the pull request adds or
changes; set changed-only: "false" to check every file under paths. With
comment: "true" it also posts one summary comment on the pull request and
edits that comment on later runs, so the thread gets one comment, not one
per push. The comment counts the verdicts, lists the worst findings in a
table, and gives the predicted reading time.
name: readcost
on: pull_request
permissions:
contents: read
pull-requests: write # only needed for comment: "true"
jobs:
prose:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
with:
fetch-depth: 0 # lets the action diff against the merge base
- uses: arclabs561/readcost@main # pin a commit SHA in real use
with:
paths: README.md docs
fail-on: block
comment: "true"
Inputs:
paths: files or directories, separated by spaces or newlines (default.).fail-on:never,adviseorblock(defaultblock).comment:"true"to post the summary comment (default"false").changed-only: on a pull request, check only changed files (default"true").
Without fetch-depth: 0 the action fetches the base commit itself and
compares it with the checked-out commit; that list can include files that
changed on the base branch after the pull request was opened. A pull request
from a fork gets a read-only token, so the comment fails with a warning and the
annotations still appear.
Reporting a false positive
readcost is advisory, and many findings are wrong (see Limits). When one is,
open an issue with the
false positive form:
it asks for the rule, the message, the sentence, where the sentence was, and
why the finding is wrong. Text and agent output end with a line that links to
the form when there are findings; feedback_link = false in readcost.toml
turns that line off. The hooks never add it, since a model cannot act on it.
Editors
readcost lsp is a language server, so findings show up as diagnostics in
VS Code, Neovim, Helix and other editors with a generic LSP client. Install it
with pip install 'readcost[lsp]'.
docs/editors.md has the
setup for each editor.
Limits
- readcost is not an AI-text detector. Construction rates and reading-time estimates must not be used to judge who wrote a text: the same patterns appear in human writing, and treating them as markers penalizes non-native English writers in particular.
- English only.
- The default spaCy model misparses some sentences. A sentence parsed with no
verb is skipped, and a misparse can produce a false finding. Set
model = "en_core_web_trf"for better parses at several times the cost. - inanimate-subject and denominal-verb use word lists derived from WordNet. Treat their findings as prompts to reread, not verdicts.
- Precision is low on well-edited prose. Ten model raters from different labs
labelled 210 findings sampled from essays and documentation by well-regarded
writers. Of the 74 that the current rules still report, a majority of eight
raters judged 15 (20%) correct or defensible (single raters: 14 to 42%; two
lenient raters: 72%). Agreement between raters is modest (Fleiss' kappa 0.40
over the eight).
readcost explain RULEshows the count for each rule. See docs/evaluation.md. - hyphen-compound skips pairs found in 5+ documents of a 2019 FineWeb-Edu
crawl (ODC-By; see
src/readcost/data/FINEWEB_NOTICE). - The paper's findings are about how often text uses these constructions, not about any single sentence, and it ran no reading study on model text.
- The paper also measures rare word pairs. readcost uses word-pair counts only to skip hyphenated pairs in common use; it does not flag rare pairs in general yet.
- The default profile is edited English technical and essay prose. A cost index for chat answers is not comparable to one for READMEs.
Development
pip install -e '.[test]' && python3 -m pytest
readcost check . --fail-on block # CI runs readcost on its own repo
python3 scripts/build_lexicon.py # needs nltk and its WordNet data
python3 scripts/build_default_profile.py ref/eval # needs scripts/fetch_eval_corpus.py first
License
MIT or Apache-2.0, at your option. src/readcost/data/lexicon.json.gz is
derived from Princeton WordNet 3.0; its license is in
src/readcost/data/WORDNET_LICENSE.
Metadata
Release files for readcost 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| readcost-0.2.0.tar.gz | 2.6 MB | With provenance | Details for readcost-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| readcost-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for readcost-0.2.0-py3-none-any.whl |
Total release size: 5.2 MB
Release files / readcost-0.2.0.tar.gz
| Download URL | readcost-0.2.0.tar.gz |
|---|---|
| Size | 2.6 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b422e3cb3a9dfc35b6478b5eefd0abae0f2aca7ff024ca5accb4913e5bcd0dae
|
|
BLAKE2b-256 checksum How to use checksums |
8f784db499e0ca40e321dd5660646b9067e7d6128fb3ca93130f7b6c0a1e190f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.13
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.
Transparency logRelease files / readcost-0.2.0-py3-none-any.whl
| Download URL | readcost-0.2.0-py3-none-any.whl |
|---|---|
| Size | 2.6 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b9b5a59da455389905d8431d7ca8bd200738e0fb8247dc75525888c7e7d2aca1
|
|
BLAKE2b-256 checksum How to use checksums |
d2067716c7ad3bf9eea01dd811da3e1d09ed65ca2eb631ae44764a310d0776fd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.13
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.
Transparency logSecurity for readcost 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for readcost-0.2.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.