Humanizer Pro

Finds the habits that make text read as machine-written, removes them, and checks that every fact survived. Runs on your computer with no account, no API key, and no network connection. Measured false-positive rate on 1,264 human-written documents: 0.2%.

Three ways to use it:

# 1. As a skill in Claude Code (then type /humanizer-pro)
git clone https://github.com/eddyplolz/humanizer-pro.git ~/.claude/skills/humanizer-pro

# 2. As a skill in Codex and other agents
git clone https://github.com/eddyplolz/humanizer-pro.git ~/.agents/skills/humanizer-pro

# 3. As a command-line checker (Python 3.10+)
pip install humanizer-pro && humanizer-audit draft.md

Windows paths and the GitHub Action are in Install the skill and Check files automatically.

Who it is for: anyone cleaning up an AI draft before it goes out; editors and docs teams who want a check in CI; Wikipedia and wiki editors, since it knows wikitext and neutral tone; and coding agents auditing their own prose.

What makes it different from a "humanizer" website: your text never leaves your machine, every flag comes with the reason and the line, a compare mode proves the rewrite kept your numbers, names, dates, and links, and the error rates are measured on public data you can rebuild yourself.

Contents

1. What it does
2. What it does not do
3. Your privacy
4. Install the skill
5. Use the skill
6. Check files from the command line
7. Check files automatically
8. How well it works
9. How it decides
10. Help improve it
11. Credits and license
12. Version history

What it does

AI drafts repeat the same habits: stock phrases, inflated importance, and filler that sounds complete but says little. Readers notice, and then they stop trusting the text.

Humanizer Pro:

• finds those habits and explains each one
• rewrites the draft in plain language, if you ask it to
• checks that a rewrite kept the numbers, dates, full names, links, and quotes it can detect
• flags text that a chatbot left behind, such as citation codes and placeholder fields

Here is an example.

Before:

In today's rapidly evolving digital landscape, effective collaboration serves as a crucial cornerstone for organizations seeking to unlock their full potential. It is important to note that this approach is not just about tools, but about creating a vibrant culture of innovation.

After:

Good collaboration depends less on the tool than on whether people know what decisions they own, where work is tracked, and how quickly blockers get resolved.

The command-line checker explains the first version line by line (shortened):

$ humanizer-audit eval/fixtures/ai-slop-general.md
eval/fixtures/ai-slop-general.md — risk 60
  WARNING L3:C1 family3.filler_framing — Filler framing or superficial analysis [In today's]
  WARNING L3:C37 family4.ai_vocab_cluster — AI-vocabulary cluster [cornerstone, crucial, enhance, foster, landscape, robust, unlock, vibrant]
  WARNING L6:C29 family5.syntactic_tell — Syntactic tell or hedged construction [It is important to note]
  WARNING L6:C75 family7.rhetorical_formula — Rhetorical formula or forced cadence [not just about tools, but]
  WARNING L7:C80 family3.filler_framing — Filler framing or superficial analysis [In conclusion]

What it does not do

This project makes no claims about AI detectors.

It does not add a fake personality. Swapping one stock phrase for a casual one trades one habit for another, so the skill avoids both.

It does not rewrite text that is already clean. A built-in restraint check returns good writing close to how it arrived.

Your privacy

The command-line checker reads files on your computer and sends nothing anywhere. It makes no network connections and keeps no logs.

The skill runs inside your coding agent, such as Claude Code or Codex. Your text goes wherever your agent already sends it, and nowhere else.

Two features can put your text somewhere else, and only when you choose them:

• SARIF results contain short quotes from your text. If you upload them to GitHub code scanning, those quotes are stored with your repository's code scanning results.
• The GitHub Action runs in your own GitHub Actions workflow, so your files are read on GitHub's servers, as with any other check you run there.

Install the skill

Before you start

You need git. To use the command-line checker as well, you also need Python 3.10 or newer.

Install for Claude Code

On a Mac or Linux computer, run these commands in Terminal:

mkdir -p ~/.claude/skills
git clone https://github.com/eddyplolz/humanizer-pro.git ~/.claude/skills/humanizer-pro

On Windows, run these commands in Command Prompt:

mkdir "%USERPROFILE%\.claude\skills"
git clone https://github.com/eddyplolz/humanizer-pro.git "%USERPROFILE%\.claude\skills\humanizer-pro"

To check it worked, open the new humanizer-pro folder and look for a file called SKILL.md. Claude Code loads the skill the next time you start it. You can then type /humanizer-pro.

Install for Codex and other agents

On a Mac or Linux computer:

mkdir -p ~/.agents/skills
git clone https://github.com/eddyplolz/humanizer-pro.git ~/.agents/skills/humanizer-pro

On Windows:

mkdir "%USERPROFILE%\.agents\skills"
git clone https://github.com/eddyplolz/humanizer-pro.git "%USERPROFILE%\.agents\skills\humanizer-pro"

If you use Codex and have set CODEX_HOME, install into $CODEX_HOME/skills instead. Otherwise ~/.codex/skills also works.

Use the skill

Paste your text after a request in plain words. You do not need to learn any commands.

The full audit rates the draft on 6 qualities: directness, rhythm, trust, authenticity, density, and restraint. It shows its reasoning before the rewrite.

Wiki mode removes promotional tone, keeps citations, and flags claims that have no source.

Style edits use a short checklist based on The Elements of Style. The full 1918 text is included, and the skill only loads it when you ask.

Check files from the command line

The checker reads text files and lists each problem with its line number and the words that triggered it. It never changes your files.

Install the checker

Install it with pipx:

pipx install git+https://github.com/eddyplolz/humanizer-pro

You can also run it from a downloaded copy of this repository, without installing anything:

python3 scripts/humanizer_audit.py path/to/draft.md

On Windows, use py -3 instead of python3.

Check a file

humanizer-audit path/to/draft.md

You can:

• check several files or folders at once (a folder means every .md and .txt file inside it)
• add --json to get results a program can read
• add --sarif results.sarif to save results in SARIF, the format GitHub uses to show problems on pull requests
• add --include-code to check code samples as well (they are skipped by default, but leaked chatbot text inside code is always caught)
• use --compare original.md revised.md to check that a rewrite kept the numbers, dates, names of 2 or more words, links, citations, quotes, and code samples in the original (it does not catch every change: a one-word name or a changed fact, such as "delayed" becoming "canceled," can pass)

Understand the result

The checker ends with an exit code that scripts can act on.

Check files automatically

Before each commit

pre-commit is a tool that runs checks every time you commit. To add this check, put the following in a file called .pre-commit-config.yaml at the top of your project:

repos:
  - repo: https://github.com/eddyplolz/humanizer-pro
    rev: v4.15.0
    hooks:
      - id: humanizer-audit

The check runs on Markdown and text files. A review or block result stops the commit.

In GitHub Actions

This repository is also a GitHub Action. To check your writing on every pull request:

1. In your project, create the file .github/workflows/writing.yml.
2. Paste in the workflow below.
3. Change paths to the files or folders you want checked.
4. Commit the file.

name: Writing check
on: pull_request

permissions:
  contents: read
  security-events: write  # needed to show results on the pull request

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: eddyplolz/humanizer-pro@v4.15.0
        with:
          paths: docs README.md
          fail-on: block
      - uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: humanizer-audit.sarif

The last step shows each finding on the pull request, next to the line it refers to.

You can set these options:

The action needs Python 3 on the runner. GitHub's Ubuntu and macOS runners have it.

How well it works

This project measures its error rates instead of only describing them. It counts errors in both directions:

• false positives: how often it flags writing by people
• catch rate: how often it flags writing by AI

False positives

Every document in the human set was written before ChatGPT was released, so any flag on one is a mistake by definition. The latest rates, at the default threshold, are:

By the period the text was written in:

These rates come from the current rules, measured on the test group only (1,264 documents). A block counts as a false positive. The Wikipedia slice is small, so its rate says little yet.

Every document comes from a public source. The project publishes a fingerprint of each one (a unique code), with its date, word count, and a public pointer such as a Wikipedia revision id or a Stack Exchange answer id, so anyone can rebuild the collection and check the numbers. It never publishes the text.

Catch rate

The AI text comes from 2 public sources, labeled by model:

• text from RAID, a research benchmark of 2023 AI models
• first replies from WildChat, a public collection of real ChatGPT conversations

A pool of answers from current Claude models to 60 published prompts can be added with scripts/generate_machine.py; it is not part of the published numbers.

The catch rate at the default threshold is 3.1% overall (20 of 638 test documents): 5.5% on chat replies, 0.0% on news and encyclopedia text. The full table by model is in the results. 2 limits apply:

• it describes those AI models only
• the human essays and newspapers are about 100 years old, so part of any gap there reflects the era, not the author

How the results stay honest

Every document goes into one of 2 groups, chosen by its fingerprint. About a quarter go into a tuning group, and the rest into a test group.

Rules are adjusted using the tuning group only. Every published rate uses the test group only, so a rule cannot be tuned to make its own results look better.

This project also checks its own documentation with the same rules, using scripts/self_scan.py. It publishes 2 scores: one that counts every phrase this page quotes as a bad example, and one that leaves quotes and code out.

How it decides

The checker looks for 9 families of habits, learned from cleanup work on Wikipedia and elsewhere. For example:

• inflated importance, such as "stands as a testament" or "pivotal moment"
• stock rhetorical patterns, such as "not just X, but Y" or lists that always come in threes
• text left behind by a chatbot, such as "I hope this helps," knowledge-cutoff notes, or citation codes like oaicite

The full list, with examples, is in the catalog of habits.

2 principles guide every edit:

• a single instance proves nothing (one "crucial" is a coincidence, but a cluster is a pattern)
• over-editing is a failure (if a change makes good writing worse, the original goes back)

The checker is stricter for some kinds of writing than others. A chat message, an essay, a news story, and an encyclopedia article each have their own rules for strictness.

Help improve it

New rules go through a review process before they are added. A proposed rule is rejected if it:

• encourages over-editing
• repeats an existing rule
• reflects one person's taste
• takes more than about 80 words to state

The full process is in the improvement guide.

Before you open a pull request, run these 2 checks. Both must pass.

python3 -m pytest -q tests
python3 scripts/self_scan.py

On Windows, use py -3 instead of python3.

Credits and license

This project uses the MIT License.

It is a rebuild of blader/humanizer by Siqi Chen (MIT, copyright 2025). It adds a catalog of habits, detection of leaked chatbot text, a fact-checking compare mode, wiki and style modes, and measured error rates. The LICENSE file includes both copyright notices.

It draws on these sources:

• blader/humanizer by Siqi Chen (MIT)
• Stop Slop by Hardik Pandya (MIT)
• avoid-ai-writing by Conor Bronsdon (MIT): the vocabulary tiers, strictness rules, self-check, and error-rate measurement design
• humanize by Harshaneel Gokhale (MIT): rhythm counts and several patterns
• Wikipedia: Signs of AI writing by WikiProject AI Cleanup (CC BY-SA 4.0)
• Project Gutenberg #37134: the public-domain text of The Elements of Style by William Strunk Jr.
• US-PD-Newspapers by PleIAs: public-domain newspapers in the human test set
• RAID by Dugan and others (MIT): AI-written test set
• WildChat-1M by Ai2 (ODC-BY): AI-written test set
• Python Enhancement Proposals (public domain): technical writing in the human test set

Version history

Current release: v4.15.0. It puts the package on PyPI, rebuilds the measurement corpus from public sources only, publishes error rates in both directions, adds four editing principles and several new checks to the audit, and tests on Windows and macOS. Every change is listed in the changelog.