# humanize-cli
Analyze and humanize AI-generated text. Detect AI markers, score detection risk, and get actionable improvement suggestions.
```bash
npm install -g humanize-cli
```
## Why This Exists
AI detectors are everywhere now. GPTZero, Originality.ai, Turnitin — they're flagging content left and right. Problem is, they also flag plenty of human writing.
This tool helps you understand *why* text gets flagged and *how* to fix it. Not to help AI pretend to be human, but to help you write in a way that sounds like you actually wrote it.
## Quick Start
```bash
# Analyze text for AI markers
humanize analyze "This comprehensive solution leverages cutting-edge technology."
# Get detection risk score
humanize score --file article.txt
# Get improvement suggestions
echo "The software utilizes robust methodologies" | humanize suggest
# Auto-transform text
humanize transform "It is important to note that this solution is seamless."
```
## Commands
| Command | Alias | Description |
|---------|-------|-------------|
| `analyze` | `a` | Detect AI markers and patterns |
| `score` | `s` | Calculate detection risk score |
| `suggest` | `sg` | Get improvement suggestions |
| `transform` | `t` | Apply automatic fixes |
| `watch` | `w` | Watch directory for changes |
| `config` | `c` | Show configuration and API status |
### `humanize analyze <text>`
Detects AI markers and patterns in your text:
- AI vocabulary (delve, leverage, comprehensive, seamless...)
- Structural patterns (perfect intro/conclusion, uniform sentences)
- Missing human elements (contractions, personal voice, opinions)
```bash
$ humanize analyze "This comprehensive guide delves into best practices."
═══ TEXT ANALYSIS ═══
Words: 8 | Sentences: 1 | Avg words/sentence: 8.0
⚠ AI Vocabulary Detected (3)
• "comprehensive" → try: full, complete, thorough
• "delves" → try: digs into, explores, looks at
• "best practices" → try: what works, good approaches
```
### `humanize score <text>`
Calculates detection risk as a percentage (0-100%):
- **0-20%**: Low risk — appears human-written
- **21-40%**: Moderate risk — may trigger sensitive detectors
- **41-70%**: High risk — likely to be flagged
- **71-100%**: Very high risk — will be flagged by most detectors
```bash
$ humanize score --file draft.txt
═══ DETECTION RISK SCORE ═══
Overall Risk: 67% (HIGH RISK)
Component Breakdown:
vocabulary ████████░░ 78%
structure ██████░░░░ 55%
patterns ███████░░░ 65%
naturalness ██████░░░░ 58%
personality ███████░░░ 72%
```
### `humanize suggest <text>`
Generates prioritized improvement suggestions:
- **🔴 Priority Fixes**: Must-fix issues that scream "AI"
- **🟡 Recommended**: Improvements that help
- **🟢 Optional Polish**: Nice-to-have tweaks
- **⚡ Quick Wins**: Copy-paste replacements
```bash
$ echo "It is important to note that our solution leverages..." | humanize suggest
═══ IMPROVEMENT SUGGESTIONS ═══
🔴 Priority Fixes
1. AI vocabulary detected: "leverages"
→ Replace with: use, take advantage of, work with
Before: "solution leverages cutting-edge..."
After: "solution uses cutting-edge..."
2. No contractions found - text sounds robotic
→ Use contractions! "Do not" → "don't"
```
### `humanize transform <text>`
Automatically applies humanization fixes:
- Replaces AI vocabulary
- Adds contractions
- Removes filler phrases
- Shows before/after risk score
```bash
$ humanize transform "It is important to utilize comprehensive solutions."
═══ TRANSFORMED TEXT ═══
It's important to use complete solutions.
Risk score: 72% → 31% (↓41% improvement)
```
### `humanize watch <directory>`
Monitor a directory for changes and analyze files in real-time:
```bash
$ humanize watch ./content --threshold 60
═══ WATCH MODE ═══
Directory: ./content
Threshold: 60%
Press Ctrl+C to stop
Scanning...
✓ intro.md 23%
⚠ HIGH RISK blog-post.md 78%
AI words: leverage, comprehensive, robust
Initial scan complete. Analyzed 2 files.
Watching for changes...
```
Options:
- `-t, --threshold <n>` — Alert when score >= threshold (default: 70)
- `-q, --quiet` — Only show high-risk files
### `humanize config`
Check configuration and API key status:
```bash
$ humanize config
═══ HUMANIZE CONFIGURATION ═══
API Integration:
GPTZero API: ✓ Configured
Originality.ai: ✗ Not configured
Detection Settings:
AI Vocabulary: 90+ words and phrases
Pattern Detectors: 9 structural patterns
Scoring: 5-component weighted average
```
## API Integration
Optional integration with GPTZero and Originality.ai for external validation:
```bash
# Set API keys
export GPTZERO_API_KEY="your-key-here"
export ORIGINALITY_API_KEY="your-key-here"
# Run with API checks
humanize analyze --api --file article.txt
```
The tool works fully offline by default. API keys add external validation on top of local analysis.
## Input Methods
```bash
# Direct text
humanize analyze "Your text here"
# From file
humanize score --file article.txt
humanize score -f draft.md
# Piped input
cat document.txt | humanize suggest
pbpaste | humanize analyze # macOS clipboard
# Output to file/clipboard
humanize transform -f draft.txt > improved.txt
humanize transform -f draft.txt | pbcopy # macOS
```
## Options
| Flag | Description |
|------|-------------|
| `-f, --file` | Read input from file |
| `-j, --json` | Output results as JSON |
| `-V, --verbose` | Show detailed output |
| `-q, --quiet` | Minimal output |
| `-a, --api` | Include GPTZero/Originality.ai checks |
| `-t, --threshold` | Alert threshold for watch mode (default: 70) |
| `-h, --help` | Show help |
| `-v, --version` | Show version |
## What It Detects
### AI Vocabulary
Words that scream "I was written by an AI":
- **The worst offenders**: delve, leverage, utilize, comprehensive, robust, seamless
- **Corporate buzzwords**: stakeholder, synergy, actionable, paradigm
- **Formal transitions**: furthermore, moreover, consequently, nevertheless
- **AI tells**: "It is important to note", "In conclusion", "Great question!"
### Structural Patterns
- Perfect intro/body/conclusion structure
- Uniform sentence lengths (low variance)
- Missing contractions
- Overuse of transitions
- Too many bullet points
### Missing Human Elements
- No personal pronouns (I, we, you)
- No opinions or perspective
- No emotional language
- No rhetorical questions
- No humor or personality
## Documentation
The `/docs` folder includes comprehensive guides:
- **[AI Detector Mechanics](docs/ai-detector-mechanics-technical-appendix.md)** — How detectors actually work (perplexity, burstiness, entropy)
- **[Writing Quality Research](docs/writing-quality-research.md)** — What makes writing genuinely good, not just undetectable
- **[The Humanization Pipeline](docs/The_Humanization_Pipeline.md)** — Complete 5-stage workflow for transforming AI text
- **[Tools Setup Guide](docs/Humanization_Tools_Setup.md)** — Recommended tools and budget breakdowns
- **[Quick Reference](docs/Humanization_Quick_Reference.md)** — Cheat sheet for fast fixes
## Philosophy
This tool isn't about fooling detectors — it's about writing better.
The same patterns that trigger AI detectors (robotic tone, uniform structure, missing personality) also make writing *worse*. Whether a human or AI wrote it, text without voice is text nobody wants to read.
Use this tool to:
1. **Understand** why text sounds robotic
2. **Learn** what makes writing human
3. **Improve** your writing habits over time
## License
MIT
---
**Built by [LXGIC Studios](https://lxgicstudios.com)**
🔗 [GitHub](https://github.com/lxgicstudios/humanize-cli) · [Twitter](https://x.com/lxgicstudios)
💡 **Want more free tools like this?** We have 100+ on our GitHub: [github.com/lxgicstudios](https://github.com/lxgicstudios)