random-gate

Tiny composable probabilistic gate CLI for cron jobs, scripts, Ansible hooks, and agent workflows.

It flips a weighted coin and communicates the result through the process exit code:

• exit 0 = HIT: run the guarded action;
• exit 1 = MISS: skip silently;
• exit 2 = usage/runtime error.

Default output is silent, so it composes cleanly in cron and shell scripts.

Install

From a local checkout:

python3 -m pip install .

For isolated CLI installs, pipx is nicer:

pipx install .

Or during development:

python3 -m pip install -e .

Usage

random-gate 0.05 && echo "runs about 5% of the time"
random-gate 5% && ./maintenance-task
random-gate 1/20 && ./maintenance-task

Human-readable output:

random-gate 0.30 --verbose

JSON output:

random-gate 0.30 --json

Deterministic per day/label:

random-gate 0.10 --label homelab-nudge --seed "$(date +%Y-%m-%d)"

Cron example:

# Every morning, about 5% chance of emitting a reminder.
0 9 * * * random-gate 0.05 && echo "Review the low-priority backlog"

With jitter:

random-gate 0.30 --sleep-jitter 900 && ./low-priority-check

Probability syntax

All are equivalent:

random-gate 0.05
random-gate 5%
random-gate 1/20

Probability must be between 0 and 1 inclusive.

Help

random-gate -h
random-gate --help