# vale-ai-tells

> A Vale style-package that flags AI-written prose tells like em dashes, abstract triads, and antithesis flourishes so you can rewrite them yourself.

vale-ai-tells is an open-source Vale style-package built and maintained by Krishna Sunkam under the MIT license. It runs entirely on your local machine and flags the mechanical fingerprints of AI-generated or spec-grade prose in Markdown, HTML, and plain text files — without rewriting anything for you.

## What It Is

vale-ai-tells is a linting rule set for the [Vale](https://vale.sh) prose linter. Rather than guessing a probability that a machine wrote your text, it names specific, mechanical tells — the em dash, the abstract-noun triad, the antithesis flourish — and leaves the rewrite to the author. The project describes itself as "a rule floor, not a detector," meaning it catches patterns that should never ship or that warrant judgment, but it does not attempt to score overall AI-likeness.

## The 17 Rules

The package ships seventeen rules derived from real editing passes and scored against a labeled benchmark. Six are gated as errors — mechanical tells the project says should never ship:

- **Dash** — em and en dashes, including numeric ranges
- **CodeToken** — ALL_CAPS_UNDERSCORE names and single-letter formulas
- **FilePath** — raw file paths in prose
- **StatusBracket** — inline status grades like `[ON TRACK, GREEN]`
- **SectionCode** — section and source codes
- **NeverTag** — antithesis flourishes closing with "never"

The remaining eleven fire as suggestions: EpigramContrast, NegParallel, CopulaInflation, HiddenVerb, Passive, Cliche, WeakResume, VirtueHonest, LinkText, AbstractTriad, and Adverb. A `bench/` folder holds a synthetic labeled set and scorer so contributors can verify recall and false-fire rates before a rule ships.

## Setup Path

The quickest path is a one-command shell script that clones the repo and runs the bundled `checkmyprose.sh` against any Markdown file. Prerequisites are macOS or Linux, Vale (installable via Homebrew), and Python 3. For permanent integration, the AiTells style folder can be copied into any repo's `styles/` directory, or the release ZIP can be referenced directly in a `.vale.ini` config file and pulled with `vale sync`.

## Claude Code Integration

The repository includes a `SKILL.md` that lets Claude Code (or a compatible agent) act as a prose-review assistant. The agent runs the linter, reads findings back as a table, and offers recasts one at a time in the author's voice. The project is explicit that the skill marks tells and never bulk-rewrites.

## Update: v1.0.0 — 17 Rules, Benchmarked

Version 1.0.0 was published on 2026-08-25, marking the first stable release. The release name "17 rules, benchmarked" signals that the full rule set has been validated against the project's synthetic benchmark before shipping. The repository was created in July 2026 and reached its first release within roughly six weeks.

## Features
- 17 linting rules for AI-written prose tells
- Six error-level rules for mechanical tells that should never ship
- Eleven suggestion-level rules for judgment calls
- Runs entirely on local machine — no data leaves your system
- Supports Markdown, HTML, and plain text files
- One-command quickstart via checkmyprose.sh
- Vale style-package installable via .vale.ini and vale sync
- Benchmark folder with labeled set and scorer for rule validation
- Claude Code skill integration via SKILL.md
- MIT licensed and open source

## Integrations
Vale prose linter, Claude Code, Homebrew, Markdown, HTML, Plain text

## Platforms
MACOS, LINUX, API, CLI

## Pricing
Open Source

## Version
v1.0.0

## Links
- Website: https://github.com/krishnasunkam/vale-ai-tells
- Documentation: https://github.com/krishnasunkam/vale-ai-tells#readme
- Repository: https://github.com/krishnasunkam/vale-ai-tells
- EveryDev.ai: https://www.everydev.ai/tools/vale-ai-tells