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 theface —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
saidbefore 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.