humanizer

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