Metadata-Version: 2.5
Name: zrb-nudge
Version: 0.1.0
Summary: Scheduled nudges for zrb: a file of reminders, two tools to write it, and a trigger that reads it
Project-URL: Homepage, https://github.com/state-alchemists/zrb-nudge
License-Expression: AGPL-3.0-or-later
License-File: LICENSE
Requires-Python: >=3.10
Provides-Extra: zrb
Requires-Dist: zrb; extra == 'zrb'
Description-Content-Type: text/markdown

# zrb-nudge

Scheduled reminders for [zrb](https://github.com/state-alchemists/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

```sh
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:

```sh
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:

```sh
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:

```json
{
  "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](https://github.com/state-alchemists/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

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