forel README

The project's README from github.com/lab421/forel. As one markdown file: README.md.

Forel

Forel

The Hazel alternative for macOS. Open source and privacy-focused.

macOS 13+ Swift 6 Downloads License: GPLv3


New · project from the Forel team — check out Ombrelle →


This project is built and maintained on my personal time. A ⭐ on the repo is the simplest way to say thanks and helps Forel get discovered by others who might need it. For anyone who wants to go further, you can support the work with a buy me a coffee ☕

Forel — main view Forel — rule editor

Open source, 100% on-device, local-first, no account, no telemetry.

Install with Homebrew:

brew install --cask lab421/tap/forel

Why Forel

Forel is an open-source, community-driven take on folder automation for macOS.

Define rules once watch folders, match files, and move, rename, tag, or label them automatically then let Forel run quietly in your menu bar.

What Forel does

Forel watches your folders and organizes your files automatically based on rules you define — by filename, extension, kind, size, date, tags, or color label.

Downloads/
├── invoice_march_2026.pdf     →  Work/Invoices/2026/
├── photo_2026-03-14.jpg       →  Photos/2026/March/
├── contract_draft_v3.docx     →  Work/Legal/Pending/
└── bank_statement_march.pdf   →  Finance/2026/

Set up a rule once. Forel handles the rest — even when the window is closed.

And everything happens on your Mac. No cloud. No API keys. Your files never leave your machine.

Highlights

Features

Installation

Homebrew

brew install --cask lab421/tap/forel

or

brew tap lab421/tap
brew install --cask forel

Manual

Download the latest release .dmg from the Releases page, open it, and drag Forel to your Applications folder.

Build from source

Prerequisites: Swift 6 · macOS 13 or later

git clone https://github.com/lab421/forel.git
cd forel
swift build
swift test
swift run

To build and package the app, use the Swift package tooling and the existing release workflow.

Requires macOS 13 Ventura or later.

Quick Start

  1. Launch Forel — the icon appears in your menu bar.
  2. Click the icon to see active rules, or open the main window.
  3. Click New Rule and choose a folder to watch.
  4. Define your conditions — by name, extension, kind, size, date, tags, or color label.
  5. Set an action: move, rename, tag, copy, or run a script.
  6. Enable the rule. Forel handles the rest — even when the window is closed.

Architecture

Forel is built as a native Swift macOS app:

forel/
├── Package.swift              # Swift Package Manager manifest
├── Sources/
│   ├── ForelApp/              # SwiftUI app, menu bar, settings, editor, views
│   └── ForelCore/             # Rule engine, watcher, SQLite persistence, models
├── Tests/
│   └── ForelCoreTests/        # Core engine and persistence tests

Key technology choices:

Layer Technology Why
App shell SwiftUI + AppKit Native macOS UI with direct control over windows, menu bar, and focus
Backend Swift 6 Unified app and core logic, strong typing, simple packaging
File watching Native FSEvents wrapper Low-latency, battery-friendly folder monitoring
Database SQLite Embedded, no server, predictable schema and queries
Persistence layer Custom Swift database wrapper Direct control over transactions, migrations, and rule round-trips
Updates GitHub Releases check Detects new tagged releases; ad-hoc signed builds are updated by manual reinstall, not in-place patching
Build Swift Package Manager Single toolchain for development, test, and release

Execution pipeline:

Input
  - FSEvents (real‑time watcher)
  - Run Now (manual — whole folder)
  - Dry Run / Preview (manual — whole folder)
        ↓
Rule Engine (per file, sorted by cost)
  ├─ Scope check (recursion depth)
  ├─ Condition matching (name, extension, kind,
  │   size, date, tags, color label, contents, …)
  └─ Plan actions (conflict‑aware)
        ↓
Action Executor
  ├─ Move / Copy / Rename
  ├─ Tag / Color label
  ├─ Trash / Delete
  └─ Run Script / Shortcut
        ↓
History / Undo (SQLite)

Roadmap

Content matching

The Contents condition matches text found inside files. Everything is read locally — no cloud, OCR runs on-device. When a file's text can't be read, the Dry Run tells you why.

File path
  │
  ├─ Known plain text (.txt, .md, .json, …) ────► read as UTF‑8 / UTF‑16 / ISO Latin 1
  │
  ├─ PDF ──► text layer ─(empty)─► Vision OCR (Apple Neural Engine)
  │
  ├─ RTF / .doc/.docx ──► AppKit document reader (main thread)
  │
  ├─ .xlsx/.xltx / .pptx/.potx / .odt/.ods/.odp ──► ZIP → XML → strip tags
  │
  ├─ .pages / .numbers / .key ──► ZIP → Preview.pdf → PDF text
  │
  ├─ Images (.png, .jpg, .heic, .webp, .gif, …) ──► Vision OCR (Apple Neural Engine)
  │
  ├─ .xls / .ppt / .epub ──► Spotlight query (contains only)
  │
  └─ Unknown extension ──► try plain text ─(binary/undecodable)─► no match
Type Formats Limits
Plain text .txt .md .csv .tsv .json .xml .yaml .yml .html .css .js .ts .swift .rs .py .rb .go .java .c .cpp .h .log, plus any other text file (.ini, .conf, no extension, …) 100 MB
PDF .pdf (text layer, or OCR for scanned PDFs) 100 MB / 100 pages · OCR 20 pages
Rich text .rtf .rtfd 100 MB
Word .doc .docx .dotx 100 MB
Excel .xlsx .xltx 100 MB
PowerPoint .pptx .potx 100 MB
Apple iWork .pages .numbers .key 100 MB
OpenDocument .odt .ods .odp 100 MB
Images (OCR) .png .jpg .jpeg .heic .tiff .tif .webp .gif .bmp .jp2 .psd 25 MB / 12000 px
Spotlight fallback .xls .ppt .epub contains only

[!NOTE] Apple iWork files are read from the preview the app saves inside the document; one saved without a preview falls back to Spotlight.

The Spotlight fallback is used for formats Forel can't read directly. It relies on macOS having already indexed the file and can only answer the contains operator (not is, starts with, regex, …). When a file isn't indexed, it simply doesn't match.

Contributing

Forel is in early development and contributions are very welcome.

git clone https://github.com/lab421/forel.git
cd forel
swift build
swift test

Please read the repository guidelines before submitting. Bug reports, feature requests, and documentation improvements are all appreciated.

License

The source code is licensed under GPL-3.0-or-later, copyright © 2026 lab421 — see LICENSE. That license covers the source code only.

The Forel name, logo, and look are not covered by the GPL and are protected separately — see TRADEMARKS.md.

Star History

Star History Chart

Made with ☕ · SwiftUI + SQLite · Inspired by file automation workflows popularized by tools like Hazel.

forel (lab421/forel)

Searching Database…

832 ·GitHub
Forel
What is this?Forel is an open-source, privacy-focused file automation app for macOS that watches folders and automatically moves, renames, tags, or labels files based on rules you define — it's built as a community alternative to the paid Hazel app.
Is Forel a background service or a window I keep open?It's a native SwiftUI/AppKit menu-bar app that runs quietly in the background. You can toggle rules on or off from the menu bar without ever opening the main window.
Do I need anything beyond macOS itself to use it?No accounts, API keys, or cloud services are needed to run the app. Building it from source requires Swift 6 and macOS 13 (Ventura) or later.
Can it search inside every kind of file when matching?Content matching reads text locally from many formats (PDF, Word, Excel, iWork, images via on-device OCR) but each has size/page limits, and some older formats (.xls, .ppt, .epub) fall back to macOS Spotlight, which only supports a 'contains' match and only works if the file is already indexed.
Does any of my file data leave my Mac?No — Forel is built to run entirely on-device with no account and no telemetry, and all content scanning including OCR happens locally.
Is there a catch with the GPL license?The source code is GPL-3.0-or-later and free to use or fork, but the Forel name, logo, and look are explicitly carved out and protected separately from the code license.
What actions can a rule actually perform on a file?Rules can move, copy, rename, tag, add a color label, trash, delete, uncompress, or run a custom script on matched files, with native notifications when an action fires.
Why use Forel instead of Hazel?Hazel is a well-known macOS automation tool but it's closed-source and paid; Forel offers similar rule-based folder automation while being free, open source (GPLv3), and fully local with no telemetry.
How does Forel detect new files in a watched folder?It uses a native wrapper around macOS FSEvents for low-latency, battery-friendly folder monitoring, so rules trigger in real time even while the window is closed.
What's still missing or planned for Forel?The roadmap lists unfinished items like export/import of rules, toggling hidden file extensions, compress/sync/upload actions, and AI features, while core features like rule engine, actions, SQLite persistence, and auto-updates are already done.
What are similar projects?dimble, tendedero, MacPacker, OpenYoink, FinderSearch, gyotaku, macos-sysdata, rooms
Which topics is it in?open-source-alternative, file-manager, menu-bar, offline-first, native, ocr, document-processing, macos-app, homebrew, workflow-automation, swift, pdf
Creator
lab421
Size
9.5 MB
Stars
832
Updated
CommitOct 15Releasev1.0.9Oct 02
Age
4mo
Commits · 90 Days