pi-idle-notify

Desktop notification when a Pi TUI session has gone quiet. One toast after idle. Not "task complete". Does not use agent_settled.

Install:

pi install npm:pi-idle-notify

Then /reload (or restart Pi).

What it does

Each TUI window keeps a nested busy count (agent, compact, tool execution, ! bash). When that count drops to zero, a countdown starts (default 120 seconds). If Pi stays quiet, you get one OS notification:

• Title: Pi
• Body: idle — <last N folders of cwd> (default N = 3)

A second toast is not sent until Pi becomes busy again. Two Pi windows are independent. Waiting for you to pick something in a prompt is not busy. Typing, window focus, and slash commands that do not start the agent do not cancel the countdown.

json / print / rpc sessions do not notify. Notification failures are silent and do not break Pi. User ! commands count as busy by wrapping Pi's local bash runner.

Settings

Only ~/.pi/agent/settings.json (not project .pi/settings.json):

{
  "idleNotify": {
    "enabled": true,
    "idleSeconds": 120,
    "pathLevels": 3,
    "reminder": false
  }
}

idleSeconds is an integer from 10 to 600. pathLevels is how many trailing folders to show (1–8, default 3). Fewer folders than that: show all of them.

reminder defaults to false: a normal toast that the OS may auto-dismiss. Set it to true for a Windows reminder toast that stays until you click Dismiss. macOS and Linux keep the normal toast even if this is on. Windows may show the reminder under PowerShell (it needs a registered app id).

Command

/idle-notify

Args	Effect
(none)	Status plus usage
on / off	Toggle. off cancels a pending countdown
seconds <n>	Set idle seconds. If a countdown is running, it restarts from now
levels <n>	How many trailing cwd folders to show in the toast (1–8)
reminder on / reminder off	Windows sticky toast. Default is off (auto-dismiss). No argument prints the current value
status	enabled, seconds, path levels, reminder, busy / countdown / notified
test	Fire the same desktop notification immediately, even if off

Requirements

Windows, macOS, or Linux with a desktop session. Headless SSH / WSL without a GUI will not toast.

License

MIT