Intelligent repository cleanup with auto mode, AI learning, markdown consolidation, auto-consolidate workflow, context-aware classification, and cost optimization
npm install devibeRepository cleanup utility for vibe coding sessions
Quick Links:
- ๐ Documentation Index - Complete project documentation
- ๐ง Scripts Index - All available scripts and tools
Stop the chaos after intense AI-assisted coding sessions. UnVibe intelligently organizes your repositories, respects git boundaries, and keeps your monorepos clean.
Choose your workflow: Compress (clean everything) or Document-Archive (organize and preserve).
``bashCOMPRESS MODE (default): Consolidate + clean up
devibe consolidate:autoโ Clean root with only consolidated file + README
โ AI automatically includes related .txt, .log files
โ Cleans up UUID backup artifacts
Features:
- ๐๏ธ Compress Mode: Consolidates all .md files into one, backs up, deletes originals
- ๐ฆ Archive Mode: Moves files to
./documents/ with AI organization, preserves originals
- ๐ค AI File Selection: --include-related lets AI decide which .txt/.log files to include
- ๐ Recursive Processing: --recursive-compress for nested git boundaries
- ๐ฏ Smart Defaults: Compress = 1 file, Archive = organized folders
- ๐พ Full Safety: All originals backed up in .devibe/backups/
- ๐ BACKUP_INDEX.md: Track what was changed for easy restoration$3
Fully automated markdown consolidation workflow that respects git repository boundaries!
`bash
Auto-consolidate current directory (respects git boundaries)
devibe consolidate:autoProcess monorepo - each nested repo processed independently
devibe consolidate:auto /path/to/monorepoWith options
devibe consolidate:auto --max-output 3 --suppress-toc
`Key Features:
- ๐ Git-aware - Automatically detects and processes each git repo independently
- ๐ฏ Monorepo support - Handles nested repositories like a pro
- ๐ Multi-repo reporting - Shows count of repositories processed
- ๐ Automated workflow - Moves files, consolidates, updates README automatically
- ๐ท๏ธ Intelligent naming - Output files named based on content topics
- ๐ README integration - Auto-updates README.md with summary index
- ๐พ Backup tracking - Creates date-sorted BACKUP_INDEX.md in
.devibe/
- ๐ค AI optional - Works with or without AI configuration
- ๐ก๏ธ 100% safe - All originals preserved, full rollback capabilityPerfect for:
- Repository cleanup after AI coding sessions
- Weekly/sprint documentation snapshots
- Monorepo documentation management
- Preparing consolidated docs for AI assistants
---
๐ Markdown Consolidation
Advanced AI-powered markdown consolidation for interactive workflows.
---
Features
$3
โ
Mono-repo friendly - Respects multiple .git boundaries
โ
Secret detection - Scans for 31 types of hardcoded secrets (API keys, tokens, credentials)
โ
100% reversible - All operations backed up automatically with restore capability
โ
Build validation - Ensures cleanup doesn't break builds (Node.js, Docker, Python, Go)
โ
Dry-run mode - Preview changes before applying across all commands $3
โ
Multi-provider AI - Support for Anthropic Claude, OpenAI GPT, Google Gemini (7 models)
โ
90% accuracy - AI-powered file classification with context awareness
โ
Learning system - Learns from corrections and improves over time
โ
Cost optimization - 98% savings with smart model selection (Gemini Flash vs Claude Sonnet)
โ
Secure keys - AES-256 encrypted API key storage in ~/.devibe/ $3
โ
Auto mode - One-command cleanup: devibe --auto or devibe yolo
โ
Intelligent classification - Multi-stage: learning โ structure โ dependencies โ AI
โ
GitIgnore management - Auto-excludes .devibe/ and .unvibe/ directories
โ
GitHub integration - Pre-push hooks and Actions for CI/CD
โ
Progress tracking - Real-time feedback with detailed status updates $3
โ
8 test categories - unit, integration, e2e, tdd, functional, performance, acceptance, contract
โ
6 technology stacks - Node.js, React, Python, Go, Java, .NET/C#
โ
Smart detection - Automatic pattern matching and categorization
โ
Organization reports - Detailed breakdown by category and technology $3
โ
Best practices analyzer - 40+ automated checks across 8 categories
โ
Rule packs - Shareable directory structure standards (YAML/JSON)
โ
Weighted scoring - 0-100 quality score with severity levels
โ
Auto-fix detection - Identifies issues that can be automatically resolved
โ
CI/CD ready - JSON output for automation pipelines $3
โ
Project convention analysis - Auto-detects existing docs/, scripts/, and root file conventions
โ
Intelligent indexing - Creates smart docs/INDEX.md and scripts/INDEX.md with categorization
โ
Folder conflict resolution - Interactive merge when both docs/ and documents/ exist
โ
README AI integration - Adds AI-visible navigation instructions to guide assistants
โ
Important file protection - Never consolidates README, CHANGELOG, CONTRIBUTING, LICENSE
โ
Markdown consolidation - AI-powered doc organization with topic clustering
โ
Relevance analysis - Multi-factor scoring (recency, quality, connectivity)
โ
Smart strategies - Merge, summarize, archive, or create navigation hub
โ
Content preservation - Validation and backup with rollback capability $3
โ
Non-intrusive UX - Smart prompting (max 2 times, then silent)
โ
Folder enforcement - Maintains scripts/ and documents/ structure
โ
Helpful recommendations - Context-aware suggestions for improvements
โ
Comprehensive docs - 20+ guides covering all features and workflowsInstallation
$3
`bash
Install globally
npm install -g devibeOr use with npx (no installation)
npx devibe
`$3
`bash
devibe --version
Should show: 1.8.7
devibe --help
Shows all available commands
`NPM Package: https://www.npmjs.com/package/devibe
Quick Start
`bash
Quick auto-organize (recommended!)
devibe --auto
or
devibe yoloShow repository status
devibeScan for secrets before commit
devibe scanPlan file distribution
devibe planExecute with backup
devibe executeEnforce folder structure
devibe enforceValidate builds
devibe validateCheck repository best practices
devibe best-practicesValidate a rule pack file
devibe validate-rulepack my-pack.jsonConsolidate markdown documentation (NEW in v1.7.0!)
devibe consolidate ./docs --dry-run
`$3
Devibe intelligently detects and respects your existing folder structure:
#### Automatic Detection Rules:
For documentation:
- If only
docs/ exists โ uses it automatically
- If only documents/ exists โ uses it automatically
- If both exist โ prompts you once, saves preference to .devibe/config.jsonFor scripts:
- If only
scripts/ exists โ uses it automatically
- If only script/ exists โ uses it automatically
- If both exist โ prompts you once, saves preference to .devibe/config.json#### Conflict Resolution Prompt:
When both folders exist, you'll see this once per project:
Documentation folders:
`
โ ๏ธ Found both docs/ and documents/ foldersOptions:
1. Use docs/ folder (skip documents/)
2. Use documents/ folder (skip docs/)
3. Merge documents/ โ docs/ (move all files)
4. Merge docs/ โ documents/ (move all files)
5. Skip indexing for now
Choose option (1-5):
โ Saved preference: docs/
`Scripts folders:
`
โ ๏ธ Found both script/ and scripts/ foldersOptions:
1. Use scripts/ folder (skip script/)
2. Use script/ folder (skip scripts/)
3. Merge script/ โ scripts/ (move all files)
4. Merge scripts/ โ script/ (move all files)
5. Skip indexing for now
Choose option (1-5):
โ Saved preference: scripts/
`#### How Preferences Work:
1. First time: Devibe detects conflict and prompts you
2. You choose: Select option 1-4 (saved to
.devibe/config.json)
3. Future runs: Uses saved preference automatically, no prompt
4. Project-specific: Each project remembers its own preferenceThis ensures:
- โ
Zero prompts when only one folder exists (automatic)
- โ
One prompt when both exist (saves your choice)
- โ
Zero prompts on future runs (uses saved preference)
- โ
Files merged intelligently (preserves existing files, skips duplicates)
- โ
Project-specific preferences in
.devibe/config.jsonCommands
$3
Show repository status and suggested next actions.$3
List all git repositories in the current directory.$3
Scan for hardcoded secrets (API keys, passwords, tokens).Detects 31 types: AWS, Google, Azure, Stripe, GitHub, Slack, Discord, Anthropic, OpenAI, SendGrid, Twilio, Heroku, Firebase, NPM, Docker, Cloudflare, Datadog, and more. Plus JWT tokens, private keys, webhooks, and database credentials.
$3
Plan root file distribution (shows what would be done).$3
Execute planned file operations with automatic backup.`bash
devibe execute --dry-run # Preview without making changes
`$3
Enforce folder structure (scripts/, documents/).$3
Detect and validate build systems (Node.js, Docker, Python, Go).$3
List all available backups.$3
Restore from a backup.$3
Quick auto-organize: Run full cleanup workflow automatically.These commands are equivalent - use whichever you prefer!
What
--auto does:
- ๐ Git-aware scanning - Detects and processes each git repository independently (perfect for monorepos)
- ๐ค AI-powered classification - Intelligently categorizes files using AI or heuristics fallback
- ๐ Automated organization - Plans and executes file distribution to proper folders
- ๐ Secret detection - Scans for 31 types of hardcoded credentials before organizing
- ๐ GitIgnore management - Automatically updates .gitignore to exclude .devibe/ directories
- ๐พ 100% reversible - All operations backed up automatically with full rollback capability
- โก One command cleanup - Complete repository organization in secondsPerfect for:
- Post-coding session cleanup
- Repository maintenance before commits
- Preparing repos for team collaboration
- Cleaning up after AI-assisted coding sessions
AI Key Handling:
- If no AI key is configured, you'll be prompted to add one (first 2 times only)
- After declining twice, the tool will silently use heuristics to avoid being annoying
- You can continue with heuristics (65% accuracy) or add a key for AI (90% accuracy)
- Use
devibe ai-key add to configure AI
- Re-enable prompts with: devibe ai-key reset-promptโ ๏ธ Note: This mode makes automatic changes but always creates backups first.
$3
Quick commands:
`bash
devibe --auto # Quick auto-organize (same as yolo)
devibe yolo # Quick auto-organize (same as --auto)
devibe --auto --no-ai # Force heuristics only (skip AI prompt)
`Advanced commands:
`bash
devibe plan --auto # Preview AI organization
devibe execute --auto # Execute AI organization
devibe execute --auto --no-ai # Execute with heuristics only
`When to use:
- ๐ค
devibe --auto or devibe yolo: Quick cleanup with AI (recommended)
- โก devibe --auto --no-ai: Fast cleanup without AI prompts
- ๐ devibe plan --auto: Preview before executing
- See AI Auto Mode Guide for details$3
Initialize UnVibe configuration file.$3
Organize test files by category (unit, integration, e2e, etc.).`bash
devibe organize-tests # Move tests to organized directories
devibe organize-tests --dry-run # Preview changes
devibe organize-tests --report # Generate organization report
`0$3
List all test files and their categories.$3
Analyze repository against industry best practices (40+ automated checks).`bash
devibe best-practices # Run analysis
devibe best-practices --json # Output JSON for CI/CD
`Checks include:
- ๐ Documentation (README, CHANGELOG, API docs)
- ๐ง Git (.gitignore, .gitattributes)
- ๐ Security (.env management, lockfiles, SECURITY.md)
- ๐ Structure (src/, tests/, no root files)
- ๐ฆ Dependencies (engines, no wildcards)
- ๐ CI/CD (GitHub Actions, pre-commit hooks)
- โ๏ธ Licensing (LICENSE file, package.json)
- โจ Quality (ESLint, Prettier, TypeScript, EditorConfig)
Scoring: Weighted 0-100 score with severity levels (critical, high, medium, low)
$3
Validate a rule pack file against the specification.`bash
devibe validate-rulepack my-pack.json
`Provides clear, helpful error messages with:
- JSONPath location (
$.metadata.name)
- Expected format with examples
- Error codes for automation
- Warnings for best practices$3
Consolidate markdown documentation using AI-powered semantic analysis.
`bash
Preview consolidation (RECOMMENDED FIRST!)
devibe consolidate ./docs --dry-runInteractive consolidation
devibe consolidate ./docs -rAuto-consolidate with AI
devibe consolidate ./docs --auto -r --max-output 5Exclude patterns
devibe consolidate ./docs -r --exclude '/archive/' --exclude '/old/'
`How it works:
1. ๐ Scans directory for markdown files
2. ๐ Analyzes relevance (recency, quality, connectivity, uniqueness)
3. ๐ค Clusters files by semantic similarity using AI
4. ๐ Creates plan with consolidation strategies
5. ๐พ Backs up originals automatically
6. โ
Validates content preservation (max 30% loss allowed)
7. ๐ Generates
DOCUMENTATION_HUB.md navigation hubConsolidation Strategies:
- merge-by-topic - Combine files on same topic
- merge-by-folder - Combine files in same directory
- summarize-cluster - Create AI-powered summaries
- create-super-readme - Generate navigation hub
- archive-stale - Move outdated files to archive
Relevance Scoring:
- Highly Relevant (70-100) - Recent, high-quality, well-connected
- Relevant (50-69) - Good quality, some connections
- Marginal (30-49) - Consider consolidating or archiving
- Stale (0-29) - Old, low quality, candidates for archiving
Safety Features:
- ๐ก๏ธ Always run with
--dry-run first to preview
- ๐พ Automatic backups before any changes
- โ
Content preservation validation
- ๐ Broken link detection
- ๐ Full rollback with devibe restoreOptions:
-
-r, --recursive - Process subdirectories
- --max-output - Maximum consolidated files (default: 5)
- --dry-run - Preview without changes (RECOMMENDED)
- --auto - Auto-approve plan (use with caution)
- --exclude - Exclude file patterns (repeatable)โ ๏ธ Important: Requires AI to be enabled. Run
devibe ai-key add first.$3
NEW in v2.0.0 Two powerful modes for markdown organization!
#### Compress Mode (Default) - Clean Up Everything
Consolidates all .md files into one, backs them up, and deletes originals. Perfect for cleaning up doc clutter.
`bash
Default compress mode - consolidates and cleans up
devibe consolidate:autoProcess all git boundaries recursively
devibe consolidate:auto --recursive-compressWith options
devibe consolidate:auto --max-output 1 --suppress-toc
`Workflow:
1. ๐ Consolidates all
*.md files directly from root into one file
2. ๐พ Backs up originals to .devibe/backups/
3. ๐๏ธ Deletes original .md files (safely backed up)
4. ๐ Updates README.md with summary
5. ๐ท๏ธ Creates BACKUP_INDEX.md for restoration trackingResult:
- Clean root with only consolidated file + README.md
- All originals safely backed up
- Respects git boundaries (each repo processed independently)
#### Document-Archive Mode - Organize Into Folders
Moves files to
./documents/ with AI organization. Perfect for archiving scattered docs.`bash
Archive mode - move and organize
devibe consolidate:auto --document-archiveWith options
devibe consolidate:auto --document-archive --max-output 3
`Workflow:
1. ๐ Moves all
*.md files from root โ ./documents/
2. ๐ค Organizes with AI into proper subdirectories (if enabled)
3. โ๏ธ Creates consolidated summary in root
4. ๐ Updates README.md
5. โ
Preserves documents folder (not deleted)Result:
- Original files preserved in organized
./documents/ folder
- Summary file in root for quick reference
- README updated with documentation index---
Git-Aware:
- ๐ Automatically detects git repository boundaries
- ๐ฏ Processes each git repo independently
- โ
Respects monorepo structures with nested repos
- ๐
--recursive-compress processes ALL boundaries recursivelySafety:
- โ
All original files backed up in
.devibe/backups/
- โ
Automatic BACKUP_INDEX.md for tracking
- โ
README.md safely updated with HTML markers
- โ
Full rollback with devibe restoreOptions:
-
--document-archive - Archive mode (preserves documents/ folder)
- --recursive-compress - Compress mode: process all git boundaries
- --no-include-related - Disable AI file analysis (enabled by default)
- --max-output - Maximum output files (default: 1 compress, 5 archive)
- --suppress-toc - Suppress Table of Contents generation๐ค AI-Powered File Selection (ENABLED BY DEFAULT)
AI automatically decides which additional files (.txt, .log) should be included:
`bash
Default behavior - AI analyzes related files automatically
devibe consolidate:autoDisable AI file selection if you don't want it
devibe consolidate:auto --no-include-related
`What it does (automatically):
- ๐ Scans for
.txt, .log files in root directory
- ๐ค Uses AI to analyze each file's content
- โ
Automatically includes documentation-related files
- ๐ Shows AI reasoning for each inclusion
- ๐งน Cleans up UUID backup artifacts from rootExample output:
`
โ COMMIT_MESSAGE.txt: detailed commit message with features
โ WEEK_4_SUMMARY.txt: project summary and accomplishments
โ PHASE_2_SUMMARY.txt: phase completion documentation๐ AI Analysis: Including 8 related files
๐งน Cleaned up 12 backup artifact(s) from root
`Use Cases:
- Compress: Weekly cleanup, preparing AI context, milestone snapshots
- Archive: Long-term organization, documentation hub, knowledge base
๐ง AI Optional: Works with or without AI (uses smart fallback clustering)
$3
Manage AI providers, keys, and cost optimization.
####
devibe ai-key add
Add an AI API key (encrypted with AES-256).`bash
devibe ai-key add anthropic sk-ant-...
devibe ai-key add openai sk-...
devibe ai-key add google AIza...
`####
devibe ai-key status
Show current AI configuration and cost recommendations.`bash
devibe ai-key status
Shows active provider, model, and potential savings
`####
devibe ai-key clear
Revert to environment variables (removes configured keys).`bash
devibe ai-key clear
Falls back to ANTHROPIC_API_KEY or OPENAI_API_KEY
`####
devibe ai-analyze
Compare AI models and costs for your repository.`bash
devibe ai-analyze # Analyze current directory
devibe ai-analyze -f 5000 # Analyze for 5000 files
`Shows cost comparison across 7 AI models:
- Gemini 1.5 Flash (cheapest - $0.06/1K files)
- GPT-4o Mini
- Claude 3 Haiku
- Claude 3.5 Sonnet
- Gemini 1.5 Pro
- GPT-4o
- Claude 3.5 Opus (premium)
####
devibe ai-models
List all available AI models with pricing and context windows.`bash
devibe ai-models
`Test Organization
DeVibe can automatically organize your tests into logical categories:
`
tests/
โโโ unit/ # Unit tests
โโโ integration/ # Integration tests
โโโ e2e/ # End-to-end tests
โโโ tdd/ # TDD specs
โโโ functional/ # Functional tests
โโโ performance/ # Performance tests
โโโ acceptance/ # Acceptance tests
โโโ contract/ # Contract tests
`Supports 6 technologies:
- Node.js/TypeScript (
.test.ts, .spec.ts)
- React (.test.tsx, __tests__/)
- Python (test_.py, _test.py)
- Go (*_test.go)
- Java (Test.java, IT.java)
- .NET/C# (Tests.cs, Test.cs, xUnit/NUnit/MSTest)Rule Packs
Share and reuse directory structure standards across projects and teams.
$3
`bash
Install official rule pack
devibe rulepack install @devibe/nodejs-standardUse in your project
devibe --rulepack @devibe/nodejs-standardOr in .devibe.config.js
module.exports = {
rulepacks: ['@devibe/nodejs-standard']
};
`$3
-
@devibe/nodejs-standard - Standard Node.js structure
- @devibe/react-standard - React/Next.js conventions
- @devibe/nodejs-monorepo - NX/Turborepo monorepo structure
- @devibe/python-standard - Python best practices
- @devibe/go-standard - Go standard project layout$3
Create your own shareable standards:
`yaml
my-company-standard.yaml
schema: "devibe-rulepack/v1"
metadata:
name: "@mycompany/engineering-standard"
version: "1.0.0"structure:
requiredFolders:
- path: "src"
- path: "tests"
- path: "docs"
testOrganization:
enabled: true
categories:
- name: "unit"
patterns: ["*/.test.ts"]
targetDirectory: "tests/unit"
`See RULE_PACK_SPEC.md for complete specification.
Configuration
Create
.unvibe.config.js in your repository root:`javascript
module.exports = {
secretScan: {
excludePatterns: ['node_modules/', '.git/'],
},
folderStructure: {
requiredFolders: ['scripts', 'documents'],
},
ai: {
enabled: false,
provider: 'anthropic', // or 'openai'
},
backup: {
enabled: true,
retentionDays: 30,
}
};
`AI Integration (Optional)
For better file classification (90% vs 65%):
`bash
export ANTHROPIC_API_KEY=your-key-here
or
export OPENAI_API_KEY=your-key-here
`UnVibe automatically detects AI availability and provides helpful recommendations when features are unavailable.
Intelligent Recommendations
UnVibe provides smart, context-aware recommendations for common issues:
$3
`bash
$ devibe validate
โ nodejs: PASSED (0ms)
โ ๏ธ No build script found in package.json
Skipping build validation (not blocking)
To enable: Add "build": "tsc" or your build command to package.json scripts
`$3
`bash
$ devibe validate
โ nodejs: FAILED (499ms)
๐ก Build failed. Possible fixes:
โข Run "npm install" to ensure dependencies are installed
โข Check for TypeScript errors if using tsc
โข Review build script in package.json
โข Run "npm run build" manually to see full error
`$3
`bash
$ devibe plan
โ ๏ธ AI classification unavailable - using heuristics (65% accuracy)
For better results: Set ANTHROPIC_API_KEY or OPENAI_API_KEY
`$3
`bash
$ devibe status
๐ UnVibe StatusAI Classification:
โ ๏ธ AI unavailable - using heuristics (65% accuracy)
To enable: Set ANTHROPIC_API_KEY or OPENAI_API_KEY environment variable
Build Configuration:
โ ๏ธ No build script found
To enable validation: Add "build" script to package.json
`The app never blocks on missing optional features - it provides helpful guidance while continuing to work.
Safety Guarantees
1. Git boundaries respected - Never moves files between sibling repos
2. All operations backed up - 100% reversible
3. Secrets are truncated - Never logged in full
4. Dry-run available - Test before applying
5. Build validation - Ensures code still works
6. Permission preserved - File modes maintained
Architecture
- TDD - Test-Driven Development
- ISP - Interface Segregation Principle
- 86 passing tests - E2E coverage
- TypeScript - Fully typed
- Zero runtime dependencies
GitHub Integration
UnVibe integrates with GitHub to keep your
main branch clean:`bash
Setup git hooks (auto-runs on push)
devibe setup-hooksCheck before pushing
devibe check-pr
`Features:
- โ
Pre-push hooks block critical secrets
- โ
GitHub Actions validate PRs
- โ
Automated PR comments with results
- โ
Prevents broken builds on main
See GITHUB-INTEGRATION.md for full guide.
Documentation
documents/ directory:๐ View Full Documentation Index โ
$3
- AI & Setup:
- AI Setup Guide - Get started with AI features
- AI Auto Mode Guide - Automatic organization
- Auto Mode Quick Reference - Quick commands
- Architecture:
- Architecture Overview - System design
- Specifications - Technical specs
- Requirements - Feature requirements
- Reference:
- Quick Reference - Command cheat sheet
- Changelog - Version history
- Rule Pack Spec - Custom rule packs
๐ก Tip: The
documents/ folder contains 20+ guides. Check documents/README.md for the complete organized index.Development
`bash
npm install
npm test
npm run build
``ISC License
---
UnVibe - Because every vibe coding session deserves a clean ending. ๐
Made with Claude Code