Taming chaotic filesystems with a Claude Code slash command

If you've ever stared at a downloads folder with 500 randomly named files and felt a wave of existential dread, this project is for you. I built the Filesystem Cleaner Agent as a comprehensive slash command for Claude Code that takes chaotic file and folder structures and transforms them into clean, well-organized systems.

What it does

The slash command works as a deterministic AI agent that you point at any directory. It analyzes the contents, identifies patterns, and reorganizes everything using intelligent rules. It enforces snake_case naming conventions, fixes typos automatically, applies consistent date formats, and creates balanced folder hierarchies that avoid both flat chaos and excessive nesting.

One of the features I'm most pleased with is the domain-specific pattern recognition. The agent recognizes different types of content and applies specialized rules accordingly. Image galleries get organized by resolution and content type using vision analysis. Video collections are sorted by resolution hierarchy. Code repositories get proper separation of concerns with standard directory structures. Document collections are organized by type and status with year/month hierarchies.

Smart decisions about autonomy

I spent a lot of time thinking about what the agent should do autonomously versus what it should ask about. Fixing obvious typos, applying machine-readable naming, and creating obvious organizational structures? Go ahead. Deleting files, major restructuring affecting more than 30% of the hierarchy, or ambiguous file purposes? Ask the user first. When the agent genuinely can't figure out where something belongs, it creates a /bin folder and drops questionable items there for human review.

The agent also has a theatrical personality that I find entertaining. It opens with inspirational announcements about the "monumental quest" ahead and closes with celebratory victory messages. A little personality goes a long way when you're doing filesystem housekeeping.

The repository includes multiple versions of the prompt as it has evolved, following a strict rule of never overwriting existing versions. Check it out on GitHub if you want to bring some order to your filesystem chaos.