Skip to content

README.md

Latest commit

 

History

History
239 lines (160 loc) · 7.99 KB

README.md

File metadata and controls

239 lines (160 loc) · 7.99 KB
Raw

Claude Organize

Intelligent document organization for Claude Code

npm version npm downloads License: MIT CI

NPM Package: https://www.npmjs.com/package/claude-organize

The Messy File Problem 🗂️

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

How Claude Organize Helps

🗂️ Automatic File Organization

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

Quick Start

Installation

npm install -g claude-organize

Setup File Organization

You have two options to configure the file organization hook:

Option 1: Using Claude's /hooks command (Recommended)

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 configured

Option 2: Manual Configuration

Add to your .claude/settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [{ "type": "command", "command": "claude-organize" }]
      }
    ]
  }
}

How This Complements Claude Code Best Practices

According 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 /clear and perfect CLAUDE.md setup, Claude still creates files in root. Our hooks ensure consistent organization.

Think of it this way:

  • Best Practices: Organize your kitchen (hierarchical CLAUDE.md)
  • Claude Organize: Clean as you cook (hooks)

Both approaches work together for optimal Claude Code workflows.

Key Features

✅ 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

Architecture

How It Works

Architecture Overview

File Organization: User → Claude Code → Hook → claude-organize → AI → Organized Files

View all architecture diagrams →

Documentation

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

Categories

Files are automatically organized into these directories:

Documentation

  • docs/testing/ - Test results, QA reports
  • docs/analysis/ - Data analysis, performance reports
  • docs/architecture/ - System design, technical docs
  • docs/operations/ - Deployment guides, runbooks
  • docs/troubleshooting/ - Debug logs, issue investigations

Scripts

  • scripts/checks/ - Verification and validation utilities
  • scripts/testing/ - Test scripts and runners
  • scripts/deployment/ - Deployment and release scripts
  • scripts/utilities/ - General utility scripts
  • + 6 more subcategories

Common Scenarios

The "Create and Run" Learning Curve

Learning Curve

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:

  1. First time: Claude learns files don't stay at root
  2. Second time: Claude checks where files went (find . -name "test-email.mjs")
  3. Third time: Claude runs directly from organized location

Just like training a junior developer: "Test files go in the test directory."

Why This Matters

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

Slash Commands

  • /claude-organize-bypass - Toggle file organization on/off
  • /claude-organize-add <pattern> - Add patterns to be organized
  • /claude-organize-js - Enable JavaScript organization (experimental)

Safety & Disclaimers

⚠️ USE AT YOUR OWN RISK: Claude Organize moves files in your project. Always use version control and test in a safe environment first.

  • ✅ Use version control (Git) before enabling
  • ✅ Test in a safe environment first
  • ✅ Review the organization log at docs/organization-log.json

Contributing

We welcome contributions! Please see our Contributing Guide for details.

License

Distributed under the MIT License. See LICENSE for more information.

Related Projects

  • cc-enhance - Prompt enhancement with contrarian analysis for Claude Code
    • Transform vague requests into comprehensive, context-aware prompts
    • Adds contrarian analysis to challenge assumptions early
    • Use both tools together for the complete Claude Code experience!

Support

Made with ❤️ by Rama Annaswamy