# Maid for rule-based file cleanup and renaming

> Maid is a Ruby gem for developers who want to clean up, move, or rename files through rules defined in Ruby. It supports dry runs and action logging, but it is not a continuous file watcher and its regularly tested platforms are limited.

**maid/maid** — Be lazy.  Let Maid clean up after you, based on rules you define.  Think of it as "Hazel for hackers".

- Repository: https://github.com/maid/maid
- Website: http://rubygems.org/gems/maid
- Stars: 1,912 · Forks: 86
- Language: Ruby
- License: GPL-2.0
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/maid-maid

## Maid's file cleanup use case and intended operators

Maid addresses the accumulation of temporary downloads and other files that are left untouched because sorting them manually is repetitive. Its intended users are programmers and system administrators comfortable expressing repeatable housekeeping tasks as code. The README compares Maid to email filters, except that the object is a file rather than a message, and it also describes the project as an advanced file renaming tool.

That positioning matters. Maid is not limited to deleting old downloads. Its rules can inspect files, test conditions, and call actions such as `move` or `trash`. The README includes a rule that searches `~/Downloads/*`, checks whether a file was downloaded from `http://localhost`, and checks how long ago it was accessed. A separate example moves PDF files from `~/Downloads` to `~/Books`.

The project is aimed at people who want rules to remain readable, reviewable, and versionable in Ruby. However, the README does not describe Maid as a daemon, background watcher, or event-driven file monitor. Commands invoke rules when Maid runs. A cron entry is mentioned in connection with uninstall cleanup, which indicates that scheduling may be relevant to a user's setup, but the README does not document a built-in scheduler or its configuration. Users who need immediate reactions to newly created files should verify their external scheduling mechanism before assuming Maid supplies one.

## How Maid evaluates Ruby rules

Maid's configuration is executable Ruby. Rules are grouped through `Maid.rules`, each rule receives a descriptive name, and the rule body performs file operations. A small domain-specific language makes common operations such as selecting directories more concise, while ordinary Ruby constructs remain available.

The documented example uses `dir('~/Downloads/*').each` to iterate over matching paths. Conditions then combine metadata operations with Ruby logic. `downloaded_from(path)` returns URLs associated with a path, while `accessed_at(path)` supplies access information used by `1.week.since?`. If both conditions match, `trash(path)` handles the file. This structure makes the decision path visible: select candidate paths, inspect metadata, evaluate a condition, and invoke an action.

Maid also accepts a traditional `for` loop for developers who prefer that syntax. Rules can therefore express more than a fixed list of paths or filename patterns. The trade-off is direct: this flexibility comes with a requirement to execute Ruby and to review the logic in `~/.maid/rules.rb`. A malformed or overly broad rule can affect unintended files, so understanding the code is part of using the tool.

The README states that Maid does not overwrite files and that actions are logged. Those properties make review and later inspection more practical, but the README does not claim that destructive actions can be undone or that every possible filesystem state is protected. Dry-run support remains the documented safeguard before execution.

## Installing Maid and creating the first rules file

Maid is distributed as a Ruby gem. The documented requirements are Ruby 2.7.0 or later, with Ruby 3.0.0 or later preferred. Only macOS and Ubuntu are tested regularly, and some features require macOS. Install the gem through RubyGems:

```bash
gem install maid
```

A successful installation places the `maid` executable in the user's Ruby environment. If Ruby is not already present, the README points to version managers such as `rvm`, `rbenv`, and `rtx`. It also recommends Ruby 3 because Ruby 2.7 is described as end-of-life.

Generate the sample rules file after installation:

```bash
maid sample
```

The repository identifies `lib/maid/rules.sample.rb` as the sample source. The tutorial says Maid normally runs rules from `~/.maid/rules.rb` and writes activity to `~/.maid/maid.log`. Editing that file is the first real configuration step. A minimal move rule can be created in the documented Ruby format:

```ruby
Maid.rules do
  rule 'downloaded PDF books' do
    move(dir('~/Downloads/*.pdf'), '~/Books')
  end
end
```

This rule targets PDF files in `~/Downloads` and sends them to `~/Books`. Before applying it, preview the actions without taking them:

```bash
maid clean -nr some_rules.rb
```

The short options combine rule-file selection with dry-run behavior. The path must identify a rules file that actually exists. The preview can be run before and after changing the rule so that its intended file selection is visible before execution.

## Dry runs, explicit execution, and action logs

Maid separates inspection from execution through `maid clean`. The dry-run command performs no actions and displays what the rules would do:

```bash
maid clean --dry-run
```

The README also lists `-n` and `--noop` as synonyms. To execute the default rules from `~/.maid/rules.rb`, use the force flag:

```bash
maid clean -f
```

That command logs to `~/.maid/maid.log`. A different rules file can be supplied with the short rule-file option:

```bash
maid clean -fr some_rules.rb
```

This is a useful operational model for personal machines because rules do not take effect at the instant a file changes. It also makes a review stage explicit. The presence of a force flag is worth noticing: invocation is not the same as preview, and installing Maid does not run any cleanup by itself.

The log provides an audit trail, but the README does not document log formats, retention, rotation, or a dedicated command for reviewing or reverting actions. Uninstalling the gem also leaves `~/.maid` files and crontab entries behind:

```bash
gem uninstall maid
```

Removing the package therefore does not remove the configuration or scheduling residue described in the README. Users need to inspect `~/.maid` and relevant crontab entries separately.

## Maintenance, upgrades, and GPL-2.0 effects

The repository is not archived, and its last push was on 2026-09-10. Version `v0.11.3` was released on 2026-09-10, following `v0.11.2` on 2025-11-29 and `v0.11.1` on 2025-08-16. Those dates indicate recent repository activity, although the README states that only macOS and Ubuntu are tested regularly. That distinction is important when adopting Maid on another Unix-like system or a newer Ruby configuration.

The documented upgrade path preserves the installed gem name:

```bash
gem update maid
```

The repository also contains a Ruby 3.4 Dockerfile, a Gemfile, a lockfile, and the gemspec. This gives the project conventional packaging and a defined bundle for that container configuration, but the Docker image is described primarily as a development environment. Its command starts Guard through Bundler rather than acting as a production deployment example for file cleanup.

Maid is distributed under `GPL-2.0`. The direct operational implication is that users should account for the license when distributing modified versions or incorporating the software into another distributed work. This is not legal advice. Internal use, modification, and redistribution can involve different obligations, so teams needing a license review should read the repository's `LICENSE` file and obtain appropriate guidance.

Upgrade cost also includes reviewing rule files. Since rules are Ruby rather than a declarative data format, a new Maid release can be evaluated against real rules, but migration requirements are not documented in the README. The user must check `CHANGELOG.md` and test with `--dry-run` after upgrading.

## Maid's limits and a different automation approach

Maid's main limitation is that it is tied to Ruby and to explicitly invoked rules. It does not present itself as a cross-platform desktop automation program. Although the README says modern Ruby and Unix-like systems should work, regular testing is limited to macOS and Ubuntu, and some features require macOS. That makes host compatibility a pre-adoption check rather than an assumption.

It is also the wrong tool for someone who wants non-programmers to maintain cleanup behavior through a graphical interface. Rules contain Ruby expressions and filesystem operations, so understanding the code is necessary. The README does not document rollback. Although it promises logging and no file overwriting, an action log is not the same as an undo system.

Hazel is the conceptual alternative named by the project. Maid was inspired by that macOS shareware file automation program, but Maid presents rules as Ruby and installs as a gem. A user who chooses Hazel would be choosing a different project. The README does not document Hazel's current capabilities, so the comparison here is limited to Maid's stated inspiration.

A plain cron-based shell approach is another possible route for fixed cleanup jobs, particularly for users who do not want Ruby rules. The README mentions crontab entries but does not provide a cron configuration example or claim parity with Maid's metadata-aware rule DSL. The decision therefore rests on maintainability and matching file conditions. Use Maid when Ruby-based rules and dry-run review fit the task, and verify another approach when simple scheduled commands are sufficient.

## Conclusion

Maid fits developers who want repeatable, reviewable file management rules in Ruby and can operate within its documented macOS and Ubuntu support. It is less suitable for users seeking a general desktop automation watcher or a tool whose cleanup logic is independent of Ruby. Before adoption, run `maid clean --dry-run` against representative files, inspect the proposed actions and `~/.maid/maid.log`, then confirm that the chosen Ruby version and any macOS dependent operations match the host environment.

## FAQ

### How do I install Maid on macOS or Ubuntu?

Install Ruby 2.7.0 or later, with Ruby 3.0.0 or later preferred, then run `gem install maid`. The README regularly tests macOS and Ubuntu only, and notes that some features require macOS.

### Where does Maid store its rules and logs?

The documented default rules file is `~/.maid/rules.rb`, and executed actions are logged to `~/.maid/maid.log`. A different rules file can be passed with `maid clean -fr some_rules.rb`.

### Can I preview Maid cleanup actions before deleting or moving files?

Yes. Run `maid clean --dry-run`, or use the documented `-n` and `--noop` synonyms, to see what the rules would do without taking those actions.

## Sources

- [License: GPL-2.0](https://github.com/maid/maid/blob/master/LICENSE)
- [maid/maid on GitHub](https://github.com/maid/maid)
- [Project website](http://rubygems.org/gems/maid)
- [README](https://github.com/maid/maid/blob/master/README.md)
- [Releases](https://github.com/maid/maid/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/maid-maid