timbre

Catch generic AI writing before your readers do.

Lint drafts and whole repos. Teach agents from writing you trust.

Pronounced TAM-ber.

Get started · Audit a repo · Build a voice skill · npm · Lint reference · Corpus reference

Timbre is an editorial linter for AI-assisted writing. It finds the habits that make useful drafts feel bland, repetitive or strangely over-polished. Every finding comes with a file, line, rule and reason, so a writer or agent can revise the draft without guessing.

Run it on one article or an entire content tree. When a clean draft still sounds interchangeable, give Timbre writing you already trust. It will measure the recurring voice and package the evidence as a skill that Codex, Claude and other agents can use while drafting.

Stop cleaning up the same problems

AI gets to a plausible first draft quickly. Editing takes longer because vague claims need evidence, staged contrasts need rewriting, and page after page settles into the same polished rhythm.

Those habits become harder to catch as a repo grows. Reviewers know the copy feels wrong but have to explain why from scratch. Another prompt often trades one generic voice for another.

Timbre turns that recurring cleanup into a reviewable workflow:

• Exact locations replace vague feedback about tone.
• A transparent 0–100 score puts the worst files first.
• Safe mechanical fixes handle edits that need no judgement.
• Corpus evidence gives agents a better starting voice next time.

Try it on a draft

The npm beta currently supports Apple Silicon Macs and includes the full runtime. Python is not required.

npm install --global timbre@beta
timbre setup skill --yes
timbre lint launch.md

The setup command installs Timbre's general review skill for the coding agents it finds. The linter works without a skill or corpus profile.

Pass files or directories when the writing is elsewhere. Stdin works too:

timbre lint docs/ "content/**/*.mdx"
timbre lint "src/pages/**/*.astro" --preset marketing
timbre lint - --stdin-filename draft.md

Timbre reads Markdown, MDX, Astro and plain text. The Astro extractor checks visible text, prose props and static copy while ignoring component code, scripts, styles and expressions. Findings still point to the original source line.

See which files need work

audit ranks a folder by editorial pressure:

timbre audit content/ --preset marketing

Score  Err  Warn  Words  File
-----  ---  ----  -----  ----
   42    1     3    916  content/launch.md
   27    0     2   1786  docs/importing.mdx
    0    0     0    835  docs/setup.md

Under 25 is the target. Every point comes from visible findings you can inspect, ignore or configure. The score measures editing pressure. It does not estimate the probability that AI wrote the text.

Files shorter than 80 words still get linted, but Timbre withholds the score. Tiny components and fragments do not provide enough evidence for a useful ranking.

Fix what a tool can fix safely

Automatic fixes are deliberately narrow. Timbre can remove hidden Unicode and rewrite a small set of exact filler phrases without touching frontmatter, code, links, quoted examples or component expressions.

timbre lint launch.md --fix-dry-run
timbre lint launch.md -w

Everything else stays as a located suggestion. You keep control of the edit.

Give agents a better starting voice

Linting catches repeatable problems. Corpus mode helps when a draft passes the rules but still sounds interchangeable.

Point Timbre at writing you own or have permission to use:

timbre build ./posts --name my-writing
timbre skill my-writing --install

Timbre measures the language, rhythm and structures that recur in the corpus, then packages selected evidence as write-like-my-writing. An agent can query real examples while drafting and run the same lint and review loop before it returns the work.

The generated skill carries a compact evidence library and its own lint policy. Universal residue checks stay active, while voice-sensitive warnings can relax when the corpus strongly supports the habit. Using an existing generated skill does not require spaCy or NumPy.

Your writing stays local, and corpus extraction makes no API calls. No model weights are trained. Generated drafts retrieve evidence instead of copying source sentences. Read the corpus and generated-skill guide for input formats, style-runtime setup, privacy rules and inspection commands.

Use it where the writing lives

Presets stop a landing page from being judged like API documentation:

timbre lint src/pages/ --preset marketing
timbre lint docs/ --preset docs
timbre lint README.md --preset readme

JSON, JSONL, GitHub annotations and SARIF are built in. CI can fail on configured findings or a score limit:

timbre lint docs/ --format github --fail-on error
timbre audit docs/ --fail-score-above 49

The repository includes a complete GitHub Actions workflow and standard pre-commit configuration. Timbre also exposes a public pre-commit hook.

A small project configuration is often enough:

lint:
  preset: docs
  include:
    - "docs/**/*.mdx"
    - "src/pages/**/*.astro"
  failOn: error

Rules, baselines, inline suppressions, output contracts and complete configuration examples live in the linting guide.

What Timbre checks

The deterministic catalog covers 56 rule families. It catches assistant residue, staged contrasts, vague attribution, promotional filler, repetitive structures, suspiciously uniform rhythm and formatting habits that make prose feel pre-digested. Fourteen rules start as errors, thirty-eight start as warnings and four weak or house-style checks stay off until configured.

Some patterns depend on meaning. timbre review prepares a stable packet with numbered source lines and seventeen review lenses for an agent to judge. These cover disguised reframes, false agency, unsupported claims, portable filler, fake-profound endings and conflicts with corpus-supported voice. Timbre does not call a model itself.

See the editorial pattern map for the full catalog and linting guide for deterministic and agent-led review workflows.

What Timbre does not claim

Timbre is an editorial tool. A clean result does not prove human authorship, and a finding does not prove that a model wrote the sentence. The rules locate concrete habits worth reviewing because they make writing less clear, less specific or less recognisable as yours.

Corpus profiles measure writing you provide. They do not fine-tune a model or grant permission to reuse someone else's work. Public writing is not automatically licensed for redistribution.

Run from source

Source contributors need Python 3.11 to 3.13 and uv:

git clone https://github.com/iannuttall/timbre.git
cd timbre
uv sync
uv run timbre lint README.md

The default source install leaves out the style runtime. Core linting, review, profile inspection and existing generated skills still work. Install spaCy, NumPy and the English model only when building or scoring a corpus:

uv run timbre setup style --yes

Documentation

• Linting, scoring, fixes and CI
• Corpus profiles and generated skills
• Editorial pattern coverage
• Architecture and runtime boundaries
• npm publishing
• Agent instructions

Development

uv sync --all-extras --group dev --frozen
make check

Native packaging changes also require make native and make npm-smoke. A fixed source and environment produce the same profile and portable skill on every build.

Licence

Timbre is released under the MIT Licence.