An auditable, integrity-preserving style editor for AI-generated text.
不只是改写——是可审计、保真、有出处的风格编辑。
Quick Start · Modes · Usage · Architecture · Research Basis · Contributing · Changelog
Humanizer is a Claude Code skill that detects surface AI writing patterns and rewrites text in distinct human voice profiles. It scans for 43 editorial lint patterns, produces a style lint density score (not a fake detection probability), applies 5 voice profiles, and enforces a content integrity gate — numbers, citations, URLs, and code must survive the rewrite intact.
It turns:
"This comprehensive guide delves into the intricacies of our authentication system. The platform leverages cutting-edge JWT technology to provide a seamless, secure, and robust authentication experience."
Into:
"The auth system uses JWTs. Tokens expire after 15 minutes; refresh tokens last 7 days. The token rotation logic is in
src/auth/refresh.ts."
v1 was a surface-pattern replacer that claimed to predict detector behavior. v2 is an auditable style editor rebuilt after studying two papers:
| Paper | What we learned | What changed |
|---|---|---|
| Pangram 4 (arXiv:2607.27183, 2026) | AI detectors now operate at the token/clause level with structured CRF decoding, mixed-authorship heads, and dedicated humanizer detection. Surface rewrites are insufficient. | Removed false "probability API" claims. Added integrity gate, clause change maps, mechanical transform audit. Deprecated tail-token-smuggling. |
| Guo et al. (ICML 2025) | Low-probability tokens carry 3.5× more discriminative signal. Surface rewrites don't change entropy shape. Boilerplate transitions are free detector signal. | Moved P44-P47 from active patterns to research reference. Kept the descriptive insights (vary density, cut boilerplate, prefer specifics) as editorial heuristics — not detection-evasion guarantees. |
Core principle shift: We don't claim to know what any specific detector will do. We make the text better — more specific, more varied, more honest — and report what we changed. Detector results belong to detectors, not to us.
Claude Code installed.
git clone https://github.com/Aaron-Bushnell/humanizer.git ~/.claude/skills/humanizer# Detect AI patterns
/humanizer --mode detect --score "Your text..."
# Rewrite with a voice profile
/humanizer --mode rewrite --voice casual "Your text..."
# Edit a file in place
/humanizer --mode edit --file docs/README.md
# Audit without rewriting (style lint + integrity + mechanical checks)
/humanizer --mode audit "Your text..."
# Compare original vs rewrite (clause change map + integrity diff)
/humanizer --mode compare --file original.txt --rewritten rewritten.txt
# Extended rewrite with style metrics
/humanizer --mode deep --score "Your text..."| Mode | What it does | Rewrites? |
|---|---|---|
detect |
Scan for 43 patterns, report style lint density | No |
rewrite |
Full transform with voice injection (default) | Yes |
edit |
In-place minimal edits via Edit tool | Yes |
deep |
Extended rewrite guided by token-level style metrics | Yes |
compare |
Clause change map + integrity diff between two texts | No |
audit |
Style lint + mechanical transform audit + content risk check | No |
| Voice | Character |
|---|---|
casual |
Contractions, fragments, first person |
professional |
Dry wit, concrete examples, short paragraphs |
technical |
Precise terms, numbers over adjectives, code-like clarity |
warm |
"We" language, shorter paragraphs, empathy |
blunt |
Shortest sentences, no hedging, active voice |
| Flag | Effect |
|---|---|
--edit-budget light|balanced|heavy |
Controls rewrite intensity (default: balanced) |
--preserve facts,citations,terms,quotes,code |
Lock critical content (default: all) |
--voice-sample PATH |
Extract voice from a real writing sample |
--score |
Prepend [Style Lint: NN/100] density header |
┌──────────────┐
│ Input Text │
└──────┬───────┘
│
┌────────────┼────────────┐
│ │ │
┌────────▼──────┐ ┌──▼────┐ ┌─────▼────────┐
│ Detect │ │Voice │ │ --voice-sample│
│ 43 patterns │ │Inject │ │ (optional) │
│ (Step 2) │ │(Step3)│ │ │
└────────┬──────┘ └──┬────┘ └─────┬────────┘
│ │ │
└────────────┼────────────┘
│
┌──────▼───────┐
│ Rewrite │
│ (Step 4) │
└──────┬───────┘
│
┌────────────┼────────────┐
│ │ │
┌────────▼──────┐ ┌──▼────────┐ ┌─▼───────────┐
│ Integrity Gate│ │Clause Map │ │Style Metrics │
│ (numbers, URLs│ │(keep/edit │ │(TTR, hapax, │
│ citations, │ │ /rewrite/ │ │ Gini, entropy│
│ code) │ │ add/del) │ │ --deep only) │
└────────┬──────┘ └──┬────────┘ └─┬───────────┘
│ │ │
└────────────┼────────────┘
│
┌──────▼───────┐
│ Deliver │
│ (if gates │
│ pass) │
└──────────────┘
| Script | Purpose |
|---|---|
scripts/token_analyzer.py |
Document-level descriptive style metrics (TTR, hapax, Gini, Rényi entropy). No API calls; no probability claims. |
scripts/integrity_check.py |
Verifies numbers, URLs, citations, code blocks, negations, modals, and quotes are preserved post-rewrite. |
scripts/clause_align.py |
Aligns original and rewritten text at clause level; produces 5-class change map (keep/light_edit/rewrite/delete/add). |
scripts/benchmark_runner.py |
Runs configurable detector benchmarks; reports per-detector results separately — never synthesized. |
| Category | Count | What it catches |
|---|---|---|
| Content (P1-P8) | 8 | Significance inflation, AI vocabulary, copula avoidance, name-dropping |
| Language & Style (P9-P18) | 10 | Em dashes, boldface overuse, synonym cycling, title case, curly quotes |
| Communication (P19-P21) | 3 | Chatbot artifacts, knowledge-cutoff disclaimers, sycophancy |
| Filler & Hedging (P22-P30) | 9 | Generic conclusions, uniform sentence length, hallucination markers |
| Emerging 2026 (P31-P43) | 13 | LLM citation markup, UTM params, reshuffling immunity, infomercial hooks |
Full pattern documentation: references/patterns-en.md (English) · references/patterns-zh.md (中文独立规则)
A technical report from Pangram Labs describing their state-of-the-art AI text detection model. Key architectural facts that informed v2:
- Token-level 3-class classification (Human / AI-Assisted / AI-Generated) with CRF structured decoding
- Soft N-Grams Labeling as a training label generator (clause-level provenance tracking) — not an inference mechanism
- Dedicated humanizer detection head covering typo injection, casing changes, synonym substitution, homoglyph attacks
- Segment-level fAI estimation (15-bucket regression over 512-token windows)
- Repeat2 giving every token full document context
Our response: integrity gates, mechanical transform audits, clause-level change maps. We do not claim to predict or evade Pangram 4 scores. Full analysis: references/pangram4-notes.md
"On the Salience of Low-Probability Tokens for AI-Generated Text Detection"
Three findings we treat as descriptive observations, not prescriptive evasion recipes:
- Bottom ~15% tokens carry 3.5× more human signal (Assumption 3.1)
- Surface rewrites barely change Rényi entropy shape (Proposition 3.4)
- Boilerplate transitions are concentrated detector signal
We apply the editorial implications (vary density, cut boilerplate, prefer specifics) as writing-quality heuristics. We do not implement "tail token injection" or claim these heuristics reduce any specific detector's score. Full notes: references/guo2025-notes.md
humanizer/
├── SKILL.md # Main skill: routing, modes, execution protocol (224 lines)
├── references/
│ ├── patterns-en.md # P1-P43: English editorial lint catalog
│ ├── patterns-zh.md # Z1-Z20: 中文独立规则 (not translated from English)
│ ├── voices.md # 5 voice profiles + voice-sample extraction protocol
│ ├── pangram4-notes.md # Pangram 4: paper facts, limits, prohibited extrapolations
│ ├── guo2025-notes.md # Guo et al. (2025): distributional observations (research ref)
│ └── tail-token-smuggling.md # ⛔ DEPRECATED — kept for historical reference only
├── scripts/
│ ├── token_analyzer.py # Document-level descriptive style metrics
│ ├── integrity_check.py # 7-category content preservation verifier
│ ├── clause_align.py # Clause split + greedy alignment + 5-class change map
│ └── benchmark_runner.py # Detector adapter interface + reproducible result records
├── tests/
│ └── fixtures/ # Sample original/rewritten pairs + benchmark config
├── README.md
├── LICENSE # MIT
├── CONTRIBUTING.md
└── .github/
└── ISSUE_TEMPLATE/
When --score is used, Humanizer computes a style lint density score:
score = 4 × patterns_hit
+ 25 × (1 − burstiness_normalized)
+ 15 × (vocabulary_blacklist_ratio)
Clamped to 0–100. Lower = fewer surface AI patterns detected.
| Range | Meaning |
|---|---|
| 0–20 | Very few patterns detected |
| 21–40 | Minor tells, easy to clean |
| 41–60 | Multiple patterns triggered |
| 61–80 | Many structural tells |
| 81–100 | Dense AI writing patterns |
This is a rule-density heuristic. It does not estimate what any specific detector would score. For actual detector results, use --mode benchmark with an explicitly configured detector via scripts/benchmark_runner.py.
Contributions welcome. Before submitting, please read:
CONTRIBUTING.md— pattern proposal format, voice profile guidelines, PR processreferences/pangram4-notes.md— what we know and what we don't claim to know
Areas we especially welcome:
- New patterns for the English or Chinese catalogs (with source attribution)
- Voice profile refinements based on real writing data
- New language pattern sets (the
patterns-zh.mdmodel is the template)
- Removed: P44-P47 from active patterns (→ research reference); "real token probability via API" claims; tail-token-smuggling from default path; detection guarantees in scoring rubric
- Added:
integrity_check.py;clause_align.py;benchmark_runner.py;compareandauditmodes;--edit-budget,--preserve,--voice-sampleparams;references/pangram4-notes.md;references/guo2025-notes.md;references/patterns-zh.md;references/voices.md - Changed: SKILL.md 580→224 lines; scoring renamed to "Style Lint"; iteration stops on quality gates, not zero patterns;
token_analyzer.pymethodology label corrected; 47→43 patterns - Deprecated:
tail-token-smuggling.md(kept for history, removed from execution path)
- Initial release: 47 patterns, 5 voices, deep mode, tail token smuggling
MIT © 2026 — see LICENSE
Write like a human. Be weird, specific, inconsistent.