aismell

Sniff AI-smell in your text. Bilingual ES/EN. CLI. Offline. Opinionated.

🇪🇸 Léeme en español · 🌐 Try it in your browser

text.md  •  47 sentences  •  smell: 31% (moderate)

Line-by-line findings
  🔴 L4   It's not just about productivity—it's about transformation.
        AI's signature negative parallelism [en.not_just]
        → state the positive idea directly

  🔴 L12  ...let's delve into the complexities of...
        the most flagged AI word of 2024 [en.delve]
        → use "explore", "look at", or just dig in

What it actually does

aismell reads your text and points out lines that smell like a language model wrote them. No false promise of "fooling GPTZero." Your blog post, email, PR description, or essay either sounds like you or sounds like an LLM — this tool just helps you spot which.

It runs offline, uses regex + heuristics (no API calls by default), and works on Spanish and English text.

Why another one of these

Most "AI text humanizers" are scams. They reshuffle synonyms or insert typos to bypass detectors. That game is dishonest and useless.

aismell is the opposite:

• It does not rewrite for you. It tells you what reads like AI, line by line.
• It is auditable. Every pattern lives in a YAML file you can read and contribute to.
• It is offline by default. Your text never leaves your machine.
• It does not promise to fool detectors. It promises to make your text feel less like autopilot.

The honest framing is editorial, not adversarial. Use it before publishing.

Install

pipx (recommended, any OS):

pipx install aismell
pipx inject aismell pymupdf       # optional: enable PDF annotation

Arch (AUR):

yay -S aismell                    # once published
# or from this repo:
git clone https://github.com/brm-src/aismell.git
cd aismell/packaging && makepkg -si

From source, no install:

git clone https://github.com/brm-src/aismell.git
cd aismell
./bin/aismell --help
# requires: PyYAML (pacman -S python-yaml, apt install python3-yaml, etc.)

Requires Python 3.9+. PyMuPDF is optional, only for .pdf annotation.

Use

# analyze a file (auto-detects language)
aismell post.md

# pipe stdin
cat draft.txt | aismell

# annotate a Word .docx — yellow highlights + sidebar comments
aismell mi-tesis.docx --out mi-tesis-marcado.docx

# annotate a PDF — yellow highlights + sticky-note comments
aismell paper.pdf --out paper-marcado.pdf

# no arguments? opens a native file picker (if you have a desktop)
aismell

# only show high-confidence findings
aismell --strict post.md

# get a single number 0-100 (great for CI / pre-commit)
aismell --score-only post.md

# force language
aismell --lang es post.md

# disable color
aismell --no-color post.md

Exit code is 0 when clean, 1 when findings are present. Useful for git hooks.

What it catches

Three layers of detection.

1. Phrase patterns. Things AI writes when it coasts: vale la pena destacar, delve into, stands as a testament, hope this helps. The rules now cover 130+ English patterns and 180+ Spanish patterns, including formal connectors and bloated abstract nouns.

2. Structure patterns. Tells beyond word choice: split binary reframes, false agency, evasive passive voice, negative listing, copula avoidance, generic conclusions, sycophantic openers.

3. Rhythm, shape, and discourse. Sentence-length variance, em-dash density, list ratio, rule-of-three frequency, paragraph-length symmetry (LLMs produce paragraphs of suspiciously similar length), opening-connector density (Pangram research shows multiple paragraphs starting with explicit connectors is the single strongest AI tell), and StoryScope-inspired cues such as over-explained themes and too-neat narrative closure.

Scores are normalized to a 0–100 smell percentage. Above 60 is loud AI, 30–60 is mixed, below 30 is mostly clean.

What it does not do

• Does not call an LLM (a future --rewrite flag may do so, opt-in).
• Does not rewrite your text for you.
• Does not claim to be a forensic AI detector. False positives are fine — humans use these phrases too. The point is making them visible so you can decide.

Patterns are data

Every detection rule lives in patterns/es.yaml or patterns/en.yaml. Format:

- id: en.delve
  kind: phrase            # phrase | regex
  severity: 3             # 1 (suspect) | 2 (probable) | 3 (almost certain)
  pattern: delve into
  message: the most flagged AI word of 2024
  suggestion: use "explore", "look at", or just dig in

Add a pattern, open a PR. No code changes needed for new rules.

Roadmap

• More patterns (always)
• --rewrite flag with optional LLM backend (offline by default stays default)
• Plain-text output mode for grep-style piping
• Pre-commit hook config
• --diff mode that shows before/after suggestions

Related

This project is built on top of the patterns documented in Wikipedia: Signs of AI writing, blader/humanizer, and hardikpandya/stop-slop. The bloat lexicon and structural checks are informed by Pangram Labs research (2024-2025), the DAMAGE paper on AI humanizers, and EditLens. See docs/research.md for the full breakdown.

All sources MIT-compatible, and so is this.

License

MIT. See LICENSE.