fs-janitor

module

v1.0.0 Latest Latest Go to latest Published: Jul 9, 2026 License: MIT

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/BadRat-in/fs-janitor

Links

Open Source Insights

README ¶

FS Janitor

The complete filesystem maintenance toolkit for macOS.

Storage cleanup, scheduled expirations, directory watchers and a maintenance score — one tool, a scriptable CLI and a full-screen TUI.

Install

From source (Go 1.26+):

git clone https://github.com/BadRat-in/fs-janitor.git
cd fs-janitor
make build          # produces ./bin/fsj
# or install into GOBIN:
make install

go install github.com/BadRat-in/fs-janitor/cmd/fsj@latest

FS Janitor is a single, cgo-free static binary (the SQLite job store uses the pure-Go modernc.org/sqlite driver). macOS 10.15+.

Why?

Most computers slowly become cluttered over time.

Downloads folders filled with installers from years ago.
Temporary ZIP files that are never opened again.
Screenshots scattered across the Desktop.
Build artifacts taking up gigabytes.
Google Drive temporary folders that should disappear after a few days.

Instead of manually cleaning them every few months, FS Janitor automates the entire lifecycle.

Features

One-time Expiration

Schedule a file or folder to be removed after a specific duration.

fsj expire ~/Downloads/archive.zip 30d

Supports:

From now
Birth time
Modification time

Actions:

Move to Trash
Permanent deletion
(Future) Archive
(Future) Custom actions

Directory Watchers

Continuously keep directories clean.

Example:

fsj watch ~/Downloads \
    --after 30d \
    --from modified \
    --pattern '*.zip'

Files are moved to the Trash by default; add --delete for permanent removal, --recursive to descend into subfolders, and --dry-run to preview.

Every cleanup run, FS Janitor automatically removes files matching the configured policy.

Perfect for:

Downloads
Desktop
Temporary folders
Build directories
Cache directories
Google Drive
External drives

Interactive Terminal UI

Manage everything from a modern Bubble Tea interface.

View active jobs
Create watchers
Schedule expirations
Edit rules
View cleanup history
Monitor reclaimed storage

CLI

Everything available in the TUI is also accessible from the command line.

fsj                     # open the interactive dashboard (TUI)
fsj expire <path> <dur> # schedule a one-time expiration
fsj watch  <path> …     # create a recurring directory watcher
fsj list                # list jobs
fsj remove <id>…        # remove jobs
fsj run [--dry-run]     # run every due job now
fsj clean               # preview reclaimable leftovers & caches
fsj score               # maintenance score + storage health
fsj history             # recent run log
fsj install|uninstall   # manage the scheduled LaunchAgent
fsj doctor              # environment diagnostics

Safe by Default

FS Janitor prioritizes safety.

By default it moves files to the macOS Trash instead of permanently deleting them.

Permanent deletion must be explicitly enabled.

Native macOS

Designed specifically for macOS.

LaunchAgent integration
Finder-compatible
Google Drive compatible
iCloud Drive compatible
APFS birth time support

Example Workflows

Keep Downloads Clean

Downloads
└── Delete files after 30 days

Temporary Project Folder

Delete entire folder
15 days from now

Google Drive

Move temporary folders to Trash
after 14 days

Screenshots

Delete screenshots
after 7 days

Planned Features

Smart cleanup rules
Pattern matching
Include / Exclude filters
Size-based cleanup
Duplicate detection
Archive old files
Compression before deletion
Notifications
Cleanup analytics
Storage insights
Rule templates
Plugin system

Roadmap

v0.1 — Foundation

Project structure
Cobra CLI
Bubble Tea TUI
SQLite storage
Duration parser
One-time expiration jobs
Move to Trash
Permanent delete
Cleanup engine
LaunchAgent installer
Job history
Logging

v0.2 — Directory Watchers

Watch directories
Cleanup policies
Birth time support
Modification time support
From-now expiration
Include patterns
Exclude patterns
Dry-run mode
Recursive cleanup

v0.3 — Rule Engine

Multiple rules per directory
File extension filters
File size filters
Name matching
Ignore lists
Rule priorities
Rule presets

v0.4 — Dashboard

Interactive dashboard
Storage statistics
Cleanup reports
Search
Bulk operations
Job editing
Notifications

v0.5 — Automation

Archive action
Compression
Execute custom commands
Plugin API
Webhooks
Scheduled reports

v1.0

Stable API
Homebrew distribution
Automatic updates
Documentation
Examples
Performance optimizations
Comprehensive test suite

Tech Stack

Go
Bubble Tea
Bubbles
Lip Gloss
Cobra
SQLite

License

This project is licensed under the MIT License.

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
fsj command Command fsj is FS Janitor: the filesystem maintenance toolkit for macOS.	Command fsj is FS Janitor: the filesystem maintenance toolkit for macOS.
internal
analytics Package analytics turns raw filesystem signals into the FS Janitor "Maintenance Score" and the storage-health report that headlines the dashboard.	Package analytics turns raw filesystem signals into the FS Janitor "Maintenance Score" and the storage-health report that headlines the dashboard.
app Package app is FS Janitor's service layer: the single seam where the reused CleanX scanning/cleanup stack, the new job/engine/store/analytics modules, and the macOS probes are wired together into high-level operations.	Package app is FS Janitor's service layer: the single seam where the reused CleanX scanning/cleanup stack, the new job/engine/store/analytics modules, and the macOS probes are wired together into high-level operations.
appindex Package appindex builds and holds the index of installed macOS applications that CleanX's detection engine consults to decide whether a Library item belongs to an app that is still present.	Package appindex builds and holds the index of installed macOS applications that CleanX's detection engine consults to decide whether a Library item belongs to an app that is still present.
cleaner Package cleaner performs the actual deletion of selected leftover groups and reports how much space was reclaimed.	Package cleaner performs the actual deletion of selected leftover groups and reports how much space was reclaimed.
cleanui Package tui implements CleanX's Bubble Tea terminal UI, replacing the raw ANSI escape sequences of the reference script with a proper full-screen, terminal-agnostic interface.	Package tui implements CleanX's Bubble Tea terminal UI, replacing the raw ANSI escape sequences of the reference script with a proper full-screen, terminal-agnostic interface.
cli Package cli defines FS Janitor's command-line interface: the scriptable surface that mirrors every TUI action, built on Cobra.	Package cli defines FS Janitor's command-line interface: the scriptable surface that mirrors every TUI action, built on Cobra.
config Package config holds the static configuration that drives CleanX's leftover detection: which directories to scan, which patterns to protect, how folder and bundle-ID names map to applications, and the age thresholds that gate deletion.	Package config holds the static configuration that drives CleanX's leftover detection: which directories to scan, which patterns to protect, how folder and bundle-ID names map to applications, and the age thresholds that gate deletion.
detect Package detect implements CleanX's leftover-attribution logic: given a filesystem component name (a folder, a plist, a bundle-ID directory) it decides whether that component belongs to a currently installed app, and whether it is a confirmed leftover of an uninstalled one.	Package detect implements CleanX's leftover-attribution logic: given a filesystem component name (a folder, a plist, a bundle-ID directory) it decides whether that component belongs to a currently installed app, and whether it is a confirmed leftover of an uninstalled one.
duration Package duration parses and formats the compact, human-friendly retention and expiry durations that fs-janitor jobs are configured with (for example "expire after 30d" or "keep for 2w").	Package duration parses and formats the compact, human-friendly retention and expiry durations that fs-janitor jobs are configured with (for example "expire after 30d" or "keep for 2w").
engine Package engine executes jobs against the filesystem.	Package engine executes jobs against the filesystem.
humanize Package humanize formats byte/kilobyte quantities for display in the CLI and TUI.	Package humanize formats byte/kilobyte quantities for display in the CLI and TUI.
job Package job defines the central domain object of FS Janitor: the Job.	Package job defines the central domain object of FS Janitor: the Job.
launchd Package launchd installs, uninstalls, and renders the macOS LaunchAgent that drives fs-janitor's periodic cleanup (the PRD's "Automation" module).	Package launchd installs, uninstalls, and renders the macOS LaunchAgent that drives fs-janitor's periodic cleanup (the PRD's "Automation" module).
osprobe Package osprobe provides the production implementation of scan.Probes: the real filesystem and system interactions the scanner needs on macOS.	Package osprobe provides the production implementation of scan.Probes: the real filesystem and system interactions the scanner needs on macOS.
scan Package scan walks the configured Library and developer directories, applies CleanX's safety gates (installed / in-use / staleness, via package detect), and groups the surviving leftovers by vendor for presentation and deletion.	Package scan walks the configured Library and developer directories, applies CleanX's safety gates (installed / in-use / staleness, via package detect), and groups the surviving leftovers by vendor for presentation and deletion.
store Package store is FS Janitor's persistence layer: an embedded SQLite database holding the user's jobs and the history of every run the engine performs.	Package store is FS Janitor's persistence layer: an embedded SQLite database holding the user's jobs and the history of every run the engine performs.
tmutil Package tmutil lists and deletes local Time Machine snapshots via the macOS `tmutil` command.	Package tmutil lists and deletes local Time Machine snapshots via the macOS `tmutil` command.
toolclean Package toolclean discovers developer tools present on the machine and runs each tool's own cache-cleanup command (e.g.	Package toolclean discovers developer tools present on the machine and runs each tool's own cache-cleanup command (e.g.
trash Package trash implements fs-janitor's "safe by default" deletion: instead of permanently removing a file or folder, the target is moved to the macOS Trash so the user can recover it later (Finder's Put-Back restores it to its original location).	Package trash implements fs-janitor's "safe by default" deletion: instead of permanently removing a file or folder, the target is moved to the macOS Trash so the user can recover it later (Finder's Put-Back restores it to its original location).
tui cleanup.go renders the Cleanup module: the reused CleanX scan surfaced as an interactive, sectioned multi-select inside the app shell.	cleanup.go renders the Cleanup module: the reused CleanX scan surfaced as an interactive, sectioned multi-select inside the app shell.