Complete File Organizer Executor

One-shot command that analyzes a directory structure and reorganizes files into a logical hierarchy based on type, date, project, or custom rules.

When to Use This Command

Run this command when you need to:

• Reorganize a cluttered project directory into a clean, consistent folder structure following framework conventions
• Sort downloaded files, assets, or exported data into categorized subdirectories based on file type and naming patterns
• Standardize a repository layout to match team conventions before onboarding new developers

Consider alternatives when:

• You need ongoing file watching and automatic organization rather than a one-time restructure
• The files are managed by a build tool or package manager that expects a specific immutable layout

Quick Start

Configuration

Copy
name: complete-file-organizer-executor
type: command
category: utilities

Example Invocation

Copy
claude command:run complete-file-organizer-executor --target ./src --strategy type

Example Output

File Organization Report
========================
Target: ./src (147 files analyzed)
Strategy: type-based grouping

Moves planned:
  components/  ← 23 .tsx files (from scattered locations)
  hooks/       ← 8 use*.ts files
  utils/       ← 12 helper files
  types/       ← 9 .d.ts and interface files
  constants/   ← 5 config/constant files
  services/    ← 7 API service files
  styles/      ← 6 .css/.scss files

Skipped: 77 files (already in correct location)
Conflicts: 0

Dry run complete. Run with --execute to apply changes.

Core Concepts

File Organization Overview

Aspect	Details
Strategy Selection	Choose between type-based (by extension), domain-based (by feature), date-based (by modification time), or custom rule-based organization
Conflict Resolution	When two files would map to the same destination, the command detects collisions and offers rename, skip, or merge options
Import Rewriting	After moving files, automatically updates relative import paths in TypeScript, JavaScript, and CSS files to prevent broken references
Dry Run Mode	Default behavior previews all planned moves without executing them, requiring explicit --execute flag to apply changes

Organization Workflow

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  Scan Target │────▶│  Classify    │────▶│  Plan Moves  │
│  Directory   │     │  Each File   │     │  (dry run)   │
└──────────────┘     └──────────────┘     └──────────────┘
       │                    │                     │
       ▼                    ▼                     ▼
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  Detect      │────▶│  Execute     │────▶│  Rewrite     │
│  Conflicts   │     │  File Moves  │     │  Imports     │
└──────────────┘     └──────────────┘     └──────────────┘

Configuration

Parameter	Type	Default	Description
target	string	.	Directory path to organize
strategy	enum	type	Organization strategy: type, domain, date, or custom
execute	boolean	false	Apply changes instead of dry run preview
rewrite_imports	boolean	true	Automatically update import paths after moving files
ignore_patterns	list	[node_modules, .git]	Glob patterns for directories and files to skip

Best Practices

1. Always Run Dry Mode First The default dry run mode previews every planned move without touching the filesystem. Review the full plan before adding --execute to ensure no critical files are misclassified or moved to unexpected locations.

2. Commit Before Organizing Create a clean git commit before running the organizer so you can easily revert with git checkout if the reorganization produces unexpected results. The command modifies many files simultaneously and manual undo is impractical.

3. Use Domain Strategy for Feature-Based Codebases If your project follows a feature-based architecture where each feature has its own components, hooks, and utilities, use the domain strategy to keep related files together rather than splitting them by type across the entire project.

4. Configure Ignore Patterns for Generated Files Build output directories, generated types, and vendor bundles should be excluded from organization. Add them to ignore_patterns to prevent the command from moving files that will be regenerated on the next build.

5. Run Import Rewriting Separately for Large Projects In repositories with thousands of files, import rewriting can take significant time. Run the organizer with --rewrite_imports=false first to verify file moves, then run a dedicated import update pass to catch and fix all broken references.

Common Issues

1. Circular import detected after reorganization Moving files can surface hidden circular dependencies that previously worked due to module resolution order. Use the --detect-cycles flag to identify circular imports before and after organization and resolve them by extracting shared code into a separate module.

2. CSS module imports break after file moves CSS Modules use relative paths that the import rewriter may not update if the CSS file references images or fonts with relative URLs. Manually verify that asset references in moved CSS files still resolve correctly.

3. Git history lost for moved files Git tracks file moves as delete + create unless the content similarity threshold is met. Use git log --follow on moved files to verify history is preserved, and consider using git mv for critical files where history tracking is essential.