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
Что это?Forel — открытое приложение для macOS, ориентированное на приватность и автоматизацию работы с файлами: оно следит за папками и автоматически перемещает, переименовывает, помечает тегами или цветными метками файлы по заданным вами правилам — это созданная сообществом альтернатива платному приложению Hazel.
Forel — это фоновая служба или окно, которое держишь открытым?Это нативное приложение в строке меню на SwiftUI/AppKit, которое тихо работает в фоне. Включать и выключать правила можно прямо из строки меню, вообще не открывая главное окно.
Нужно ли что-то помимо самой macOS, чтобы им пользоваться?Для работы приложения не нужны ни аккаунты, ни API-ключи, ни облачные сервисы. Для сборки из исходников требуются Swift 6 и macOS 13 (Ventura) или новее.
Может ли он при сопоставлении искать внутри файлов любого типа?Поиск по содержимому читает текст локально из многих форматов (PDF, Word, Excel, iWork, изображения через OCR на устройстве), но у каждого есть ограничения по размеру/числу страниц, а часть старых форматов (.xls, .ppt, .epub) обрабатывается через macOS Spotlight, который поддерживает только поиск по вхождению и работает, лишь если файл уже проиндексирован.
Покидают ли мои файловые данные Mac?Нет — Forel создан работать целиком на устройстве, без аккаунта и телеметрии, и всё сканирование содержимого, включая OCR, происходит локально.
Есть ли подвох в лицензии GPL?Исходный код — под GPL-3.0-or-later, его можно свободно использовать и форкать, но имя Forel, логотип и внешний вид явно исключены и защищены отдельно от лицензии на код.
Какие действия правило может выполнять с файлом?Правила могут перемещать, копировать, переименовывать, помечать тегами, добавлять цветную метку, отправлять в корзину, удалять, распаковывать или запускать пользовательский сценарий над найденными файлами, с нативными уведомлениями при срабатывании.
Почему Forel, а не Hazel?Hazel — известный инструмент автоматизации для macOS, но он закрытый и платный; Forel предлагает похожую автоматизацию папок по правилам, оставаясь бесплатным, открытым (GPLv3) и полностью локальным, без телеметрии.
Как Forel замечает новые файлы в отслеживаемой папке?Он использует нативную обёртку вокруг macOS FSEvents для мониторинга папок с низкой задержкой и бережным расходом батареи, так что правила срабатывают в реальном времени даже при закрытом окне.
Чего в Forel ещё не хватает и что запланировано?В дорожной карте значатся незавершённые пункты вроде экспорта/импорта правил, переключения показа скрытых расширений файлов, действий сжатия/синхронизации/загрузки и AI-функций, тогда как ключевые вещи — движок правил, действия, хранение в SQLite и автообновления — уже сделаны.
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