Docs · Sheet 01 of 05

Getting started

Install Cuckoo, let macOS run it in the background, and write your first Job. It takes a few minutes.

Requirements

• macOS 26 or later.
• A shell you already use. Cuckoo runs each Command in your login shell, so your PATH and profile apply.

Install

1. Download Cuckoo-0.1.0.dmg and open it.
2. Drag Cuckoo to Applications.
3. Open Cuckoo from Applications. Its icon appears in the menu bar, not in the Dock.

Cuckoo has to run from /Applications. A copy anywhere else can't register its background agent, so its Jobs don't run.

Approve it in Login Items

The Jobs are run by a small background agent. macOS asks you to allow it once. Until you do, the popover says:

Click Open Settings… and turn Cuckoo on in Login Items. The notice goes away and the Jobs start.

• Open at Login, in the popover, brings the menu bar icon back after you log in. It is on by default. The Jobs run either way.

Your first Job

Choose New Job… in the popover, or press ⌘N. Give it a name, a Command, and a Schedule, then save.

Or write the file yourself. Save this as ~/.config/cuckoo/disk-space.toml:

1# Fails when the startup disk is more than 90% full.2name = "Disk space"3command = '''4df -h /5used=$(df / | awk 'NR==2 {gsub("%", "", $5); print $5}')6test "$used" -lt 907'''8every = 60

Cuckoo picks it up within a second and runs it every hour. A Run fails when the Command exits with a non-zero status. Here, that is when test finds the disk too full. The first failure sends a notification to this Mac.

Next steps

• Job files: every key, and how Schedules work.
• Notifications: get them on your iPhone with ntfy.
• CLI: check a file, or run a Job, from the terminal.