alarm_app/README.md

alarm_widg

Minimal alarm scheduler, part of CandyWidgets.

Reads alarms from a TOML configuration file and triggers them at the configured times.

Work in progress: The project is still under active development and may change.

Install

Build the release binary:

cargo build --release

Install it somewhere in your $PATH, for example:

install -Dm755 target/release/alarm_widg ~/.local/bin/alarm_widg

Install the systemd user service:

mkdir -p ~/.config/systemd/user
cp extra/alarm-widg.service ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now alarm-widg.service

Check the service:

systemctl --user status alarm-widg.service

Configure

Create or edit:

~/.config/candywidgets/alarm-app/config.toml

Example:

# Daily task
[[alarm]]
title = "Take medication"
time = "08:00"
days = [1, 2, 3, 4, 5, 6, 0]

# Daily task, disabled
[[alarm]]
title = "Check personal email"
time = "18:00"
days = [1, 2, 3, 4, 5, 6, 0]
enabled = false

# Weekly task
[[alarm]]
title = "Water plants"
time = "10:00"
days = [0]

# A few days each week
[[alarm]]
title = "Exercise"
time = "17:30"
days = [1, 3, 5]

# Specific date
[[alarm]]
title = "Submit monthly report"
time = "16:00"
dates = ["2026-08-31"]

# Multiple specific dates
[[alarm]]
title = "Project deadlines"
time = "17:00"
dates = [
    "2026-08-15",
    "2026-08-22",
    "2026-08-29",
]
color = "FFFFCC00"

Options

Option	Description
title	Alarm title
time	Time in HH:MM format
days	Recurring days, 0 = Sunday through 6 = Saturday
dates	Specific dates in YYYY-MM-DD format
color	Optional ARGB hexadecimal color
enabled	Enable or disable the alarm, defaults to true

Each alarm must specify either days or dates.

License

GPL-3.0-or-later. See LICENSE.