cascade-fm 0.1.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) is the active/default frontend.
• Status: Alpha / MVP in progress.
• Core workflow already works for browsing, filtering, and writing outputs.

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

Quick Start

Requirements

• Python 3.13+
• uv

Install and Run

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

For platform notes and troubleshooting, 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 (today)

• Browser filtering: name pattern + type
• rename_pattern (label in UI: Rename)
• image_transform (unified image operation)
• unarchive
• create_archive
• save_to

Release Scope (Milestone 2)

This release targets a stable MVP flow:

• browse files/folders,
• chain supported operations in panes,
• execute and inspect intermediate results,
• write final output with save_to,
• restore or clear last session snapshot on startup.

Known Limitations

• Cache strategy still needs the planned metadata/content split refactor.
• Workflow/session JSON schema is currently version 1 and intended for same-version app usage.
• Advanced graph editing, plugins, and remote filesystems are not part of this release.
• Very large directories and heavy transforms may still require manual pacing.

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