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 |
Say this to the user in your own words, briefly. |
zrb_init.py |
What the turn asks for, after the reminder itself. 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.
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, and may say something short or nothing worth saying.
- 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.
What it does not know
It knows the clock and the file. It cannot see whether anyone is at the desk, whether
the camera saw you leave, or whether the last turn failed — those belong to
zrb-avatar, whose own nudge keeps
that half (ZRB_AVATAR_NUDGE*). With both loaded, each speaks for what it knows.
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.0
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.0.tar.gz | 28.2 kB | Without provenance | Details for zrb_nudge-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| zrb_nudge-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for zrb_nudge-0.1.0-py3-none-any.whl |
Total release size: 53.2 kB
Release files / zrb_nudge-0.1.0.tar.gz
| Download URL | zrb_nudge-0.1.0.tar.gz |
|---|---|
| Size | 28.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b6c0ff2377f0cbc232b095e55067ad26c417b5cb814624bf958f8adf628c884b
|
|
BLAKE2b-256 checksum How to use checksums |
84611cb43423859a2385540b467fd9dd319b0449d4e18af26d1d316243918f4a
|
| 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.0-py3-none-any.whl
| Download URL | zrb_nudge-0.1.0-py3-none-any.whl |
|---|---|
| Size | 24.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ac68efcda7d4db3dec3fe7e90212f8a8b0388b153752d1c3da0717c9edbeb9c3
|
|
BLAKE2b-256 checksum How to use checksums |
5f6be9efa5858091631426826c4b7ea2d42d4b0a588c750eb41801a16ab84561
|
| 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.0
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.