{"id":31211428,"url":"https://github.com/ramakay/claude-organizer","last_synced_at":"2025-09-21T05:05:42.137Z","repository":{"id":304924097,"uuid":"1020321525","full_name":"ramakay/claude-organizer","owner":"ramakay","description":"AI-powered file organization and context engineering that understands content, not patterns. Automatically sorts temporary scripts from permanent docs while   preserving your workflow. Works seamlessly with Claude Code hooks. Protects README, LICENSE, configs.","archived":false,"fork":false,"pushed_at":"2025-08-18T01:23:10.000Z","size":841,"stargazers_count":36,"open_issues_count":1,"forks_count":7,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-14T05:29:00.016Z","etag":null,"topics":["claude-ai","claude-code","context-engineering"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ramakay.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-15T17:23:26.000Z","updated_at":"2025-09-12T12:34:25.000Z","dependencies_parsed_at":"2025-08-11T07:13:43.304Z","dependency_job_id":"60db6df7-4bcf-48d9-9b1f-d17bdf92dda3","html_url":"https://github.com/ramakay/claude-organizer","commit_stats":null,"previous_names":["ramakay/claude-organizer"],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/ramakay/claude-organizer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ramakay%2Fclaude-organizer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ramakay%2Fclaude-organizer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ramakay%2Fclaude-organizer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ramakay%2Fclaude-organizer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ramakay","download_url":"https://codeload.github.com/ramakay/claude-organizer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ramakay%2Fclaude-organizer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":275116073,"owners_count":25408196,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-14T02:00:10.474Z","response_time":75,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude-ai","claude-code","context-engineering"],"created_at":"2025-09-21T05:05:09.357Z","updated_at":"2025-09-21T05:05:42.114Z","avatar_url":"https://github.com/ramakay.png","language":"TypeScript","funding_links":[],"categories":["Code Quality Gates"],"sub_categories":[],"readme":"# Claude Organize\n\n\u003cdiv align=\"center\"\u003e\n\n\u003ch3\u003eIntelligent document organization for Claude Code\u003c/h3\u003e\n\n[![npm version](https://badge.fury.io/js/claude-organize.svg)](https://www.npmjs.com/package/claude-organize)\n[![npm downloads](https://img.shields.io/npm/dm/claude-organize.svg)](https://www.npmjs.com/package/claude-organize)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![CI](https://github.com/ramakay/claude-organizer/actions/workflows/ci.yml/badge.svg)](https://github.com/ramakay/claude-organizer/actions/workflows/ci.yml)\n\n**NPM Package**: [https://www.npmjs.com/package/claude-organize](https://www.npmjs.com/package/claude-organize)\n\n\u003c/div\u003e\n\n## The Messy File Problem 🗂️\n\nClaude 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:\n\n```\nmy-project/\n├── test-api-v1.md               # First attempt\n├── test-api-v2.md               # \"Fixed\" version\n├── test-api-final.md            # \"Final\" version\n├── test-api-final-FIXED.md      # Actually final?\n├── debug-webhook.mjs            # Quick test script\n├── analyze-performance.mjs      # Debugging session\n└── ... (87 more files at root!)\n```\n\n**Solution**: Automatic file organization using AI-powered categorization\n\n## How Claude Organize Helps\n\n### 🗂️ Automatic File Organization\n\n```\nmy-project/\n├── src/                         # Source code stays untouched\n├── docs/\n│   ├── testing/                 # Test results organized\n│   └── troubleshooting/         # Debug notes in one place\n└── scripts/\n    ├── checks/                  # Validation scripts grouped\n    └── debug/                   # Debug utilities together\n```\n\n## Quick Start\n\n### Installation\n\n```bash\nnpm install -g claude-organize\n```\n\n### Setup File Organization\n\nYou have two options to configure the file organization hook:\n\n#### Option 1: Using Claude's /hooks command (Recommended)\n\nUse Claude Code's built-in /hooks command to configure:\n\n```bash\n# Step 1: Type the /hooks command\n/hooks\n\n# Step 2: Select \"PostToolUse\" from the menu\n\n# Step 3: Enter the matcher pattern:\nWrite|Edit|MultiEdit\n\n# Step 4: Select \"command\" as the hook type\n\n# Step 5: Enter the command:\nclaude-organize\n\n# Step 6: Press Enter to confirm\n\n# Step 7: Press Esc twice to exit the menu\n\n# That's it! The hook is now configured\n```\n\n#### Option 2: Manual Configuration\n\nAdd to your `.claude/settings.json`:\n\n```json\n{\n  \"hooks\": {\n    \"PostToolUse\": [\n      {\n        \"matcher\": \"Write|Edit|MultiEdit\",\n        \"hooks\": [{ \"type\": \"command\", \"command\": \"claude-organize\" }]\n      }\n    ]\n  }\n}\n```\n\n## How This Complements Claude Code Best Practices\n\nAccording to [Claude Code Best Practices](https://www.anthropic.com/engineering/claude-code-best-practices), the recommended approaches include:\n\n- **Hierarchical CLAUDE.md files** - Great for static organization in monorepos\n- **Shorter sessions with /clear** - Helps manage context effectively\n- **Using subagents** - Reduces context usage for complex tasks\n\n**Claude Organize complements these practices:**\n\n**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.\n\nThink of it this way:\n\n- **Best Practices**: Organize your kitchen (hierarchical CLAUDE.md)\n- **Claude Organize**: Clean as you cook (hooks)\n\nBoth approaches work together for optimal Claude Code workflows.\n\n## Key Features\n\n✅ **Automatic cleanup** - Files move to proper directories instantly  \n✅ **AI categorization** - Understands file purpose from content  \n✅ **10 script subcategories** - Detailed organization for scripts  \n✅ **Safe defaults** - Protects README, LICENSE, configs  \n✅ **Context reduction** - Cleaner workspace = better Claude performance\n\n## Architecture\n\n### How It Works\n\n![Architecture Overview](docs/architecture/architecture.png)\n\n**File Organization**: User → Claude Code → Hook → claude-organize → AI → Organized Files\n\n[View all architecture diagrams →](docs/architecture/)\n\n## Documentation\n\n| **Guide**                                                   | **Description**                          |\n| ----------------------------------------------------------- | ---------------------------------------- |\n| 📖 [Full Documentation](docs/)                              | Complete feature guide and API reference |\n| 🚀 [Quick Start](docs/quick-start.md)                       | Get up and running in 5 minutes          |\n| 📂 [Subcategories Guide](docs/subcategories.md)             | Script organization patterns             |\n| ⚙️ [Configuration](docs/configuration.md)                   | Customize behavior and settings          |\n| 🔧 [JavaScript Organization](docs/js-organization-guide.md) | Experimental JS/MJS features             |\n| 🛠️ [Troubleshooting](docs/troubleshooting/)                 | Common issues and solutions              |\n\n## Categories\n\nFiles are automatically organized into these directories:\n\n### Documentation\n\n- `docs/testing/` - Test results, QA reports\n- `docs/analysis/` - Data analysis, performance reports\n- `docs/architecture/` - System design, technical docs\n- `docs/operations/` - Deployment guides, runbooks\n- `docs/troubleshooting/` - Debug logs, issue investigations\n\n### Scripts\n\n- `scripts/checks/` - Verification and validation utilities\n- `scripts/testing/` - Test scripts and runners\n- `scripts/deployment/` - Deployment and release scripts\n- `scripts/utilities/` - General utility scripts\n- [+ 6 more subcategories](docs/subcategories.md)\n\n## Common Scenarios\n\n### The \"Create and Run\" Learning Curve\n\n![Learning Curve](docs/assets/images/learning-curve.jpeg)\n\nYou might encounter this scenario:\n\n```\nClaude: \"I'll create test-email.mjs and run it\"\n*Creates file*\n*File gets organized to scripts/testing/*\nClaude: \"Error: Cannot find module './test-email.mjs'\"\n```\n\n**This is intentional!** The friction teaches Claude (and us) better habits:\n\n1. **First time**: Claude learns files don't stay at root\n2. **Second time**: Claude checks where files went (`find . -name \"test-email.mjs\"`)\n3. **Third time**: Claude runs directly from organized location\n\nJust like training a junior developer: \"Test files go in the test directory.\"\n\n### Why This Matters\n\nThe housekeeper doesn't compromise on cleanliness. This \"friction\" is actually a feature:\n\n- Claude learns project structure through experience\n- Better long-term habits \u003e short-term convenience\n- Consistent organization \u003e temporary files at root\n\n## Slash Commands\n\n- `/claude-organize-bypass` - Toggle file organization on/off\n- `/claude-organize-add \u003cpattern\u003e` - Add patterns to be organized\n- `/claude-organize-js` - Enable JavaScript organization (experimental)\n\n## Safety \u0026 Disclaimers\n\n**⚠️ USE AT YOUR OWN RISK**: Claude Organize moves files in your project. Always use version control and test in a safe environment first.\n\n- ✅ **Use version control** (Git) before enabling\n- ✅ **Test in a safe environment** first\n- ✅ **Review the organization log** at `docs/organization-log.json`\n\n## Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n## License\n\nDistributed under the MIT License. See [LICENSE](LICENSE) for more information.\n\n## Related Projects\n\n- **[cc-enhance](https://github.com/ramakay/cc-enhance)** - Prompt enhancement with contrarian analysis for Claude Code\n  - Transform vague requests into comprehensive, context-aware prompts\n  - Adds contrarian analysis to challenge assumptions early\n  - Use both tools together for the complete Claude Code experience!\n\n## Support\n\n- 📝 [Report Issues](https://github.com/ramakay/claude-organize/issues)\n- 💬 [Discussions](https://github.com/ramakay/claude-organize/discussions)\n\n---\n\n\u003cdiv align=\"center\"\u003e\nMade with ❤️ by \u003ca href=\"https://github.com/ramakay\"\u003eRama Annaswamy\u003c/a\u003e\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Framakay%2Fclaude-organizer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Framakay%2Fclaude-organizer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Framakay%2Fclaude-organizer/lists"}