reclaimed 0.2.10

Fast, local disk-usage analysis with a responsive terminal interface.

Reclaimed recursively scans a directory, calculates its largest files and directory trees, and presents the results in either an interactive Textual application or compact Rich tables. It runs entirely on your machine, makes no network requests, and includes no telemetry.

Reclaimed supports Python 3.9+ on macOS, Linux, and Windows.

Install

To work from a clone instead:

git clone https://github.com/taylorwilsdon/reclaimed.git
cd reclaimed
python -m pip install -e .

Use

Interactive mode is the default. Pass a directory, or omit PATH to scan the current directory.

# Open the interactive interface
reclaimed ~/Documents

# Print Rich tables and exit
reclaimed ~/Documents --no-interactive

# Keep more results and use all eight workers
reclaimed ~/Documents --files 25 --dirs 20 --jobs 8

# Add directory names to the default skip list
reclaimed ~/Documents -s node_modules -s __pycache__

# Count logical file sizes instead of bytes currently allocated on disk
reclaimed ~/Documents --apparent-size

# Export the retained results and scan metadata
reclaimed ~/Documents --output results.json

When --output is used with the interactive interface, the JSON file is written after the app exits. In text mode, pressing Ctrl+C prints and optionally exports the partial results collected so far.

Command-line reference

.Trash and System Volume Information are always included in the skip list. Additional --skip-dirs values are matched by directory name.

Interactive interface

The interface updates while the scan runs and adapts to the terminal width: result panels sit side by side in wide terminals and stack in compact terminals. Each result shows its size, share of the scanned total, and path. Directories show whether their full subtree is still scanning or done, and a storage column appears when iCloud or OneDrive content is found.

The summary strip tracks discovered size, file count, elapsed time, and hidden items. Hiding a directory only removes it and its descendants from the current view. Deletion removes the selected item from disk and always requires confirmation.

Results can be sorted by size, modification time, name, or path. The built-in theme cycle includes Solarized Dark, Nord, Rose Pine Moon, Catppuccin Mocha, Atom One Dark, and Textual Light.

Text output and JSON

Text mode prints the same largest-file and largest-directory sets without starting the full-screen interface. Tables use relative, end-preserving paths, proportional bars, percentages, and an iCloud/OneDrive/local storage column only when relevant. Permission and other access failures are summarized after the results instead of aborting the scan.

JSON exports contain:

• Scan timestamp, root path, size mode, total bytes, formatted total, and number of files scanned
• Largest files and directories with absolute paths, byte and formatted sizes, and storage type
• Paths that could not be read and their error messages

Python API

The scanner can also be embedded. Cloud roots named Mobile Documents, OneDrive, or OneDrive - Organization are detected automatically; explicit base paths are also supported:

from pathlib import Path

from reclaimed import DiskScanner, ScanOptions

options = ScanOptions(
    max_files=25,
    max_dirs=20,
    max_workers=4,
    icloud_base=Path.home() / "Library" / "Mobile Documents",
    onedrive_base=Path.home() / "OneDrive",
    actual_size=True,
)
result = DiskScanner(options).scan(Path.home())

scan_async() yields progress snapshots while directory listings run off the event loop. An interrupted synchronous scan raises ScanInterruptedError with the collected ScanResult available as error.partial.

Contributing

See CONTRIBUTING.md for the development workflow and pyproject.toml for supported Python versions, dependencies, and tool configuration.

License

Reclaimed is available under the MIT License.