frequent-cron

A lightweight daemon and service manager that executes shell commands at sub-second intervals. Standard cron only supports minute-level granularity -- frequent-cron supports millisecond precision. Runs on Linux, macOS, FreeBSD, and Windows.

By default, command execution is blocking (synchronous): if a command takes longer than the configured interval, the next execution waits until the previous one completes. For example, a 500ms interval with a command that takes 3 minutes will effectively run once every 3 minutes.

You can set --synchronous=false to run commands asynchronously. Warning: running asynchronously can cause unbounded resource growth if the script never exits or is called too frequently (e.g. consuming too many database connections or too much memory). Synchronous (the default) is the safer option.

Licensed under the MIT License.

Dependencies

• Boost 1.37+ (components: asio, program_options)
• SQLite3
• CMake 3.14+
• C++23 compiler

See platform-specific install instructions in docs/.

Installation

git clone https://github.com/homer6/frequent-cron.git
cd frequent-cron
cmake .
make
make test
sudo make install

Usage

Running a Command Directly

frequent-cron run --frequency=1000 --command="/path/to/your/script.sh" --pid-file=/var/run/frequent-cron.pid

Or using legacy mode (backward compatible):

frequent-cron --frequency=1000 --command="/path/to/your/script.sh" --pid-file=/var/run/frequent-cron.pid

To stop:

kill $(cat /var/run/frequent-cron.pid)

Managing Named Services

Register, start, monitor, and stop services by name:

# Install a service
frequent-cron install myservice --frequency=1000 --command="/path/to/script.sh"

# Start it
frequent-cron start myservice

# Check status
frequent-cron status           # all services
frequent-cron status myservice  # specific service

# View logs
frequent-cron logs myservice

# List all services
frequent-cron list

# Stop and remove
frequent-cron stop myservice
frequent-cron remove myservice

Jitter and Probabilistic Firing

Add timing variance to spread load across services, or skip a percentage of ticks:

# Add up to 500ms of random jitter to each 1-second interval
frequent-cron run --frequency=1000 --command="echo tick" --jitter=500

# Use a normal distribution for jitter instead of uniform
frequent-cron install myservice --frequency=1000 --command="/path/to/script.sh" --jitter=200 --jitter-distribution=normal

# Fire only 40% of ticks (skip ~60% at random)
frequent-cron run --frequency=500 --command="echo tick" --fire-probability=0.4

Both options are off by default and work with all subcommands (run, install).

The install command also creates platform-native service definitions:

• Linux: systemd unit files
• macOS: launchd plists
• FreeBSD: rc.d scripts
• Windows: Windows Service (SCM) entries

Command-Line Options

Option	Description
--frequency	Interval in milliseconds between command executions
--command	Shell command to execute
--pid-file	Path to write the daemon's PID (optional)
--synchronous	Set to false for async execution (default: true)
--jitter	Random variance in milliseconds added to each interval (default: 0)
--jitter-distribution	Distribution for jitter: uniform or normal (default: uniform)
--fire-probability	Probability (0.0–1.0) of firing on each tick (default: 1.0)
--data-dir	Override the data directory path
--help	Display help

Platform Setup

• macOS: See docs/macos.md
• Ubuntu/Debian: See docs/ubuntu.md
• FreeBSD: See docs/freebsd.md
• Windows: See docs/windows.md

Documentation

Full documentation is available in docs/wiki/:

• Getting Started
• CLI Reference
• Service Management
• Service Lifecycle
• Architecture
• Logging
• FAQ
• Troubleshooting
• Contributing