Plugin catalog

folder_cleaner

Plans how to sort and clean a messy folder, moves clutter to quarantine, and can undo the run.

↓ on this page

Actions
Example
Settings
Permissions

folder_cleaner scans a folder, saves a plan for sorting files and setting clutter aside, then applies the plan after you confirm. Reach for it on a folder such as ~/Downloads when you want to review every move and be able to undo the run. It adds nothing to listings.

Cleanup candidates go to .lla-quarantine/<plan_id>/ inside the folder and stay there until you empty the quarantine. The candidates are temporary files, OS junk, empty directories, duplicates (the oldest copy stays) and archives older than 30 days.

Actions

Run an action with lla plugin run folder_cleaner <action> -- <args>. Every action is interactive, so it needs a TTY and the default --output human. A directory defaults to the current one.

Action	Arguments	What it does
`scan`	`[dir]`	Prints a summary and saves nothing.
`preview`	`[dir] [profile]`	Prints the planned actions and saves the plan.
`clean`	`[dir] [profile]`	Previews, asks which actions to run (all, organize only, quarantine only or one by one), then runs them.
`apply`	`<plan_id>`	Applies a saved plan after a confirmation.
`show-plan`	`<plan_id>`	Prints a saved plan.
`restore`	`[run_id]`	Moves a run's items back after a confirmation. With no ID, you pick the run. Folders the run created stay in place.
`history`		Lists saved plans and runs.
`doctor`	`[run_id] [--repair]`	Checks run records and recovers restorable items when asked.
`quarantine-list`		Lists quarantined files.
`quarantine-empty`	`[days]`	Permanently deletes quarantined files older than `days`, by file modified time, after a confirmation. Defaults to 30.
`config-wizard`		Adjusts common settings through prompts.
`help`		Prints usage.

Profile	Organize	Cleanup	Scan
`downloads` (default)	yes	yes	Recursive, depth 8
`desktop`	yes	yes	Recursive, depth 8
`project`	yes	yes	Top level only
`media`	yes	no	Recursive, depth 6

Example

lla plugin run folder_cleaner preview -- ~/project/clean

Folder Cleaner Preview
Plan: plan-20261104230028394
Directory: ~/project/clean
Profile: downloads
Actions: 9
Summary: 5 organize · 4 quarantine · 75 B quarantine bytes · 1 duplicates · 1 empty dirs
 
Organize 5
  [1] report copy.pdf -> Documents/report copy.pdf (organize as documents)
  [2] unknown.xyz -> Uncategorized/unknown.xyz (organize as uncategorized)
  [3] photo.png -> Images/photo.png (organize as images)
  [4] sub/script.py -> Code/script.py (organize as code)
  [5] notes.md -> Documents/notes.md (organize as documents)
 
Quarantine 4
  [6] scratch.tmp -> .lla-quarantine/plan-20261104230028394/scratch.tmp (temporary or backup file)
  [7] archive.zip -> .lla-quarantine/plan-20261104230028394/archive.zip (archive older than 30 days)
  [8] report.pdf -> .lla-quarantine/plan-20261104230028394/report.pdf (duplicate file; oldest copy kept)
  [9] empty-dir -> .lla-quarantine/plan-20261104230028394/empty-dir (empty directory)
Info: Saved plan plan-20261104230028394 at ~/.config/lla/plugins/folder_cleaner/plans/plan-20261104230028394.json

lla plugin run folder_cleaner apply -- plan-20261104230028394
lla plugin run folder_cleaner history
lla plugin run folder_cleaner restore -- run-20261104230029646

Success: Applied plan plan-20261104230028394 as run run-20261104230029646
run-20261104230029646  9 actions  9 completed  0 restored  4 quarantined  ~/project/clean
plan-20261104230028394  9 actions  downloads  ~/project/clean
Success: Restored 9 items from run run-20261104230029646

Settings

The plugin reads ~/.config/lla/plugins/folder_cleaner/config.toml and keeps plans and run records in plans/ and runs/ beside it.

[scan]
recursive = true
max_depth = 8
include_hidden = false
follow_symlinks = false
same_filesystem = true
ignore_patterns = [".git", "node_modules", "target", ".lla-quarantine"]
 
[safety]
quarantine_dir = ".lla-quarantine"
require_confirmation = true
 
[cleanup]
duplicate_detection = true
empty_dirs = true
temp_files = true
os_junk = true
old_archives = true
duplicate_max_bytes = 268435456
old_archive_days = 30
 
[profiles.media]
organize = true
cleanup = false
recursive = true
max_depth = 6
include_hidden = false
 
[[rules]]
category = "notes"
destination = "Notes"
extensions = ["org"]
filename_patterns = []
path_patterns = []

require_confirmation = false skips only the final prompt in clean. apply, restore and quarantine-empty always ask. The cleanup.level and safety.allow_permanent_delete keys do nothing in 0.6.6.

Permissions

filesystem = ["read:tree", "write:tree", "delete:quarantine"]: it moves files inside the target folder, and quarantine-empty deletes from the quarantine.