riff
Ruff-style prose linter whose semantic rules each ask Jev a yes/no question about a paragraph, title or section, with tunable thresholds.
Overview
riff is a small, fast prose linter that reports writing tells and clarity problems with ruff-style rule codes you can select, ignore and configure. Static rules (for example Title Case headings) are pure Python and run in milliseconds. Semantic rules are one Noul question to Jev each, asked about the right unit of the document: a paragraph for filler phrases or announcing what is about to be said, a slide title for whether it states a claim, a section for whether its body delivers its title, and the whole outline for whether a deck's titles tell its argument.
Each Jev finding prints its probability (p=0.92) and you set a per-rule threshold. The README's example run made 14 Jev calls for about $0.0004. It lints Markdown, text, docx, pptx and web pages, and can classify the document type first. Jev is the default but any calibrated decision model can be used; thresholds are tuned to Jev, so other models need re-tuning with --debug-jev. --no-jev runs static rules without a key. It is not yet on PyPI.
What the decision model decides
| Type | Question | Answers |
|---|---|---|
| Yes / no | Does this paragraph announce what it is about to say instead of saying it? | — |
| Yes / no | Does this paragraph use overused AI filler vocabulary as filler? | — |
| Yes / no | Does this slide title state a claim? | — |
| Choice | What type of document is this (e.g. email)? | — |
How it works
- Parse the document into paragraphs, titles and sections
- Run static rules locally
- Ask Jev one Noul per semantic rule per unit
- Report findings above each rule's threshold with p values and rule codes
Strengths
- Cheap: about $0.0004 for 14 calls in the README example
- Probabilities shown for tuning
- Works offline with --no-jev for static rules
Caveats
- Not on PyPI yet; install from source
- Document text is sent to the model provider
- Thresholds tuned to Jev only
Getting started
uv tool install git+https://github.com/scale-venture-partners/riff, set TYPESAFE_API_KEY, then riff draft.md.At a glance
- Type
- Project
- Status
- beta
- Language
- Python
- Runtime
- CLI
- Has code
- yes
- Has tests
- yes
- License
- MIT
Use cases and integrations
How curated lists describe it
A small, fast prose linter: ruff-style rule codes for writing, backed by TypeSafe's Jev model.
hellogumbo/awesome-jev
Frequently asked questions
What does Jev decide in riff?
Whether each paragraph, title or section shows a specific writing problem, as a yes/no probability.
Can I use it without a key?
Yes, --no-jev runs the static rules only.
Can I use another model?
Yes, any calibrated decision model, but you should re-tune thresholds with --debug-jev.
Related projects
Node tool that crosschecks a folder of Markdown notes for contradictions and repeats, and ranks notes by any question, using Jev.
ProjectbetaJavaScriptProse linter for AI writing tells: regex handles 18, Jev judges 15 as Nouls in one call, shipped as a Claude Code Stop hook.
HookbetaPythonProse linter with local regex rules and Jev judgment rules per paragraph, as CLI, pre-commit hook, GitHub Action and Claude Code skill.
CLIbetaTypeScriptCLI design and copy linter: mechanical checks block commits, while fuzzy taste checks go to Jev for probability-scored review notes.
CLIbetaTypeScriptChinese controlled-writing agent skill for technical reports with nine rules, using static checks plus a Jev semantic gate for certainty.
Agent skillbetaDependency-light Go linter that applies natural-language rules to code and documents using decision models like Jev or Clef.
ProjectprototypeGo