cascade-fm 0.2.0

A visual, pipeline-driven file manager that turns file operations into composable, repeatable workflows.

cascade

cascade is a visual, pipeline-driven desktop file manager.

You select files, add operations in panes from left to right, and only the final pane writes to disk.

Think of it as Unix pipes with a face.

Current State

• UI: PySide6 (Qt) desktop application.
• Status: Alpha — approaching first release (Milestone 2).
• Full standard file-management workflow works end-to-end.

Project details and roadmap live in spec/design.md and spec/roadmap.md.

Quick Start

Linux — AppImage (recommended)

Download cascade-x86_64.AppImage from the releases page, then:

chmod +x cascade-x86_64.AppImage
./cascade-x86_64.AppImage

No Python or installation required. Works on any distro with glibc 2.17+.

Python / uv

pip install cascade-fm   # or: uv tool install cascade-fm
cascade

From source

git clone <repository-url>
cd cascade
uv sync
uv run cascade

For troubleshooting and platform notes, see docs/installation.md.

How cascade works

Pipeline model:

[ Browse Files ] -> [ Filter ] -> [ Transform ] -> [ Save To ]

• Pane 1 is the filesystem browser.
• Each next pane applies one operation to the previous pane output.
• Executing a pane marks panes to the right as stale.
• Final output is written only by the final write operation.

Built-in Operations

Operation	Description
filter_extension / filter_name	Browser-side filtering by extension or name glob
rename	Plain rename, search & replace, or regex replace with capture groups
save_to	Copy files to a target directory (with conflict policy)
move_to	Move files to a target directory (with conflict policy)
image_transform	Resize, convert format, rotate, compress, strip EXIF
create_archive	Create zip / tar / tar.gz / tar.bz2 / tar.xz archives
unarchive	Extract archives (with optional single-root flatten)
delete_files	Permanently delete files with in-UI confirmation

Features

• Pipeline model — chain operations left to right; only the final pane writes to disk
• Session restore — reopen the last pipeline on launch (configurable: ask / auto / off)
• Workflow save/load — save named pipelines as JSON, reload them later
• Preferences — start directory, default sort order, hidden-file toggle, bookmarks, language
• Internationalisation — ships English and German; add custom languages via ~/.cascade/translations/
• Caching — intermediate results stored in a content-addressable cache for fast re-execution

Known Limitations

• Workflow/session JSON schema is version 1; use the same app version that wrote the file.
• Very large directories (100k+ files) and heavy image transforms may slow the UI.
• Advanced graph editing, branch pipelines, plugins, and remote filesystems are not yet implemented.
• Language change requires an application restart to take effect.

Development

Setup

uv sync

Test / Lint / Typecheck

# tests
uv run pytest -q

# lint
uv run ruff check src tests

# typecheck
uv run pyright

Optional: task runner (just)

just test
just lint
just format
just typecheck
just build

Build / Publish

uv run python -m build

Upload (maintainers):

uv run twine upload dist/*

License

MIT