ClearClutter

A Node.js CLI tool that automatically organises a messy folder by sorting files into extension-based subdirectories.

Node.js

JavaScriptfs module

Source Code

Node.js

Runtime

CLI Tool

Type

Zero

Dependencies

Why I built this

My Downloads folder was a disaster — hundreds of files with no organisation. I kept downloading the same file twice because I couldn't find it, and manually sorting was taking too long. Rather than paying for a folder organiser app, I built one in an afternoon using only Node.js built-in modules. The constraint of using zero external dependencies made it a great exercise in the Node.js standard library.

How it works

ClearClutter reads a target directory using Node's fs module, groups all files by their extension, and then creates subdirectories (one per extension type) and moves each file into the appropriate folder. If a folder for that extension already exists, it uses the existing one. The script runs from the command line with the target path as an argument. The whole implementation is a single file with no dependencies.

Key decisions

Design choices

Zero dependencies

Node.js has everything needed to read directories, check file types, create folders, and move files built in. Keeping it dependency-free means the tool installs instantly, never has security vulnerabilities from third-party packages, and works on any Node.js environment without an npm install.

Extension-based grouping over type-based

Grouping by file extension (e.g., creating a /jpg folder rather than an /images folder) is simpler to implement and more transparent to the user. You always know exactly where a file went without having to remember the tool's type-mapping logic.

Challenges

Problems solved

Handling edge cases: files without extensions and name collisions

Some files have no extension (like Makefile or .gitignore) and some folders already contain a file with the same name. I had to handle both — routing extensionless files to a /misc folder and appending a timestamp to filenames on collision to avoid silent overwrites.

What I learned

ClearClutter was a reminder that you don't need a framework to build something useful. Working exclusively with Node's fs module forced me to understand the file system API deeply — asynchronous I/O, error handling for missing paths, and the difference between rename (move) and copy-then-delete. It's also one of the most satisfying builds: I use it regularly.

To-Do List App