Skip to main content

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.
  • disable and enable: turn features off or on.
  • advise_severity: the verdict is at least advise when any finding reaches this severity; off turns that rule off.
  • profile: a relative path is read from the config file's directory.
  • hooks.mode: off, advise or block.
  • feedback_link: false drops 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 in integrations/claude-code/.
  • piku: integrations/piku/hooks.json.
  • git: .pre-commit-hooks.yaml, or the scripts in integrations/git/.
  • GitHub Actions: action.yml; see the next section.
  • Anything else: readcost hook generic reads 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, advise or block (default block).
  • 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 RULE shows 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)

Source distribution for readcost 0.2.0
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)

Table of built distributions (wheels) for readcost 0.2.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

0.2.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page