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 名称、Logo 和外观被明确排除在外，与代码许可证分开保护。
规则实际上能对文件执行哪些操作？规则可以对匹配的文件执行移动、复制、重命名、打标签、添加颜色标记、移入废纸篓、删除、解压缩或运行自定义脚本，操作触发时会有系统原生通知。
为什么用 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