lab421/forel

Forel

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

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 ☕

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

• Open source (GPLv3) — source code available, community-driven development.
• 100% on-device — no cloud, no API keys, no account. Your files never leave your Mac.
• Rule-based — match by name, extension, kind, size, date, tags, or color label.
• Native menu-bar app — runs quietly in the background; toggle rules without opening the window.
• Community-driven — built in the open, contributions welcome.

Features

• Rule-based automation — Create flexible rules combining filename patterns, file types, sizes, dates, tags, and Finder color labels.
• Folder watching — Monitor any number of folders in real time with native macOS FSEvents.
• Menu bar app — Forel lives in your menu bar. Toggle individual rules on/off without opening the main window.
• Actions — Move, copy, rename, tag, trash, delete, or run a custom script.
• SQLite persistence — Rules, folders, and history are stored locally in a bundled SQLite database.

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

• [x] Folder watching
• [x] Rule engine (name, extension, kind, size, date)
• [x] Actions: move, copy, rename, trash, delete, tag, run script
• [x] SQLite persistence
• [x] Menu bar icon with live rule toggle
• [x] Action history & undo
• [x] Automatic updates
• [x] Preferences: launch at login
• [x] Drag & drop to reorder rules
• [x] Rules based metadata files
• [x] Activity logs
• [x] Automatic cleaning database
• [x] Uncompress actions
• [x] Shortcuts actions
• [x] Open App actions
• [x] Validate actions / conditions before save
• [ ] Export / Import rules
• [ ] Toggle extension hidden / visible
• [ ] Compress actions
• [ ] Compress actions
• [ ] Sync actions
• [ ] Upload actions
• [x] Native notifications on rule actions
• [ ] AI features

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

---