🌰 Hazelnut

A terminal-based automated file organizer inspired by Hazel

Watch your folders and automatically organize files based on rules you define — all from your terminal.

📖 Table of Contents

• ✨ Features
• 🚀 Quick Start
• ⚙️ Configuration
• 📋 Rules
• ⌨️ Keybindings
• 🎨 Themes
• 🏗️ Architecture
• 🔧 Building from Source
• 🤝 Contributing
• 📄 License

✨ Features

Feature Highlights

🚀 Quick Start

Installation

macOS

# Homebrew (recommended - fast, pre-built binary)
brew install ricardodantas/tap/hazelnut

Linux

# Homebrew
brew install ricardodantas/tap/hazelnut
Or via Cargo
cargo install hazelnut

Arch Linux (pacman)

pacman -S hazelnut

Windows

# Via Cargo (requires Rust toolchain)
cargo install hazelnut
Or download pre-built binary from GitHub Releases:
https://github.com/ricardodantas/hazelnut/releases

From Source

git clone https://github.com/ricardodantas/hazelnut
cd hazelnut
cargo install --path .

Note: The daemon (hazelnutd) is only available on macOS and Linux. On Windows, only the TUI (hazelnut) is available.

First Run

Hazelnut needs two things to work:

1. Watch folders — which directories to monitor
2. Rules — what to do with files in those folders

⚠️ Important: Rules alone won't do anything! You must also configure at least one watch folder.

1. Create a config file at ~/.config/hazelnut/config.toml:

# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# STEP 1: Define which folders to watch
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[[watch]]
path = "/home/youruser/Downloads"  # Full path, ~, $HOME all work
recursive = false                   # Set true to include subfolders
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
STEP 2: Define rules for what to do with files
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[[rule]]
name = "Organize PDFs"
[rule.condition]
extension = "pdf"
[rule.action]
type = "move"
destination = "/home/youruser/Documents/PDFs"

2. Launch the TUI to manage and monitor:

hazelnut

3. Or start the daemon to run in the background:

hazelnutd start

⚙️ Configuration

Hazelnut uses TOML for configuration. The config file is always located at:

~/.config/hazelnut/config.toml

Full Configuration Example

# ─────────────────────────────────────────────────────────────
# General Settings
# ─────────────────────────────────────────────────────────────
[general]
Logging level: trace, debug, info, warn, error
log_level = "info"
Optional log file path
log_file = "~/.local/share/hazelnut/hazelnut.log"
Wait time (seconds) before processing a file after change detected
debounce_seconds = 2
How often to check for file changes (seconds)
polling_interval_secs = 5
Desktop notifications on errors (cross-platform)
notifications_enabled = true
Theme for the TUI
theme = "catppuccin-mocha"
─────────────────────────────────────────────────────────────
Watch Folders
─────────────────────────────────────────────────────────────
[[watch]]
path = "~/Downloads"
recursive = false
[[watch]]
path = "~/Desktop"
recursive = false
Only apply specific rules to this folder
rules = ["screenshots", "temp-files"]
[[watch]]
path = "~/Documents/Inbox"
recursive = true  # Watch subdirectories too
─────────────────────────────────────────────────────────────
Rules
─────────────────────────────────────────────────────────────
[[rule]]
name = "Organize PDFs"
enabled = true
stop_processing = false  # Continue checking other rules
[rule.condition]
extension = "pdf"
[rule.action]
type = "move"
destination = "~/Documents/PDFs"
create_destination = true
overwrite = false
[[rule]]
name = "Screenshots"
enabled = true
[rule.condition]
name_matches = "Screenshot*.png"
[rule.action]
type = "move"
destination = "~/Pictures/Screenshots"
[[rule]]
name = "Clean Old Downloads"
enabled = true
[rule.condition]
age_days_greater_than = 30
extensions = ["tmp", "log", "bak"]
[rule.action]
type = "trash"

See docs/configuration.md for the complete reference.

Watch Editor (TUI)

You can manage watch folders directly in the TUI:

1. Add a new watch: Press a or n in the Watches view
2. Edit an existing watch: Select a watch and press e
3. Delete a watch: Select a watch and press d

The watch editor dialog allows you to configure:

• Path - Path to the folder to watch (supports ~, $VAR, ${VAR}, or absolute paths)
• Recursive - Whether to include subdirectories

Use Tab to move between fields, Enter to save, and Esc to cancel.

📋 Rules

Rules are the heart of Hazelnut. Each rule has a condition (what files to match) and an action (what to do with them).

Conditions

All conditions in a rule must match for the rule to apply.

File Name

[rule.condition]
# Glob pattern matching
name_matches = "Screenshot*.png"
Regex pattern matching
name_regex = "^invoice_\d{4}\.pdf$"

File Extension

[rule.condition]
# Single extension
extension = "pdf"
Multiple extensions (match any)
extensions = ["jpg", "jpeg", "png", "gif", "webp"]

File Size

[rule.condition]
# Size in bytes
size_greater_than = 10485760  # > 10 MB
size_less_than = 1048576      # < 1 MB

File Age

[rule.condition]
# Age in days (based on modification time)
age_days_greater_than = 30  # Older than 30 days
age_days_less_than = 7      # Newer than 7 days

File Type

[rule.condition]
is_directory = false  # Match only files
is_hidden = true      # Match hidden files (starting with .)

Actions

Move

[rule.action]
type = "move"
destination = "~/Documents/Archive"
create_destination = true  # Create folder if missing
overwrite = false          # Don't overwrite existing files

Copy

[rule.action]
type = "copy"
destination = "~/Backup"
create_destination = true
overwrite = false

Rename

[rule.action]
type = "rename"
pattern = "{date}_{name}.{ext}"

Available variables:

Trash

[rule.action]
type = "trash"

Moves files to the system trash (recoverable).

Delete

[rule.action]
type = "delete"

⚠️ Warning: This permanently deletes files!

Run Command

[rule.action]
type = "run"
command = "convert"
args = ["{path}", "-resize", "50%", "{dir}/{name}_small.{ext}"]

Archive

[rule.action]
type = "archive"
destination = "~/Archives"
delete_original = false

Rule Editor (TUI)

You can create and edit rules directly in the TUI without editing the config file:

1. Create a new rule: Press n in the Rules view
2. Edit an existing rule: Select a rule and press e
3. Delete a rule: Select a rule and press d

The rule editor dialog allows you to configure:

• Name - A descriptive name for your rule
• Enabled - Toggle the rule on/off
• Conditions - Extension, name patterns (glob/regex), size limits, age limits, is_directory, is_hidden
• Action - Move, Copy, Rename, Trash, Delete, Run Command, or Archive

Use Tab to move between fields, Enter to save, and Esc to cancel.

💡 Remember: Rules only apply to files in watched folders. Make sure you've configured at least one [[watch]] entry in your config, or add one via the Watches view.

Example Rules

[[rule]]
name = "Screenshots to folder"

[rule.condition]
name_matches = "Screenshot*.png"

[rule.action]
type = "move"
destination = "~/Pictures/Screenshots"

[[rule]]
name = "PDFs to Documents"

[rule.condition]
extension = "pdf"

[rule.action]
type = "move"
destination = "~/Documents/PDFs"

[[rule]]
name = "Spreadsheets to Documents"

[rule.condition]
extensions = ["xlsx", "xls", "csv"]

[rule.action]
type = "move"
destination = "~/Documents/Spreadsheets"

[[rule]]
name = "Delete old temp files"

[rule.condition]
age_days_greater_than = 30
extensions = ["tmp", "log", "bak"]

[rule.action]
type = "trash"

[[rule]]
name = "Prefix invoices with date"

[rule.condition]
name_regex = "^invoice.*\\.pdf$"

[rule.action]
type = "rename"
pattern = "{date:YYYY-MM-DD}_{filename}"

[[rule]]
name = "Compress large images"

[rule.condition]
extensions = ["jpg", "png"]
size_greater_than = 5242880  # > 5 MB

[rule.action]
type = "run"
command = "convert"
args = ["{path}", "-quality", "80", "{path}"]

⌨️ Keybindings

Global

Navigation

Rules View

Watches View

Log View

Theme Picker

🎨 Themes

Hazelnut includes 15 beautiful themes based on popular terminal and editor color schemes.

Press t in the TUI to open the theme picker with live preview.

Available Themes

🏗️ Architecture

Hazelnut consists of two binaries that work together:

┌─────────────────────────────────────────────────────────────┐
│                         User                                │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                       hazelnut (TUI)                            │
│  • Manage rules                                             │
│  • Monitor activity                                         │
│  • Change themes                                            │
│  • View logs                                                │
└─────────────────────────────────────────────────────────────┘
                              │
                         Unix Socket
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                     hazelnutd (Daemon)                          │
│  • Watch folders                                            │
│  • Evaluate rules                                           │
│  • Execute actions                                          │
│  • Run 24/7 in background                                   │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                      File System                            │
└─────────────────────────────────────────────────────────────┘

hazelnut — The TUI

Interactive terminal interface for:

• Viewing and managing rules
• Monitoring watch folders
• Viewing activity logs
• Changing themes
• Sending commands to the daemon

hazelnut              # Launch TUI
hazelnut list         # List all rules
hazelnut check        # Validate config
hazelnut run          # Run rules once (dry-run)
hazelnut run --apply  # Run rules once (for real)
hazelnut status       # Check daemon status

hazelnutd — The Daemon

Background service that does the actual work:

hazelnutd start      # Start daemon (background)
hazelnutd stop       # Stop daemon
hazelnutd restart    # Restart daemon
hazelnutd status     # Show daemon status
hazelnutd reload     # Reload configuration (hot-reload, no restart)
hazelnutd run        # Run in foreground (for debugging)

Daemon Commands

Status Output

$ hazelnutd status
🌰 Hazelnut daemon is running
   PID: 12345
   PID file: ~/.local/state/hazelnut/hazelnutd.pid
   Log file: ~/.local/state/hazelnut/hazelnutd.log
   Uptime: 2h 15m 30s

File Locations

All files use consistent paths across Linux and macOS:

Typical Workflow

# 1. Edit your rules in the TUI or config file
hazelnut
2. Start the daemon
hazelnutd start
3. Check it's running
hazelnutd status
4. After editing rules, reload without restart
hazelnutd reload
5. View logs if needed
tail -f ~/.local/state/hazelnut/hazelnutd.log

🔧 Building from Source

Requirements

• Rust 1.93+ (uses Edition 2024 features)
• Linux or macOS

Build

# Clone the repository
git clone https://github.com/ricardodantas/hazelnut
cd hazelnut
Build release binary
cargo build --release
The binaries will be at:
- target/release/hazelnut
- target/release/hazelnutd
Or install directly
cargo install --path .

Development

# Run TUI in development
cargo run
Run daemon in foreground
cargo run --bin hazelnutd run
Run tests
cargo test
Run linter
cargo clippy
Format code
cargo fmt

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Quick Start for Contributors

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes
4. Run tests: cargo test
5. Run clippy: cargo clippy
6. Format: cargo fmt
7. Commit: git commit -m "Add amazing feature"
8. Push: git push origin feature/amazing-feature
9. Open a Pull Request

Project Structure

hazelnut/
├── src/
│   ├── main.rs          # TUI entry point
│   ├── daemon.rs        # Daemon entry point
│   ├── lib.rs           # Library root
│   ├── theme.rs         # Color themes
│   ├── app/             # TUI application
│   │   ├── events.rs    # Key event handling
│   │   ├── state.rs     # Application state
│   │   └── ui.rs        # UI rendering
│   ├── config/          # Configuration loading
│   ├── rules/           # Rule engine
│   │   ├── action.rs    # Rule actions
│   │   ├── condition.rs # Rule conditions
│   │   └── engine.rs    # Rule evaluation
│   ├── watcher/         # File system watcher
│   └── ipc/             # TUI-daemon communication
├── docs/
│   └── configuration.md # Full config reference
├── screenshots/         # Screenshots for docs
└── tests/               # Integration tests

📄 License

This project is licensed under the GPL-3.0-or-later license — see the LICENSE file for details.

_{Built with 🦀 Rust and ❤️ by Ricardo Dantas}