messyRoom

             .-.
            (   ).
           (___(__)   messyRoom
            / / /     cluttered floor, clean exits
      _    /_/ /
   __| |__    /       scan -> filter -> classify -> preview -> apply -> undo
  / _` / _ \          safe file organization for operator workspaces
 | (_| | (_) |
  \__,_|\___/

messyRoom is a dry-run-first file organizer for Linux workspaces. It scans a source directory, classifies files with configurable security/research-oriented rules, previews the target layout, and only moves or copies files after explicit confirmation.

It is designed for busy operator directories such as ~/Downloads, recon folders, bug-bounty workspaces, notes dumps, screenshots, payload collections, archives, configs, and reports.

Safety model

• Dry-run is the default. No files move unless --apply is passed.
• Hidden files and hidden directories are skipped unless --include-hidden is passed.
• Sensitive names such as private keys, credentials, tokens, and passwords are skipped by default.
• Protected system paths such as /, /etc, /usr, /var, /opt, and /root are refused.
• Existing destination files are never overwritten; collisions get a numeric suffix.
• Applied move/copy transactions are logged and can be undone.

Install

From a clone:

git clone https://github.com/usercopy-fault/messyRoom.git
cd messyRoom
python -m venv .venv
source .venv/bin/activate
python -m pip install -e .

The editable install provides the messyroom command.

If you do not want to install it yet, run directly from the repository:

PYTHONPATH=src python -m messyroom --help
# or:
python src/messyroom/organizer.py --help

Quick start

Preview organization for ~/Downloads:

messyroom --source ~/Downloads

Preview with skipped files visible:

messyroom --source ~/Downloads --show-skipped

Create the category folders under the configured target root, defaulting to ~/organized:

messyroom --init

Move files after reviewing the preview:

messyroom --source ~/Downloads --target ~/organized --apply

Copy instead of move:

messyroom --source ~/Downloads --target ~/organized --apply --copy

Undo the most recent applied transaction:

messyroom --undo

Show undo history or recent operation logs:

messyroom --history
messyroom --log --log-tail 50

Common workflows

Organize a recon drop

messyroom -s ~/Downloads/recon-drop -t ~/ops/sorted-recon --show-skipped
messyroom -s ~/Downloads/recon-drop -t ~/ops/sorted-recon --apply

Organize only one category

messyroom -s ~/Downloads -t ~/organized --only-category Screenshots
messyroom -s ~/Downloads -t ~/organized --exclude-category Archives

Include hidden or sensitive files deliberately

messyroom -s ~/Downloads --include-hidden
messyroom -s ~/Downloads --apply --include-sensitive

Use --include-sensitive carefully. The safer pattern is to inspect the preview first, then apply only after you are certain the target directory is appropriate.

Categories

Default categories include:

• Burp-Exports, Caido-Exports, Targets, Recon, Payloads, Reports, Wordlists
• Mobile-APKs, Screenshots, PCAPs, Keys, JS-Files
• Notes, Code, Web, Configs, Logs, Data, Documents
• Images, Videos, Music, Archives, Other

Classification uses this order:

1. filename keyword rules
2. content regex rules from the first few KB of text-like files
3. extension rules
4. fallback to Other

Configuration

Bundled JSON configs live in src/messyroom/configs/:

• categories.json controls keyword, content, extension, and priority rules.
• ignore.json controls ignored folders, ignored filenames, protected paths, and sensitive patterns.
• settings.json controls defaults such as recursion, scan depth, target root, and collision behavior.

Use a custom config directory containing any or all of those files:

mkdir -p ~/.config/messyroom
cp src/messyroom/configs/*.json ~/.config/messyroom/
$EDITOR ~/.config/messyroom/categories.json
messyroom -s ~/Downloads --config-dir ~/.config/messyroom

Project layout

messyRoom/
├── README.md
├── pyproject.toml
├── src/messyroom/
│   ├── __init__.py
│   ├── __main__.py
│   ├── organizer.py
│   ├── scanner.py
│   ├── rules.py
│   ├── mover.py
│   ├── reporter.py
│   ├── utils.py
│   └── configs/
├── tests/
└── docs/legacy/

Development

python -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[dev]'
python -m pytest
python -m compileall src tests

Run a direct smoke test without touching real files:

tmp=$(mktemp -d)
printf 'Nmap scan report for example.com\n80/tcp open http\n' > "$tmp/recon.txt"
messyroom -s "$tmp" -t "$tmp/out" --show-skipped
rm -rf "$tmp"

Legacy material

The original recovered single-file organizer is kept under scripts/legacy/ for reference. The maintained implementation is the package under src/messyroom/.

Author

Kansas