NPM Package: https://www.npmjs.com/package/claude-organize
Claude Organize solves two critical problems when working with Claude Code:
Claude Code creates files everywhere. Despite CLAUDE.md instructions saying "don't create scripts in the root directory," it keeps creating test files, debug scripts, and documentation right at your project root:
my-project/
├── test-api-v1.md # First attempt
├── test-api-v2.md # "Fixed" version
├── test-api-final.md # "Final" version
├── test-api-final-FIXED.md # Actually final?
├── debug-webhook.mjs # Quick test script
├── analyze-performance.mjs # Debugging session
└── ... (87 more files at root!)
Solution: Automatic file organization using AI-powered categorization
Claude Code struggles to maintain project context throughout conversations. You have a detailed CLAUDE.md with project rules, but Claude often:
- Forgets project guidelines mid-conversation
- Ignores file organization rules when creating new files
- Loses track of coding standards over time
- Requires constant reminders about project conventions
Example: You ask "fix the broken tests" and Claude doesn't remember your rule: "NEVER claim success if tests are failing"
Solution: The /enhance command transforms vague requests into comprehensive, context-aware prompts
Before (what you type):
fix the broken tests
After /enhance (what Claude receives):
Enhanced Prompt: Fix the Broken Tests
DETECTED TASK TYPE:
Primary intent: Debugging
Relevant contexts: testing, code-quality
CONTEXT & MOTIVATION:
Tests are failing and need immediate attention. Broken tests block deployments
and reduce confidence in the codebase. Each test failure needs systematic
investigation to find root causes, not just symptom fixes.
CONTRARIAN ANALYSIS:
- Are tests failing due to code bugs or test environment issues?
- Could recent dependency updates have broken tests?
- Are the tests themselves flawed rather than the code?
- Should we fix or remove outdated tests?
PROJECT RULES (from CLAUDE.md):
- NEVER claim success if tests are failing
- ALWAYS verify functionality before declaring completion
- Document changes appropriately
REQUIREMENTS:
- Run full test suite to see current state
- Analyze each failure for root cause
- Fix underlying issues, not just symptoms
- Verify no regression in other tests
- Run lint and typecheck after changes
SUCCESS CRITERIA:
- [ ] All tests pass without warnings
- [ ] Root causes documented
- [ ] No regression in existing tests
- [ ] Lint and typecheck pass
💡 Pro Tip: Use Shift+P (plan mode) with /enhance to review the enhanced prompt before execution
- Reads CLAUDE.md - Automatically finds and incorporates your project rules
- Detects Task Type - Analyzes keywords to understand what you're trying to do
- Adds Contrarian Analysis - Questions assumptions early to prevent wasted effort
- Maps to MCP Tools - Recommends appropriate tools like mcpzen* for analysis
- Generates Structured Prompt - Creates comprehensive requirements with success criteria
- Presents for Review - Shows the enhanced prompt in plan mode for your approval
The enhance command ensures Claude understands not just what you want, but also your project's specific requirements, potential pitfalls, and success criteria.
my-project/
├── src/ # Source code stays untouched
├── docs/
│ ├── testing/ # Test results organized
│ └── troubleshooting/ # Debug notes in one place
└── scripts/
├── checks/ # Validation scripts grouped
└── debug/ # Debug utilities together
# Your vague request
/enhance fix the broken tests
# What happens:
✓ Analyzes your request to understand the task type
✓ Extracts ONLY relevant rules (e.g., testing rules for test tasks)
✓ Creates a comprehensive but concise specification
✓ Adds necessary context without bloating
# Example - from 100-line CLAUDE.md, only extracts:
✓ "NEVER claim success if tests are failing"
✓ "ALWAYS verify functionality before declaring completion"
✓ Ignores unrelated rules about file naming, deployment, etc.npm install -g claude-organizeYou have two options to configure the file organization hook:
Use Claude Code's built-in /hooks command to configure:
# Step 1: Type the /hooks command
/hooks
# Step 2: Select "PostToolUse" from the menu
# Step 3: Enter the matcher pattern:
Write|Edit|MultiEdit
# Step 4: Select "command" as the hook type
# Step 5: Enter the command:
claude-organize
# Step 6: Press Enter to confirm
# Step 7: Press Esc twice to exit the menu
# That's it! The hook is now configuredAdd to your .claude/settings.json:
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit|MultiEdit",
"hooks": [{ "type": "command", "command": "claude-organize" }]
}
]
}
}The /enhance command is automatically installed to ~/.claude/commands/ and ready to use:
/enhance create a deployment guide
# → Comprehensive prompt with relevant CLAUDE.md rules includedAccording to Claude Code Best Practices, the recommended approaches include:
- Hierarchical CLAUDE.md files - Great for static organization in monorepos
- Shorter sessions with /clear - Helps manage context effectively
- Using subagents - Reduces context usage for complex tasks
Claude Organize complements these practices:
-
File Organization (Hooks) - Works regardless of session length. Even with
/clearand perfect CLAUDE.md setup, Claude still creates files in root. Our hooks ensure consistent organization. -
The
/enhanceCommand - Bridges the gap between static rules and dynamic application:- Hierarchical CLAUDE.md = Foundation (what rules exist)
/enhance= Application (which rules apply now)- Perfect for planning mode where context often gets lost
-
Just-in-Time Context - Instead of hoping Claude remembers rules from startup or manually reminding it,
/enhancesurgically injects only the relevant 2-5 rules exactly when needed.
Think of it this way:
- Best Practices: Organize your kitchen (hierarchical CLAUDE.md)
- Claude Organize: Clean as you cook (hooks) + grab the right tools (enhance)
Both approaches work together for optimal Claude Code workflows.
✅ Automatic cleanup - Files move to proper directories instantly
✅ AI categorization - Understands file purpose from content
✅ 10 script subcategories - Detailed organization for scripts
✅ Safe defaults - Protects README, LICENSE, configs
✅ Context reduction - Cleaner workspace = better Claude performance
✅ Two-pass enhancement - First expands using Claude's best practices, then adds CLAUDE.md rules
✅ Prompt engineering - Transforms vague requests into comprehensive specifications
✅ Context engineering - Selects only relevant project rules
✅ CLAUDE.md integration - Automatically includes applicable guidelines
✅ Smart detection - Understands task type from your request
✅ Efficient prompts - No rule dumping, only what's needed
✅ Works in plan mode - Compatible with Claude's planning features
File Organization: User → Claude Code → Hook → claude-organize → AI → Organized Files
Prompt Enhancement: User → /enhance → Reads CLAUDE.md → Context Analysis → Enhanced Prompt
- Hooks: Automatic, background file organization
- Slash Commands: Interactive, user-initiated enhancements
View all architecture diagrams →
| Guide | Description |
|---|---|
| 📖 Full Documentation | Complete feature guide and API reference |
| 🚀 Quick Start | Get up and running in 5 minutes |
| 📂 Subcategories Guide | Script organization patterns |
| ⚙️ Configuration | Customize behavior and settings |
| 🔧 JavaScript Organization | Experimental JS/MJS features |
| 🛠️ Troubleshooting | Common issues and solutions |
Files are automatically organized into these directories:
docs/testing/- Test results, QA reportsdocs/analysis/- Data analysis, performance reportsdocs/architecture/- System design, technical docsdocs/operations/- Deployment guides, runbooksdocs/troubleshooting/- Debug logs, issue investigations
scripts/checks/- Verification and validation utilitiesscripts/testing/- Test scripts and runnersscripts/deployment/- Deployment and release scriptsscripts/utilities/- General utility scripts- + 6 more subcategories
You might encounter this scenario:
Claude: "I'll create test-email.mjs and run it"
*Creates file*
*File gets organized to scripts/testing/*
Claude: "Error: Cannot find module './test-email.mjs'"
This is intentional! The friction teaches Claude (and us) better habits:
- First time: Claude learns files don't stay at root
- Second time: Claude checks where files went (
find . -name "test-email.mjs") - Third time: Claude runs directly from organized location
Just like training a junior developer: "Test files go in the test directory."
Pro tip: Use /enhance to help Claude understand the project structure:
/enhance create and test email functionality
# The enhanced prompt will:
# - Extract only relevant CLAUDE.md rules (not the entire file)
# - Add necessary context and structure
# - Include project-specific conventions
# - Create a comprehensive but concise planThe /enhance command has been optimized to be "comprehensive but concise" - adding only necessary detail instead of arbitrary expansion. It performs surgical context injection, selecting just the 2-5 most relevant rules from your CLAUDE.md instead of dumping everything.
The housekeeper doesn't compromise on cleanliness. This "friction" is actually a feature:
- Claude learns project structure through experience
- Better long-term habits > short-term convenience
- Consistent organization > temporary files at root
/claude-organize-bypass- Toggle file organization on/off/claude-organize-add <pattern>- Add patterns to be organized/claude-organize-js- Enable JavaScript organization (experimental)
- ✅ Use version control (Git) before enabling
- ✅ Test in a safe environment first
- ✅ Review the organization log at
docs/organization-log.json
We welcome contributions! Please see our Contributing Guide for details.
Distributed under the MIT License. See LICENSE for more information.
- 📝 Report Issues
- 💬 Discussions
- 📧 Contact