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 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 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.

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)

Source distribution for zrb-nudge 0.1.0
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)

Table of built distributions (wheels) for zrb-nudge 0.1.0
File Interpreter ABI Platform Actions
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.

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