ClutterCut

ClutterCut is a local-first organizer for messy folders. It cleans staging areas, media dumps, project spillover, and the usual Downloads chaos by using deterministic rules first and a local LLM only for the files that still need judgment.

It is built to be conservative:

• preview first
• protect config and app-state paths by default
• keep cohesive collections together when possible
• keep RAG off until it proves useful
• make undo part of the normal workflow, not an afterthought

Why It Exists

Most file organizers fail in one of two ways:

• they are too dumb, so they stop at extension buckets
• they are too aggressive, so they confidently move the wrong thing

ClutterCut splits that problem:

• deterministic routing handles the obvious cases
• the hybrid planner spends local AI budget only on unresolved files
• policy rules protect the kinds of files that should not be touched casually

Screenshots

Dry-run preview

Hybrid planning with local AI

Quick Start

Install the CLI

make install

That installs the binary as cluttercut.

Preview a rules-only run

cluttercut \
  --mode deterministic \
  --root ~/Downloads \
  --dest ~/Downloads \
  --dry-run

Preview a hybrid run

cluttercut \
  --root ~/Downloads \
  --dest ~/Downloads \
  --dry-run \
  --llm-metrics

Hybrid mode is the default planner path.

Preinstall the local AI dependencies

make llama
make models

Or let the CLI fetch missing pieces:

cluttercut --install-deps

Too Late, You Didn’t Read

• Start with --dry-run.
• The hybrid planner only sees files the deterministic pass could not confidently route.
• --protect-config is on by default and should usually stay on.
• RAG examples and the RAG safety gate are off by default. Keep them off unless you are explicitly benchmarking them.
• Auto-launched llama-server uses a grammar-constrained output path for the canonical planner.
• If you are comparing planner quality, benchmark with fixed seed, fixed worker count, and the same folder set.

Profiles

Profiles bias routing toward the shape of your files:

• photographer
• video
• audio
• developer

Example:

cluttercut \
  --profile developer \
  --root ~/Desktop \
  --dest ~/Desktop \
  --dry-run

Local AI Setup

ClutterCut uses llama.cpp through llama-server for local hybrid planning.

Useful defaults:

• binary: adapters/llm/bin/llama/llama-server
• backend: llama
• host: http://localhost:8080
• grammar: hybrid_lines

Override with env vars:

CLUTTERCUT_LLAMA_BINARY=/path/to/llama-server
CLUTTERCUT_LLAMA_HOST=http://localhost:8080
CLUTTERCUT_LLM_MODEL=/path/to/model.gguf

Or flags:

cluttercut \
  --llama-bin /path/to/llama-server \
  --llama-host http://localhost:8080 \
  --llm-model /path/to/model.gguf

More detail is in docs/llama.md.

Development

Common commands:

make test
make build
make run
make check

Desktop shell:

make frontend-install
make wails-dev

The CLI entrypoint is ./cmd/organize.

Release

Automated release flow:

make release TAG=v0.2.0

Pushing a v* tag now triggers the GitHub Actions release workflow, which runs go test ./... and publishes the GitHub Release through GoReleaser.

If you need to rerun release publishing for an existing tag, use the GitHub Actions release workflow with the tag input set to that tag.

For macOS packaging:

make pkg-macos-release TAG=v0.2.0

make pkg-macos-release still builds the local .pkg on macOS, while GitHub Actions publishes the GitHub Release assets for the same tag.

License

ClutterCut is licensed under Business Source License 1.1.

Current repo parameters:

• Additional Use Grant: personal use, non-commercial use, and internal business use are allowed; third-party hosted, managed, OEM, white-label, service-bureau, and directly competing commercial uses are not
• Change Date: 2028-03-20
• Change License: Apache License, Version 2.0

Status

ClutterCut is still pre-1.0. The CLI and canonical planner path are usable now, while packaging, desktop UI, and longer-horizon planner tuning are still evolving.