linnl

linnl is a text linter aimed to catch LLM tells and reduce the complexity of the text produced by them, so that the cognitive load on the reader is reduced and ideas are clearer.

Some built-in rules are checked in code, others (most) are judged by an LLM. You can also install linnl plugins to provide your own set of rules.

Install

uv tool install linnl

Claude as a judge

You will either need a working claude login or an ANTHROPIC_API_KEY set in your environment.

Codex as a judge

Codex reuses the local Codex session. You can also set OPENAI_API_KEY.

Use

In Claude Code or Codex

linnl install-to-agent claude
linnl install-to-agent codex

Then run /linnl in your chat.

CLI

linnl lint notes.md
linnl lint docs/
echo "text" | linnl lint

Example output:

notes.md
=========
line 3:
    > No config. No cron. No surprises.
SCH003 Three successive fragments open with the same word for emphasis, which is anaphora.

line 5:
    > Set it up once; forget about it.
CHR004 Semicolon.

Found 2 violations across 1 file.

Configure

CLI

Check

linnl lint --help

To see available quick configuration options.

File configuration

The priority is:

• The closest pyproject.toml with a tool.linnl section
• A linnl.toml file next to the closest pyproject.toml
• ~/.config/linnl/config.toml
• The config file shipped with the tool

You can easily create a linnl.toml with:

linnl config > linnl.toml

Adding your own rules

Add groups under [rules.<PREFIX>] in your config file. description is the only reserved key. Every other key is a rule:

extend-select = ["SEC"]

[rules.SEC]
description = "Wording that must not leak infrastructure details"
001 = "Names an internal host, IP or path"
abc = "Shows a credential or token in an example"

That defines SEC001 and SECabc, judged by the model. linnl shows the group description to the model above its rules, so make it say what the group is for.

The reserved RGX group defines regular expression rules. Every value under [rules.RGX] is compiled as a Python regular expression and is enabled by default:

[rules.RGX]
description = "Patterns to avoid"
001 = "X is not (.*), it's (.*)"

Each non-overlapping match is reported separately, with the full match as the quoted text. Invalid regular expressions fail configuration.

If the rule requires configurable parameters:

extend-select = ["SEC"]

[rules.SEC]
description = "Wording that must not leak infrastructure details"
001 = "Names an internal host, IP or path"
abc = "Shows a credential or token in an example"

[rules.SEC.xyz]
description = "Do now show more {n_files} files in the current directory"
n-files = 3

A description can name the rule's options in braces. Write an option name with underscores, so max-sentences becomes {max_sentences} and "More than {max_sentences} sentences." renders with the configured value. Options work on Python and model rules. linnl renders their values before sending model rules to the judge.

Installing rules plugins

Install them alongside linnl:

uv tool install linnl --with linnl-acme-rules

Then enable their linnl.plugins entry-point names.

plugins = ["acme-rules"]
extend-select = ["ACM"]

The package contributes default sections under [rules]. Your configuration can select, ignore, and override those rules in the same way as built-in rules.

linnl plugins lists the rule packages enabled by the active configuration.

To author a package, declare an entry point that names a linnl.plugins.Plugin subclass:

[project.entry-points."linnl.plugins"]
acme-rules = "linnl_acme_rules:AcmePlugin"

from typing import ClassVar

from linnl.document import Document
from linnl.plugins import Plugin
from linnl.rules import CodeRule
from linnl.rules.pattern_rules import TextPatternRule
from linnl.violations import Violation, Violations


class Acme001(TextPatternRule, identifier="ACM001"):
    """Flag obviously.

    Example: "This is obviously correct."
    """

    pattern = r"\bobviously\b"


class Acme002(CodeRule, identifier="ACM002"):
    """Flag lines longer than 80 characters.

    Example: "This line has more than eighty characters and should be shortened before it is committed."
    """

    def __call__(self, document: Document) -> Violations:
        violations = []

        for line_number, line in enumerate(document.lines, start=1):
            if len(line) > 80:
                violations.append(
                    Violation(
                        rule=self,
                        path=document.path,
                        line=line_number,
                        offset=81,
                        quote=line,
                    )
                )

        return Violations(violations)


class AcmePlugin(Plugin):
    """Define Acme's writing rules."""

    name = "acme-rules"
    rules: ClassVar = {
        "ACM": {
            "description": "Acme writing rules",
            "001": "Avoid obviously.",
            "002": "Keep lines at 80 characters or fewer.",
        }
    }

The class's name must match the entry point name. Acme001 registers itself when the package imports it. Each code rule needs a definition in rules.

Check configuration

linnl rules prints every rule with its resolved on/off state and whether Python or the model checks it.

Built-in rules

Develop

uv sync --group dev
uv run pytest
uv run ty check linnl
uv run ruff check
uv run ruff format
uv tool install --editable .

Acknowledgments

The CLH and WIK rules are adapted from Simon Willison's LLM cliche highlighter.

For a broader collection of deterministic prose checks, see Proselint.