Skip to main content

zrb-nudge

Scheduled reminders for zrb. A reminder is a line in a JSON file; two tools write that file, and a trigger reads it and offers the agent a turn when a reminder's moment comes. Nothing here needs a window or a face: it works in any zrb chat.

Install

pipx install zrb-nudge        # or: pip install zrb-nudge, next to zrb
zrb-nudge install             # append the export line to your shell profile, once
zrb chat

zrb-nudge install appends this line to the profile your shell reads (~/.zshrc for zsh, ~/.bashrc for bash, else ~/.profile) and prints what it wrote:

export ZRB_INIT_SCRIPTS="$ZRB_INIT_SCRIPTS:/…/site-packages/zrb_nudge/zrb_init.py"

Open a new shell afterwards. zrb-nudge uninstall takes that line out again and leaves the rest of the file alone.

Using it

Ask the agent, in a normal turn:

remind me at 15:30 that the deploy starts at 16:00

stop reminding me to stretch

It answers with AddSchedule or RemoveSchedule. You can also write the file yourself — the tools read exactly what they wrote:

zrb-nudge show     # the file, the schedules in it, and what has been said today

The file

~/.zrb/nudge.json, or wherever ZRB_NUDGE_FILE points:

{
  "schedules": [
    {
      "id": "lunch",
      "at": "12:00",
      "within": 120,
      "repeat": "daily",
      "message": "It is lunchtime and the user is still working."
    }
  ],
  "said": {"lunch": "2026-11-09T12:00"}
}
Key What it means
id The name RemoveSchedule takes. Leave it off in a tool call and it is made from the first words of the message.
at A time of day on the 24-hour clock, 12:30. 24:00 is the end of the day.
within Minutes after at during which the moment is still true, so a zrb started at 13:10 can still mention the 12:00 lunch. Past that, the moment is gone and the next one is tomorrow.
repeat daily, weekdays (Monday to Friday) or once. A once reminder removes itself after it has been said, since it has nothing left to say.
message The situation, not the words: the turn says it in the agent's own voice.
said When each moment was last used. Written by the trigger, not by you.

A window that runs past midnight is a window: 23:30 with within: 60 is still due at 00:15, and it is still 23:30's reminder. Only these keys are kept; anything else you add is dropped on the next write.

Settings

The prefix follows zrb's own (CFG.ENV_PREFIX, ZRB by default), so a white-labeled zrb reads its own names.

Setting Default Read by What it does
ZRB_NUDGE auto zrb_init.py auto offers a turn when a moment is due and unsaid; off never does.
ZRB_NUDGE_FILE ~/.zrb/nudge.json both The schedule file.
ZRB_NUDGE_SECONDS 60 zrb_init.py Seconds between looking at the file. Reading it costs nothing, so a due moment arrives within a minute.
ZRB_NUDGE_PROMPT Before saying anything, check whether the user is at the desk … otherwise reply exactly {nothing_to_say}. Otherwise say this to the user in your own words, briefly. zrb_init.py What the turn asks for, after the reminder itself. {nothing_to_say} is the one placeholder it reads (…); an empty value asks for nothing, so the reminder is the whole turn.
ZRB_NUDGE_PROFILE empty zrb-nudge install The profile to write, instead of the one this shell reads.

What a nudge turn is

A due moment becomes a user turn that says so:

[nudge 12:00, not typed by the user] It is lunchtime and the user is still working.
Before saying anything, check whether the user is at the desk — AvatarStatus answers it
where zrb-avatar is loaded — and if nobody is there reply exactly … , so nothing is said.
Otherwise say this to the user in your own words, briefly.
  • It is a normal turn: the model answers it with its tools, its memory and its rules.
  • The presence check is the agent's, not this package's. A reminder is worth saying to somebody; whether somebody is there is a fact only a face can supply. Where zrb-avatar is loaded its AvatarStatus (and the face — line in every turn) answers it, and its speech backend shows … without speaking it. Where it is not, the model has nothing to check and simply says the reminder.
  • A turn that starts while another is running is queued behind it, not dropped.
  • One moment per look, earliest first: three reminders due at once arrive as three turns a minute apart, not one wall of text.
  • The moment is written to said before the turn starts, so a turn that errors, a restart, or two zrb processes on the same file cannot say the same thing twice.

Independence

Nothing here imports zrb-avatar, reads its files, or knows it exists; the two packages share a convention (… for "nothing to say") and a question, not a call. zrb-avatar's side of the bargain is presence: it knows whether someone is at the desk and answers AvatarStatus. So a chat with no face still gets its reminders, and a chat with one gets them only when someone is looking.

The command line

Command What it does
zrb-nudge init-path Prints the zrb_init.py to add to ZRB_INIT_SCRIPTS, for a profile this command does not write.
zrb-nudge install [profile] Appends the export line to the profile, once, and says what it wrote.
zrb-nudge uninstall [profile] Removes that line and its marker, and nothing else.
zrb-nudge show The schedule file, the schedules in it, and what has been said today.

Develop

pip install -e ".[zrb]"
python test_nudge.py    # the file, the tools, the trigger and the command line
python test_ci.py       # the CI configuration is what keeps a secret out of a pull request
File Role
zrb_nudge/schedule.py The file: schedules, windows, the ledger of what has been said, and which moment is due. No zrb, no clock of its own.
zrb_nudge/zrb_init.py The zrb side, loaded through ZRB_INIT_SCRIPTS: AddSchedule, RemoveSchedule, and the trigger that reads the file.
zrb_nudge/__main__.py The zrb-nudge command.
test_nudge.py The checklist above, as assertions.

Metadata

Release files for zrb-nudge 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for zrb-nudge 0.1.1
File Size Uploaded Provenance Actions
zrb_nudge-0.1.1.tar.gz 28.9 kB Without provenance Details for zrb_nudge-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for zrb-nudge 0.1.1
File Interpreter ABI Platform Actions
zrb_nudge-0.1.1-py3-none-any.whl Python 3 none any Details for zrb_nudge-0.1.1-py3-none-any.whl

Total release size: 54.3 kB

Release files / zrb_nudge-0.1.1.tar.gz

Download URL zrb_nudge-0.1.1.tar.gz
Size 28.9 kB
Tags Source
SHA-256 checksum
How to use checksums
83c6bdb3249860dc9df5dd03b4e9babc6b43396c66fb8e2a1b5fdb146824711a
BLAKE2b-256 checksum
How to use checksums
582a7d5bc0db2c0b30d517d9e3a449c88e8070fa626873675a8d33bd6d4571eb
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.2

Release files / zrb_nudge-0.1.1-py3-none-any.whl

Download URL zrb_nudge-0.1.1-py3-none-any.whl
Size 25.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
47eb319e8ccba9ed07d42c076bf87f5df206bf0fdb6e612911f2e3fa569ed48c
BLAKE2b-256 checksum
How to use checksums
0a452c67a9ba24b44bfcb8feefcf34bcc8426ee54330370c78a978693d298228
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.2

Security for zrb-nudge 0.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page