Diff Wizard (diff-wizard)
Smart text comparison beyond traditional diff / git diff. Detects semantic differences in JSON, YAML, CSV, code, and plain text with format-aware comparison strategies, AI-powered natural-language explanations, and 3-way merge conflict resolution.
Quick Start
clawhub run diff-wizard --help # Show usage
clawhub run diff-wizard a.json b.json # Compare two files
clawhub run diff-wizard --paste # Paste content to compare
clawhub run diff-wizard --merge base ours theirs # 3-way merge
clawhub run diff-wizard ./dir-a/ ./dir-b/ # Compare directories
First-Success Path
Step 1: Install → clawhub install diff-wizard
Step 2: Run → clawhub run diff-wizard file-v1.json file-v2.json
Step 3: See diff → Color-coded terminal output with AI explanation (<10 seconds)
Step 4: Explore → Try --paste mode for clipboard-based comparison
Features
| Feature | Description |
|---|---|
| Format-aware diffing | Auto-detect JSON, YAML, CSV, TOML, code, text, XML/HTML — applies optimal comparison strategy per format |
| Structured comparison | Field-level diff for JSON/YAML, row/column for CSV, semantic diff for code, DOM for XML |
| Terminal color output | 🟢 green (added), 🔴 red (deleted), 🟡 yellow (modified) with side-by-side or unified format |
| AI explanation | LLM-powered natural-language explanation of complex diffs, configurable language (zh-CN/en-US) |
| 3-way merge | base + ours + theirs merge with conflict markers, AI merge suggestions per conflict |
| Directory diff | Recursive directory comparison with aggregate stats and per-file diff reports |
| Multiple output formats | Terminal, unified diff, markdown, HTML, JSON |
| Security first | Local-only processing, sensitive file detection, credential redaction, path traversal protection |
Input Modes
File Comparison
clawhub run diff-wizard config-v1.json config-v2.json
clawhub run diff-wizard --ignore-whitespace old.js new.js
clawhub run diff-wizard --output markdown --context-lines 5 a.yaml b.yaml
Paste Mode (interactive)
clawhub run diff-wizard --paste
Directory Comparison
clawhub run diff-wizard ./env/dev/ ./env/staging/ --exclude "node_modules,.git,*.log"
clawhub run diff-wizard ./config-v1/ ./config-v2/ --recursive --sort
3-Way Merge
clawhub run diff-wizard --merge base.json ours.json theirs.json
clawhub run diff-wizard --merge --auto-resolve --output merged.ts base.ts ours.ts theirs.ts
Options
| Option | Default | Description |
|---|---|---|
--format |
auto | Force format: json, yaml, csv, toml, xml, code, text |
--output |
terminal | Output: terminal, unified, side-by-side, markdown, html, json |
--context-lines |
3 | Context lines around diffs (0-99) |
--ignore-whitespace |
false | Ignore whitespace-only changes |
--ignore-case |
false | Ignore case differences |
--ignore-comments |
false | Ignore comment changes |
--sort-keys |
false | Sort JSON/YAML keys before comparison |
--ai-explain |
true | Enable/disable AI explanation |
--ai-language |
auto | AI explanation language: zh-CN, en-US |
--detail-level |
normal | Diff granularity: summary, normal, detailed |
--color |
true | Terminal color output |
--no-color |
false | Disable color output |
--exclude |
— | Exclude patterns (comma-separated, for dir mode) |
--max-depth |
99 | Max directory recursion depth |
--auto-resolve |
false | Auto-resolve non-conflicting 3-way merges |
--strategy |
manual | Conflict strategy: ours, theirs, manual |
Error Codes
| Code | Scenario | Handling |
|---|---|---|
| E001 | File not found | Show nearest match via Levenshtein |
| E002 | File exceeds size limit | Show file size + max_file_size_mb setting |
| E003 | Permission denied | Show permission error + fix suggestion |
| E004 | Empty input | Show error + usage example |
| E005 | Format detection failure | Fallback to plain text + warning |
| E006 | Parse error | Show precise location (line:col) + error reason |
| E007 | AI explanation failure | Skip AI, still return diff |
| E008 | 3-way merge conflict overflow | List conflicts + AI suggestions |
| E009 | Directory scan read failure | Skip file + annotate in report |
| E010 | CSV parse failure | Fallback to plain text diff |
| E011 | Encoding detection failure | Try UTF-8 / GBK / UTF-16 fallback |
Sample Prompts
1. Quick file comparison
clawhub run diff-wizard before.json after.json
Expected output:
📄 Comparing before.json ↔ after.json (format: json)
🔴 removed: "deprecated_field"
🟢 added: "new_feature_enabled": true
🟡 changed: "version": "1.0.0" → "2.0.0"
🟡 changed: "timeout_ms": 5000 → 30000
📊 Summary: 1 removed, 1 added, 2 changed
💡 AI: "Version bumped from 1.0 to 2.0, deprecated_field removed,
new_feature_enabled added, timeout increased 6x."
2. Paste mode
clawhub run diff-wizard --paste
Expected output:
📋 Paste Mode — paste the first text block, press Enter, then Ctrl+D
[Paste content A...]
📋 Now paste the second text block, press Enter, then Ctrl+D
[Paste content B...]
🔴 removed: line 3
🟢 added: line 7
🟡 changed: line 5 "old" → "new"
📊 3 differences found
3. 3-way merge with AI suggestions
clawhub run diff-wizard --merge base.ts ours.ts theirs.ts --ai-explain
Expected output:
🔀 3-Way Merge: base ← ours + theirs
✅ Auto-resolved (2): type User struct, import statement
⚠️ Conflicts (1):
[ours] name: string = "Alice"
[theirs] username: string = "Bob"
💡 AI suggests: "Prefer 'name' and merge both values with configurable default"
📄 Merged written to: merged.ts
4. Directory batch comparison
clawhub run diff-wizard ./env/dev/ ./env/staging/ --exclude "node_modules,.git,*.log"
Expected output:
📁 Comparing ./env/dev/ ↔ ./env/staging/ (recursive)
🔴 Only in dev/: local-overrides.yaml
🟢 Only in staging/: production-secrets.yaml
🟡 Modified: config.yaml (12 changes)
🟡 Modified: docker-compose.yaml (3 changes)
✅ Unchanged: 47 files
📊 Summary: 2 added, 1 removed, 2 modified, 47 unchanged
5. CSV data diff
clawhub run diff-wizard --format csv --output terminal prices-q1.csv prices-q2.csv
Expected output:
📊 Comparing prices-q1.csv ↔ prices-q2.csv (format: csv, 142 rows)
🟢 Added rows (3):
| SKU-109 | Widget Pro | $29.99 |
| SKU-110 | Widget Max | $49.99 |
| SKU-111 | Widget Lite | $12.99 |
🔴 Removed rows (1):
| SKU-042 | Old Widget | $9.99 |
🟡 Modified cells (7):
Row 23: $19.99 → $21.99
Row 56: $15.00 → $16.50
Row 78: "Widget" → "Widget v2"
... (4 more)
📊 Summary: 3 added, 1 removed, 7 cell changes, 132 unchanged
Implementation Notes
- Diff algorithm: Myers diff (O(ND)) for text; recursive DFS with key alignment for structured formats
- Format detection priority: Extension → content signature → MIME → fallback to text
- AI explanation: Only diff hunks (max 4000 chars) sent to LLM; credential patterns auto-redacted
- Sensitive file protection:
.env,credentials.*,*secret*,*.pem,*.key,id_rsa* - Path security: Prevents traversal attacks; restricted to working directory unless
--allow-system - All processing is local: Uses configured LLM for AI explanation, no external content sharing
Safety
- Never sends raw file content to external services
- Sensitive files trigger confirmation prompts before comparison
- AI explanation hunks are redacted for credential patterns
- HTML output sanitizes user content (HTML entity escaping)
- Terminal output filters malicious ANSI escape sequences
- Audit logs record AI explanation requests (path + timestamp only)