Session nudge
One helper does everything; run it with the Python 3.9+ on PATH:
python3 <this skill's directory>/scripts/nudge.py <action> [options]
Map the request to an action
| User says |
Run |
on, enable, "turn nudges on here" |
on |
off, disable, "stop nudging this session" |
off |
nothing, status, "is the nudge on?" |
status |
| a pace: "nudge every 20 minutes", "每半小时", "hourly", "every 1.5h" |
on --every N |
| first nudge at a future time, then on the cadence from it ("resume at 7:30am and nudge every 305 minutes"; 7:30 is the "0th" nudge) |
on --every N --anchor-at 07:30 |
| "nudge once at 2:01 AM local time" |
once --at 02:01 |
| a different terminal (e.g. a Codex or Grok Build window) |
add --pid N |
| "test the nudge", or first use on a machine |
test |
| change the default pace for new opt-ins |
install --interval N |
| remove the background job |
uninstall |
A pace turns the nudge on (or changes the pace of an already-enabled session).
Convert it to whole minutes yourself: "half an hour" -> 30, "every 2 hours"
-> 120, "1.5h" -> 90; anything under one minute becomes 1. With no pace,
on keeps the session's existing pace, else the default (61). The pace is per
session: other sessions keep theirs.
on --anchor-at HH:MM backdates the pace's last-nudge stamp so the first
delivery fires exactly at the anchor minute and later deliveries keep the
every-N cadence measured from it ("first nudge at 7:30, then every 305
minutes" fires at 7:30, 12:35, ...). The anchor delivery is the booked
first nudge, so do not also run once --at HH:MM: once replaces the whole
opt-in with a one-shot (it drops every/last), and an entry holding
once_at fires only once and is then removed. Conversely, any enable/on
clears a pending one-time nudge, so when a one-shot is what is wanted, run
on first and once --at last. If the anchor time has already passed, the
pace is simply due at the next tick and continues from there.
once --at HH:MM schedules the next local occurrence at HH:MM:00, or tomorrow if today's time has passed. The scheduler ticks on whole minutes so requests without explicit seconds do not drift to a later second. It delivers once and removes the entry. off also cancels a scheduled one-time nudge.
Report the helper's one-line result. Do not edit the scheduler job, the state
files or the templates by hand; the helper is the interface.
First run on a machine: ask, then test
status, on, once, install and test first make sure the background job
exists and matches this skill's location, creating it from templates/ for
the current OS if not (off never installs anything). Until an end-to-end
test has passed on this machine, their output also contains setup
questions:
ASK-USER [Header]: question
- Option label: what to do if chosen
For each one, ask the user with your question tool (AskUserQuestion in Claude
Code: the bracketed word as header, the listed options as options; in agents without
one, ask in plain text). Do what the chosen option says. Then run test, and if it
fails, handle the ASK-USER lines it prints the same way and run test again
until it passes or the user stops. The on that printed the questions has
already taken effect, so there is no need to repeat it after the test; tell
the user the session's state plus one sentence on the test result. No
ASK-USER lines means this machine is already set up: skip test. Typical
questions:
- macOS: allow python3 to control iTerm2 (Automation permission; the first
test triggers the system prompt).
- Linux: enable systemd lingering so the timer runs while logged out; start a
cron daemon if only the cron fallback is available.
- Windows: register the task with highest privileges when agents run in an
elevated terminal.
- Any OS: this terminal cannot be typed into -> run agent sessions in tmux,
WezTerm (or iTerm2 on macOS). Before installing anything, check whether the
terminal is already present (
command -v tmux); it often is, and then the
right move is just test.
test opens a throwaway terminal (tmux, WezTerm, iTerm2 window or Windows
console), has the real scheduler job fire at it, and checks the message
arrived and was submitted. test --pid N targets an existing agent terminal
instead (the nudge text really lands in that session).
A PASS proves the scheduler-to-terminal pipeline only: the throwaway window
is the test's own, so it says nothing about the session that was just
enabled. If that session sits on a plain pts (the common case for a Claude
Code run outside tmux), its nudges fire each interval but are delivered as
skipped until the agent is restarted inside a supported terminal (tmux new -s <name>, then start the agent there). Say this explicitly when
reporting, so PASS is not read as "this session will be nudged".
Restarts and resumed sessions
Two cases to check before trusting a delivery:
- Every restart kills the opt-in. Opt-ins are keyed by the TUI process,
so a restart of Claude Code —
--resume, --fork-session, a crash —
starts a new PID with no opt-in, and status reports disabled even though
the user set a pace earlier. Run on again in each new session the user
wants nudged; do not assume an earlier setup carries over.
- Resumed/forked sessions are daemon-hosted; they need a screen viewer.
A session resumed with
--resume --fork-session runs under a claude bg-pty-host parent with a daemon-created pty: no multiplexer pane hosts
the TUI itself ($TMUX unset, tmux list-panes finds no server). The
user watches it through a viewer client, and if that viewer runs inside a
GNU screen window, the screen channel delivers into the viewer and the
keystrokes relay to the session — the viewer is matched by the cc-daemon
pty socket it holds, whose path names the session, never by cwd alone
(several sessions share a cwd). Without such a screen window every
delivery is skipped. Diagnose with ps -o ppid= -p <claude pid> (the
parent names claude bg-pty-host); tell the user this when they report
that a pace they set earlier "isn't working".
How it works
- Scheduler: launchd agent
local.session-nudge (macOS), systemd user timer
session-nudge.timer or a crontab line when there is no systemd user
session (Linux), Task Scheduler task session-nudge (Windows). It runs
nudge.py fire every minute; each tick nudges only sessions whose own
interval has elapsed.
- Opt-ins live in the state directory (
~/.local/state/session-nudge/, or
%LOCALAPPDATA%\session-nudge\ on Windows; $SESSION_NUDGE_HOME
overrides), file include: one line per agent TUI PID with its pace and
last nudge time. Keyed by PID, so an opt-in ends with its process and never
sticks to a terminal a later session reuses. nudge.log there records every
delivery and skip; config.json holds the default pace and the message
({now} and {next} are filled in).
- Cleanup is lazy, by design; there is no session-exit hook. A dead session's
entry is dropped by the rewrite at its first due tick after the process
ends -- at most one interval later, costing one "gone -- skipped" log line.
An exit hook would be the weaker mechanism anyway: it does not run on
crashes, kills or closed windows, so the liveness filter would still be
required as the backstop; end-of-conversation events do not line up with
end-of-opt-ins (a cleared conversation or a terminal hosting several
sessions must keep its opt-in, because the opt-in follows the TUI process,
not the conversation); and not every supported agent has such a hook, so
liveness at delivery time is both the correctness check and the cleanup.
- Delivery: tmux
send-keys, GNU screen stuff, WezTerm cli send-text,
iTerm2 AppleScript (macOS), console input injection (Windows). Text first,
then CR after 0.5s
and again after 1s: Claude Code treats a CR in the same burst as pasted
text, and the second CR is a no-op on an empty composer. Other terminals
(Terminal.app, GNOME Terminal, VS Code's terminal without tmux) cannot be
typed into and are logged as skipped. A session sitting at a permission
prompt consumes the text there.
Finding this session's terminal
- Claude Code:
CLAUDE_PID is the TUI. Codex or anything else: the nearest
ancestor process named claude, codex or grok that has a terminal.
- A Claude Code background session (
kind: bg in
~/.claude/sessions/<pid>.json) is shown through an attached TUI that the
session files do not name; the helper takes the single interactive TUI in
the same working directory. With several it lists them and changes nothing
-- ask the user which window shows this session and rerun with --pid N.
- Find a PID by hand with
ps axww -o pid=,tty=,command= | grep -E 'claude|codex|grok'
(Windows: Get-Process claude,codex,grok,node). Headless processes (claude -p,
codex exec, the codex app-server) have no terminal and are never nudged.
- The opt-in follows the TUI process, not the conversation: if that window is
switched to another session, that session is nudged too.
1---2name: session-nudge3description: >-4 Turn a periodic or one-time keepalive nudge on or off for the current coding-agent session (Claude Code,5 Codex CLI or Grok Build), set its pace, or show whether it is on. The nudge is a "[HH:MM:SS] Automated nudge:6 continue working ..." message that a background OS job (launchd / systemd timer / cron / Windows7 Task Scheduler) types into opted-in agent terminals, every 61 minutes by default. Use for8 "/session-nudge on|off|enable|disable|status", "nudge every 20 minutes", "nudge once at 2:01 AM", "turn the nudge off9 here", "别给这个 session 发 nudge", "每半小时 nudge 一次", "给那个 codex 窗口开 nudge", "nudge my grok window too", and when setting the nudge10 up or testing it on a new machine. Sessions are off by default.11metadata:12 source: https://skillmd.com/skills/zydo/session-nudge13---1415# Session nudge1617One helper does everything; run it with the Python 3.9+ on PATH:1819```sh20python3 <this skill's directory>/scripts/nudge.py <action> [options]21```2223## Map the request to an action2425| User says | Run |26|---|---|27| `on`, `enable`, "turn nudges on here" | `on` |28| `off`, `disable`, "stop nudging this session" | `off` |29| nothing, `status`, "is the nudge on?" | `status` |30| a pace: "nudge every 20 minutes", "每半小时", "hourly", "every 1.5h" | `on --every N` |31| first nudge at a future time, then on the cadence from it ("resume at 7:30am and nudge every 305 minutes"; 7:30 is the "0th" nudge) | `on --every N --anchor-at 07:30` |32| "nudge once at 2:01 AM local time" | `once --at 02:01` |33| a different terminal (e.g. a Codex or Grok Build window) | add `--pid N` |34| "test the nudge", or first use on a machine | `test` |35| change the default pace for new opt-ins | `install --interval N` |36| remove the background job | `uninstall` |3738A pace turns the nudge on (or changes the pace of an already-enabled session).39Convert it to whole minutes yourself: "half an hour" -> 30, "every 2 hours"40-> 120, "1.5h" -> 90; anything under one minute becomes 1. With no pace,41`on` keeps the session's existing pace, else the default (61). The pace is per42session: other sessions keep theirs.4344`on --anchor-at HH:MM` backdates the pace's last-nudge stamp so the first45delivery fires exactly at the anchor minute and later deliveries keep the46every-N cadence measured from it ("first nudge at 7:30, then every 30547minutes" fires at 7:30, 12:35, ...). The anchor delivery *is* the booked48first nudge, so do not also run `once --at HH:MM`: `once` replaces the whole49opt-in with a one-shot (it drops `every`/`last`), and an entry holding50`once_at` fires only once and is then removed. Conversely, any `enable`/`on`51clears a pending one-time nudge, so when a one-shot is what is wanted, run52`on` first and `once --at` last. If the anchor time has already passed, the53pace is simply due at the next tick and continues from there.5455`once --at HH:MM` schedules the next local occurrence at `HH:MM:00`, or tomorrow if today's time has passed. The scheduler ticks on whole minutes so requests without explicit seconds do not drift to a later second. It delivers once and removes the entry. `off` also cancels a scheduled one-time nudge.5657Report the helper's one-line result. Do not edit the scheduler job, the state58files or the templates by hand; the helper is the interface.5960## First run on a machine: ask, then test6162`status`, `on`, `once`, `install` and `test` first make sure the background job63exists and matches this skill's location, creating it from `templates/` for64the current OS if not (`off` never installs anything). Until an end-to-end65`test` has passed on this machine, their output also contains setup66questions:6768```69ASK-USER [Header]: question70 - Option label: what to do if chosen71```7273For each one, ask the user with your question tool (AskUserQuestion in Claude74Code: the bracketed word as header, the listed options as options; in agents without75one, ask in plain text). Do what the chosen option says. Then run `test`, and if it76fails, handle the `ASK-USER` lines it prints the same way and run `test` again77until it passes or the user stops. The `on` that printed the questions has78already taken effect, so there is no need to repeat it after the test; tell79the user the session's state plus one sentence on the test result. No80`ASK-USER` lines means this machine is already set up: skip `test`. Typical81questions:8283- macOS: allow python3 to control iTerm2 (Automation permission; the first84 test triggers the system prompt).85- Linux: enable systemd lingering so the timer runs while logged out; start a86 cron daemon if only the cron fallback is available.87- Windows: register the task with highest privileges when agents run in an88 elevated terminal.89- Any OS: this terminal cannot be typed into -> run agent sessions in tmux,90 WezTerm (or iTerm2 on macOS). Before installing anything, check whether the91 terminal is already present (`command -v tmux`); it often is, and then the92 right move is just `test`.9394`test` opens a throwaway terminal (tmux, WezTerm, iTerm2 window or Windows95console), has the real scheduler job fire at it, and checks the message96arrived and was submitted. `test --pid N` targets an existing agent terminal97instead (the nudge text really lands in that session).9899A PASS proves the scheduler-to-terminal pipeline only: the throwaway window100is the test's own, so it says nothing about the session that was just101enabled. If that session sits on a plain pts (the common case for a Claude102Code run outside tmux), its nudges fire each interval but are delivered as103skipped until the agent is restarted inside a supported terminal (`tmux104new -s <name>`, then start the agent there). Say this explicitly when105reporting, so PASS is not read as "this session will be nudged".106107## Restarts and resumed sessions108109Two cases to check before trusting a delivery:110111- **Every restart kills the opt-in.** Opt-ins are keyed by the TUI process,112 so a restart of Claude Code — `--resume`, `--fork-session`, a crash —113 starts a new PID with no opt-in, and `status` reports disabled even though114 the user set a pace earlier. Run `on` again in each new session the user115 wants nudged; do not assume an earlier setup carries over.116- **Resumed/forked sessions are daemon-hosted; they need a screen viewer.**117 A session resumed with `--resume --fork-session` runs under a `claude118 bg-pty-host` parent with a daemon-created pty: no multiplexer pane hosts119 the TUI itself (`$TMUX` unset, `tmux list-panes` finds no server). The120 user watches it through a viewer client, and if that viewer runs inside a121 GNU screen window, the screen channel delivers into the viewer and the122 keystrokes relay to the session — the viewer is matched by the cc-daemon123 pty socket it holds, whose path names the session, never by cwd alone124 (several sessions share a cwd). Without such a screen window every125 delivery is skipped. Diagnose with `ps -o ppid= -p <claude pid>` (the126 parent names `claude bg-pty-host`); tell the user this when they report127 that a pace they set earlier "isn't working".128129## How it works130131- Scheduler: launchd agent `local.session-nudge` (macOS), systemd user timer132 `session-nudge.timer` or a crontab line when there is no systemd user133 session (Linux), Task Scheduler task `session-nudge` (Windows). It runs134 `nudge.py fire` every minute; each tick nudges only sessions whose own135 interval has elapsed.136- Opt-ins live in the state directory (`~/.local/state/session-nudge/`, or137 `%LOCALAPPDATA%\session-nudge\` on Windows; `$SESSION_NUDGE_HOME`138 overrides), file `include`: one line per agent TUI PID with its pace and139 last nudge time. Keyed by PID, so an opt-in ends with its process and never140 sticks to a terminal a later session reuses. `nudge.log` there records every141 delivery and skip; `config.json` holds the default pace and the message142 (`{now}` and `{next}` are filled in).143- Cleanup is lazy, by design; there is no session-exit hook. A dead session's144 entry is dropped by the rewrite at its first due tick after the process145 ends -- at most one interval later, costing one "gone -- skipped" log line.146 An exit hook would be the weaker mechanism anyway: it does not run on147 crashes, kills or closed windows, so the liveness filter would still be148 required as the backstop; end-of-conversation events do not line up with149 end-of-opt-ins (a cleared conversation or a terminal hosting several150 sessions must keep its opt-in, because the opt-in follows the TUI process,151 not the conversation); and not every supported agent has such a hook, so152 liveness at delivery time is both the correctness check and the cleanup.153- Delivery: tmux `send-keys`, GNU screen `stuff`, WezTerm `cli send-text`,154 iTerm2 AppleScript (macOS), console input injection (Windows). Text first,155 then CR after 0.5s156 and again after 1s: Claude Code treats a CR in the same burst as pasted157 text, and the second CR is a no-op on an empty composer. Other terminals158 (Terminal.app, GNOME Terminal, VS Code's terminal without tmux) cannot be159 typed into and are logged as skipped. A session sitting at a permission160 prompt consumes the text there.161162## Finding this session's terminal163164- Claude Code: `CLAUDE_PID` is the TUI. Codex or anything else: the nearest165 ancestor process named `claude`, `codex` or `grok` that has a terminal.166- A Claude Code background session (`kind: bg` in167 `~/.claude/sessions/<pid>.json`) is shown through an attached TUI that the168 session files do not name; the helper takes the single interactive TUI in169 the same working directory. With several it lists them and changes nothing170 -- ask the user which window shows this session and rerun with `--pid N`.171- Find a PID by hand with `ps axww -o pid=,tty=,command= | grep -E 'claude|codex|grok'`172 (Windows: `Get-Process claude,codex,grok,node`). Headless processes (`claude -p`,173 `codex exec`, the codex app-server) have no terminal and are never nudged.174- The opt-in follows the TUI process, not the conversation: if that window is175 switched to another session, that session is nudged too.