Recur

Recur is a cross-platform configuration-driven automation toolset consisting of a daemon and CLI supported by a flexible plugin system. It is written in Go and runs locally on the system.

Official documentation: https://directedbits.github.io/recur/

Simply define what events to wait for — file changes, cron schedules, webhooks, MQTT messages, calendar events, USB devices, or Docker containers — and how to respond.

Install

Pre-built binaries for Linux (amd64, arm64, armv7, i386) and macOS (amd64, arm64) are available on the Releases page. Each release ships a sha256 checksum file and a Sigstore cosign signature — see VERIFYING.md for the verify commands.

Using Go 1.25+:

go install github.com/directedbits/recur/src/app/recur@latest   # CLI
go install github.com/directedbits/recur/src/app/recurd@latest  # Daemon

Building from source:

git clone https://github.com/directedbits/recur.git
cd recur
task build    # outputs bin/recur and bin/recurd

Quick Start

# Start the daemon
recur start

# Create a config file with stubbed values for a FileCreated trigger and shell execution action
recur add MyProject FileCreated --actions=shell --stub --edit

# Check status
recur status

The add command writes the recurfile and auto-registers it with the daemon. Use recur register to register an existing recurfile manually.

Example Configuration

Build:
  on:
    - type: cron
      options:
        expression: "0 2 * * *"
  do:
    - shell: "make build"

Deploy:
  on:
    - type: WebhookReceived
      options:
        port: "9090"
        path: "/deploy"
        secret: "my-secret"
  do:
    - shell: "deploy.sh"

See the recurfile format documentation for the full syntax including template variables, aliases, group options, and scopes.

Plugins

Plugin	Triggers	Actions	Description
fileevents	FileCreated, FileModified, FileDeleted, FileMoved, FileAttributeChanged	—	File system event monitoring
timer	cron, interval	—	Cron schedule and interval triggers
webhook	WebhookReceived	—	HTTP/HTTPS webhook receiver with HMAC verification
mqtt	MessageReceived	publish	MQTT subscribe and publish
calendar	EventUpcoming, EventStarted, EventEnded	—	iCal/ICS calendar polling
devicemonitor	DeviceConnected, DeviceDisconnected	—	USB/device hotplug (Linux + Windows)
docker	ContainerStarted, ContainerStopped, HealthChanged	ContainerStart, ContainerStop, ContainerRestart	Docker container lifecycle

The first-party plugins above are now maintained in their own repositories under the directedbits org. Install one from its release archive with recur install <release-archive-url> (releases live at https://github.com/directedbits/recur-<plugin>/releases). Remote installs require the host to be allowed first: recur config set allowed_hosts github.com.

How It Works

1. The daemon (recurd) runs in the background, managing the plugin lifecycle and trigger/action registry
2. Config files declare what triggers to listen for and what actions to take
3. Plugins are standalone binaries that implement triggers and actions via an exec-based contract (stdin JSON for config, gRPC callback for events)
4. The CLI (recur) communicates with the daemon via a Unix socket, with graceful fallback to file reads when the daemon isn't running

State is persisted to ~/.config/recur/state/state.json so triggers and their error counts survive restarts.

Documentation

• Getting Started
• Recurfile Format
• CLI Reference
• Settings
• Plugins
• Architecture
• Developer Guide

Contributing

See CONTRIBUTING.md for development setup, coding standards, and how to submit changes.

Security

See SECURITY.md for the security policy and how to report vulnerabilities.

Code of Conduct

This project follows the Contributor Covenant Code of Conduct.

License

This project is licensed under the Mozilla Public License 2.0.