humanizer

Detect and remove signs of AI-generated writing. Makes text sound natural and human.

An OpenClaw skill and standalone CLI tool that scans text for 30 AI writing patterns using 500+ vocabulary terms and statistical text analysis (burstiness, type-token ratio, readability metrics) — then provides actionable suggestions to fix them.

Based on Wikipedia:Signs of AI writing, Copyleaks stylistic fingerprint research, and blader/humanizer.

Install

As an OpenClaw skill

git clone https://github.com/brandonwise/humanizer.git
cp humanizer/SKILL.md ~/.config/openclaw/skills/humanizer.md

As a standalone CLI tool

git clone https://github.com/brandonwise/humanizer.git
cd humanizer
npm install

# Score some text
echo "This serves as a testament to innovation." | node src/cli.js score

# Full analysis
node src/cli.js analyze -f your-draft.md

# Humanize with auto-fixes
node src/cli.js humanize --autofix -f article.txt

Global install

npm install -g .
humanizer score < draft.txt
humanizer analyze -f essay.md
humanizer humanize --autofix < article.txt

Architecture

The scoring engine combines three signal types:

┌─────────────────────────────────────────────────┐
│              Composite Score (0-100)             │
├────────────────────┬────────────────────────────┤
│   Pattern Score    │    Uniformity Score         │
│   (70% weight)     │    (30% weight)             │
├────────────────────┼────────────────────────────┤
│ • 30 pattern       │ • Burstiness (sentence     │
│   detectors        │   length variation)         │
│ • 500+ vocabulary  │ • Type-token ratio          │
│   terms (3 tiers)  │ • Trigram repetition        │
│ • Density scoring  │ • Sentence length CoV       │
│ • Category breadth │ • Paragraph uniformity      │
└────────────────────┴────────────────────────────┘

Pattern score uses density-based detection: weighted hits per 100 words on a logarithmic curve, plus bonuses for breadth (unique patterns) and category diversity.

Uniformity score uses statistical analysis: human text has high burstiness (varied sentence lengths), diverse vocabulary, and low n-gram repetition. AI text is mechanically uniform.

Statistical analysis

The stats engine computes metrics that differentiate AI from human writing:

CLI reference

Commands

# Quick score (0-100, higher = more AI-like)
echo "text" | humanizer score

# Full analysis with pattern matches
humanizer analyze essay.txt

# Full markdown report (pipe to file)
humanizer report article.txt > report.md

# Suggestions grouped by priority
humanizer suggest draft.md

# Statistical analysis only
humanizer stats essay.txt

# Humanization suggestions with guidance
humanizer humanize -f article.txt

# Apply safe auto-fixes
humanizer humanize --autofix -f article.txt

# Scan an entire docs folder, rank risk, and show recurring pattern hotspots
humanizer scan docs --ext md,txt --fail-above 45

# Scan a large repo with reusable defaults + custom ignores
humanizer scan . --config .humanizer.json --ignore-dirs vendor,generated

# Baseline-aware scan: fail only on regressions vs a saved baseline
humanizer scan docs --json > .humanizer-baseline.json
humanizer scan docs --baseline .humanizer-baseline.json --fail-on-regression

# Compare draft revisions and see score delta
humanizer compare --before draft-v1.md --after draft-v2.md

New core capabilities

• Repo scan (scan) — analyze a whole folder, rank files by risk, surface cross-file pattern hotspots, and optionally fail CI with --fail-above.
• Baseline-aware scan gating — compare a current scan to a saved baseline (--baseline) and fail only when files regress.
• Config-driven scan defaults — keep monorepo scan settings in one JSON file (--config) and layer one-off overrides from CLI.
• Custom ignore controls — skip noisy directories with --ignore-dirs or disable built-in excludes with --no-default-ignore.
• Code-aware analysis mode (--ignore-code) — ignore fenced code blocks and inline code snippets so technical docs do not get false positives from sample code.
• Quote-aware analysis mode (--ignore-quotes) — ignore markdown/email quote blocks so pasted AI examples, support replies, and forum excerpts do not dominate scores.
• Confidence calibration: every analysis now includes a confidence rating (high/medium/low) with short-sample warnings to reduce false-positive overconfidence.
• Draft compare (compare) — compare two versions of text and show exactly which patterns improved or regressed.
• Unicode obfuscation detection (pattern 29) — flags hidden zero-width/soft-hyphen tricks and suspicious non-breaking-space density often used in detector-evasion text.
• Product positioning fog detection (pattern 30) — flags clustered PM/marketing claims like drive engagement and unlock value when they lack a user, metric, or concrete behavior.

Options

-f, --file <path>       Read text from file
--json                  Output as JSON
--verbose, -v           Show all matches
--autofix               Apply safe fixes (humanize only)
--patterns <ids>        Check specific pattern IDs (comma-separated)
--threshold <n>         Only show patterns with weight above n
--before <path>         Before file for compare command
--after <path>          After file for compare command
--ext <list>            Extensions for scan (e.g. md,txt,rst)
--min-words <n>         Skip files shorter than n words (scan)
--fail-above <n>        Exit non-zero if any scanned file score >= n
--baseline <file>       Compare scan against prior scan JSON output
--regression-threshold <n>  Minimum score delta to flag regression (default: 1)
--fail-on-regression    Exit non-zero if baseline regressions are found
--ignore-dirs <list>    Extra dirs to ignore when scanning (comma-separated)
--no-default-ignore     Disable built-in ignores (.git,node_modules,dist,...)
--ignore-code           Ignore fenced/inline code snippets during analysis
--ignore-quotes         Ignore markdown/email quote blocks during analysis
--config <file>         Load scan defaults from JSON (scan section)
--help, -h              Show help

Scan config file (--config)

--config reads scan defaults from a JSON file under a top-level scan object. CLI flags still win when both are provided.

{
  "scan": {
    "extensions": ["md", "txt"],
    "minWords": 30,
    "failAbove": 45,
    "baseline": ".humanizer-baseline.json",
    "regressionThreshold": 3,
    "failOnRegression": true,
    "ignoreDirs": ["generated", "vendor"],
    "includeDefaultIgnore": true,
    "ignoreCode": true,
    "ignoreQuotes": true
  }
}

Then run:

humanizer scan . --config .humanizer.json
# or one-off:
humanizer analyze docs/guide.md --ignore-code
# or ignore pasted quotes/examples too:
humanizer analyze docs/guide.md --ignore-code --ignore-quotes
# or regression-only gate:
humanizer scan docs --baseline .humanizer-baseline.json --fail-on-regression

Score badges

🟢 0-25    Mostly human-sounding
🟡 26-50   Lightly AI-touched
🟠 51-75   Moderately AI-influenced
🔴 76-100  Heavily AI-generated

API (programmatic use)

const { analyze, score } = require('humanizer');

// Quick score
const s = score('Your text here...');
console.log(s); // 0-100

// Full analysis
const result = analyze(text, {
  verbose: true,          // Show all matches
  patternsToCheck: [7, 19, 22], // Only specific patterns
  includeStats: true,     // Include statistical analysis
});

console.log(result.score);           // 0-100 composite
console.log(result.patternScore);    // Pattern-only score
console.log(result.uniformityScore); // Stats-based uniformity score
console.log(result.stats);           // { burstiness, typeTokenRatio, ... }
console.log(result.findings);        // Detailed pattern matches
console.log(result.categories);      // Per-category breakdown

// Humanize
const { humanize, autoFix } = require('humanizer/src/humanizer');

const suggestions = humanize(text, { autofix: true });
console.log(suggestions.critical);   // Dead giveaway issues
console.log(suggestions.important);  // Noticeable patterns
console.log(suggestions.guidance);   // Writing tips
console.log(suggestions.styleTips);  // Statistical style advice
console.log(suggestions.autofix.text); // Auto-fixed text

// Stats only
const { computeStats } = require('humanizer/src/stats');
const stats = computeStats(text);
console.log(stats.burstiness);       // Sentence variation
console.log(stats.typeTokenRatio);   // Vocabulary diversity

Pattern catalog (top 24 shown)

Vocabulary tiers

• Tier 1 (Dead giveaways): 50+ words that appear 5-20x more in AI text. Always flagged. Examples: delve, tapestry, vibrant, crucial, meticulous, seamless, groundbreaking
• Tier 2 (Suspicious in density): 80+ words flagged when 2+ appear. Examples: furthermore, paradigm, holistic, utilize, facilitate, nuanced
• Tier 3 (Context-dependent): 60+ words flagged only at >3% density. Examples: significant, effective, unique, compelling, exceptional
• Phrases: 80+ multi-word patterns. Examples: "In today's digital age", "plays a crucial role", "serves as a testament"

How scoring works

1. Pattern detection — Each of 30 detectors scans for regex matches. Matches are weighted 1-5.
2. Density calculation — Weighted matches per 100 words, on a logarithmic curve (prevents runaway scores).
3. Breadth bonus — More unique pattern types = higher score (up to +20).
4. Category diversity — Hits across content/language/style/communication/filler = higher score (up to +15).
5. Statistical uniformity — Low burstiness, low vocabulary diversity, high repetition add up to 100 uniformity points.
6. Composite blend — Pattern score (70%) + uniformity score (30%) = final score.

This transparent methodology means you can see exactly why text scored the way it did.

What makes this different

Before/after

Before (AI score: 78):

Great question! Here is an overview of AI-assisted coding. AI-assisted coding serves as an enduring testament to the transformative potential of large language models, marking a pivotal moment in the evolution of software development. In today's rapidly evolving technological landscape, these groundbreaking tools are reshaping how engineers ideate, iterate, and deliver, underscoring their vital role in modern workflows. The future looks bright. I hope this helps!

After (AI score: 4):

AI coding tools speed up boilerplate. In a 2024 Google study, developers using Codex finished simple functions 55% faster, but showed no improvement on debugging or architecture. I've used Copilot for a year. It's good at config files and test scaffolding. It's bad at knowing when it's wrong.

Always-On Mode: Bake Into Your Agent's Personality

The skill works great on-demand, but the real power is making your AI always write like a human. Here's how to bake the humanizer principles into your agent's system prompt or personality file.

For OpenClaw (SOUL.md)

Add this to your SOUL.md (or equivalent personality file):

## Writing Like a Human (Anti-AI Patterns)

Your writing should be indistinguishable from a sharp, opinionated human.
These rules are always on — not just when asked to "humanize."

### Never Use These Words
Dead giveaways of AI output — ban them from your vocabulary:

**Words:** delve, tapestry, vibrant, crucial, comprehensive, meticulous, embark,
robust, seamless, groundbreaking, leverage, synergy, transformative, paramount,
multifaceted, myriad, cornerstone, reimagine, empower, catalyst, bolster,
spearhead, invaluable, bustling, nestled, realm, showcase, foster, garner,
interplay, enduring, pivotal, intricate, harness, unleash, revolutionize,
elucidate, encompass, holistic, utilize, facilitate, nuanced, paradigm, poised

**Phrases:** "In today's [anything]", "It is worth noting", "plays a crucial role",
"serves as a testament", "in the realm of", "delve into", "harness the power of",
"embark on a journey", "the landscape of", "without further ado"

**Filler to cut:** "In order to" → "to". "Due to the fact that" → "because".
"It is important to note that" → just say it.

### Kill These Patterns
1. No significance inflation — state facts, skip "pivotal moment" claims
2. No vague attributions — name the source or drop the claim
3. No -ing tails — "highlighting the importance of..." gets its own sentence
4. No copula avoidance — use "is" and "has", not "serves as" or "boasts"
5. No sycophancy — skip "Great question!" and just answer
6. No chatbot artifacts — no "I hope this helps" or "Let me know if..."
7. No generic conclusions — end with specifics, not "the future looks bright"

### Write With Human Texture
- Vary sentence length (short, then long, then short)
- Have opinions and take stances
- Use concrete specifics (numbers, names, dates)
- Allow imperfection (contractions, fragments, "And" or "But" starters)
- Use simple verbs ("is", "has", "does" are fine)
- Read it aloud — if you wouldn't say it, don't write it

For Claude (system prompt)

Add to your system prompt or CLAUDE.md:

You write like a human, not an AI. Never use words like "delve", "tapestry",
"crucial", "comprehensive", "robust", "seamless", or "groundbreaking". Never
write "In today's...", "It is worth noting...", or "Great question!". Use "is"
not "serves as". Vary your sentence lengths. Have opinions. Use specific numbers
and names instead of vague claims. End with specifics, not "the future looks
bright". If you'd never say it in conversation, don't write it.

For ChatGPT (Custom Instructions)

Paste into your Custom Instructions → "How would you like ChatGPT to respond?":

Write like a specific human, not a generic AI. Rules:
- Never use: delve, tapestry, vibrant, crucial, robust, seamless, groundbreaking,
  transformative, leverage, synergy, paramount, multifaceted, myriad
- Never start with "In today's..." or end with "the future looks bright"
- Never write "Great question!" or "I hope this helps!"
- Use "is" not "serves as". Use "to" not "in order to"
- Vary sentence length. Short. Then longer. Have opinions.
- Use real numbers and names, not "experts say" or "studies show"

Verification

After baking in, test your agent by asking it to write about any topic. Then scan it:

echo "Your agent's response here" | node src/cli.js score

Target: consistently under 25 on the humanizer score.

Project structure

humanizer/
├── SKILL.md          # OpenClaw skill definition
├── src/
│   ├── patterns.js   # 30 pattern detectors + pattern registry
│   ├── vocabulary.js  # 500+ AI words/phrases (3 tiers)
│   ├── stats.js       # Statistical analysis engine
│   ├── analyzer.js    # Composite scoring engine
│   ├── humanizer.js   # Suggestion engine + auto-fix
│   └── cli.js         # CLI with colored output
├── tests/             # Vitest test suite (136 tests)
│   ├── analyzer.test.js
│   ├── humanizer.test.js
│   ├── statistics.test.js
│   ├── calibration.test.js
│   ├── performance.test.js
│   └── edge-cases.test.js
├── references/        # Pattern catalogs, vocabulary lists
└── docs/              # Detailed documentation

Contributing

1. Fork and create a branch
2. Add/improve pattern detection (see src/patterns.js)
3. Write tests for your changes
4. Run npm test — all tests must pass
5. Open a PR

License

MIT