randnotify

A little system for sprinkling some randomness into your week.

The idea is simple: instead of a rigid "every day at 9am" reminder that your brain learns to ignore, this pings you at unpredictable times on unpredictable days. A few times a week, whenever it feels like it, something pops up and nudges you toward whatever you told it to nudge you toward. It's a routine that doesn't feel like a routine.

Why

Mostly because reminders that arrive on a fixed schedule stop landing — you tune them out. Reminders that show up at odd, unpredictable moments actually get your attention. This started life as a way to randomly poke myself toward a folder of notes I kept forgetting existed, and turned into a generic little randomness machine you can point at anything.

How a week plays out

• Once a week, randnotify-week rolls the dice for each thing you want to be reminded about: how many times this week, which days, what time on each day. It writes those moments down as a list of timestamps.
• randnotify-check watches the clock and, when one of those moments arrives, fires off a desktop notification. If your machine was asleep when it should have fired, it catches up; if it gets restarted, it picks the schedule back up.

You don't manage any of it. You set it up once and then occasionally get surprised.

Adding your own reminders

Everything you want reminding about lives in a config file — one per thing. Drop a .conf file in ~/.config/randnotify/jobs/, say roughly how often and in what window of the day, write the message you want to see, and that's it. No code to touch.

# ~/.config/randnotify/jobs/whatever.conf
DAYS_MIN=1                            # at least this many times a week
DAYS_MAX=4                            # at most this many
TIME_MIN=$((SECONDS_PER_DAY / 24 * 16))   # 16:00 — earliest time of day
TIME_MAX=$((SECONDS_PER_DAY - 60))        # 23:59 — latest
TIME_STEP=60                          # snap to whole minutes
NOTIFY_TITLE="..."                    # the heading on the notification
NOTIFY_BODY="..."                     # the nudge itself

Want a second kind of reminder? Add another .conf. They're independent, they get their own random schedule, and you can have as many as you like (just keep DAYS_MAX at 7 or below — there are only so many days in a week).

There's an efforts.conf.example in this repo to copy from.

Setup

See PLAN.md for the full install steps. The short version: it's a few bash scripts plus systemd user timers, all symlinked out of this repo so the repo stays the single source of truth.

The one trick that makes it work

Days and times are just numbers. A time of day is "seconds since midnight." A day is "an offset from the start of the week." Once you see scheduling as picking random integers, you only need one tool to do the picking — randpick — and everything else is just arithmetic on top of it.

randpick --min 1 --max 10                      # one random number, 1–10
randpick --min 0 --max 518400 --step 86400 --count 3   # 3 random days in a week
randpick --min 57600 --max 86340 --step 60     # a random minute between 4pm and midnight

That's the whole primitive. Want random times? Pick integers. Random days? Pick integers. It doesn't know or care what it's choosing.

Under the hood

It's deliberately small — a handful of bash scripts, no dependencies beyond what's already on a Linux box. It's also developed with test driven development: every script has a matching test written before it, and tests/run-all.sh runs the whole suite. If you're poking at the internals, PLAN.md lays the build out as a series of bite-sized, self-contained steps you can tackle one at a time, red-green-refactor.

Fun part: this was built by AI, cheaply. The way it works: one orchestrating agent reads PLAN.md but doesn't write a line of the project itself — its only job is to hand out the work. For each step it spawns a fresh Haiku agent (the small, low-cost model) with a clean slate, gives it just that one step and the context that step needs — not the whole plan — and waits for it to go green before dispatching the next. The two talk through a narrow protocol: the orchestrator sends instructions plus a desired output format, and the sub-agent sends back a small structured report. The orchestrator acts only on that report — it never reads everything the sub-agent did along the way — which is what keeps its own context (and the bill) small. Each step is scoped tightly enough that a cold agent can pick it up and ship it green. No giant context, no premium model babysitting every line; just a clear plan, an orchestrator handing out steps in order, and a cheap agent per step. Working with AI, while keeping the bill small.

tests/run-all.sh   # run everything