Forked from kyl-coding/claude-session-saver, reworked into a scheduling-focused tool.
Open your Claude Code token windows on your schedule, not by accident.
Claude Code allocates tokens in rolling 5-hour windows, and a new window only starts counting from your last usage. Leave Claude alone overnight and the clock isn't ticking — so you sit down at 9am to a window that hasn't opened yet, and the day's first five hours are spent waiting rather than working.
claude-ping fires a tiny Haiku ping at times you choose, so the windows are already turning over by the time you get there.
The useful move isn't "ping constantly" — it's placing the first ping early enough that your workday starts mid-window.
A ping at 6:00am opens a window that runs until 11:00. Start work at 9:00 and you have a couple of hours of that window left, and a fresh one arrives at 11:05 — right about when you'd have burned through it anyway. The day is already in rhythm before you sit down.
Default schedule Window state at 9:00am
────────────────── ──────────────────────
06:00 ✓ ping open since 06:00, ~2h left
11:05 ✓ ping fresh window
16:10 ✓ ping fresh window
21:15 ✓ ping fresh window
quiet overnight
The 5-minute stagger is deliberate. Windows are 5 hours long, so a 5h05m step keeps each ping just clear of the previous window's exact expiry boundary rather than racing it. The offset accumulates naturally across the day.
A launchd agent runs this at each scheduled time:
claude --print --model haiku -p "hi"
Haiku is the fastest and cheapest Claude model — each ping finishes in under 3 seconds and costs a negligible slice of your existing subscription. The bare haiku alias always resolves to the current version.
It's a launchd agent, so it runs whenever you're logged in with nothing open. That's the whole point: the pings that matter are the ones firing while you're away from the machine.
- macOS
- Claude Code installed and authenticated (Pro, Max, Max 5x, or Max 20x)
git clone https://github.com/steveylang/claude-ping.git
cd claude-ping
./install.shThe installer verifies claude is reachable, writes a config, installs the scripts to ~/.local/bin/, generates the launchd plist from your schedule, loads the agent, and fires one test ping to prove it works.
Add ~/.local/bin to your PATH if it isn't already:
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrcUpgrading from
claude-session-saver? Just run./install.sh. It unloads the old agent, removes its files, and carries your config across. Necessary because the launchd label changed — without it the old agent keeps running and you'd get two pings per slot.
Defaults to 06:00, 11:05, 16:10, 21:15, then quiet overnight. Edit ~/.config/claude-ping/config:
START="06:00" # first ping of the day
STEP="5h05m" # spacing — accepts "5h05m", "5h", or "305m"
CUTOFF="21:30" # latest permitted ping
MODEL="haiku" # model used for the pingImportant
CUTOFF is a ceiling on the last ping, not "stop generating at."
A slot landing at or before CUTOFF fires; the first slot past it ends the day.
With the defaults the last slot is 21:15, admitted because CUTOFF is 21:30 —
setting CUTOFF="21:00" would silently drop that fourth ping and leave a
14-hour overnight gap.
Want an earlier start? Change START and the rest cascades:
START |
Derived schedule |
|---|---|
05:00 |
05:00, 10:05, 15:10, 20:15 |
06:00 |
06:00, 11:05, 16:10, 21:15 |
07:00 |
07:00, 12:05, 17:10 (21:15 slot would be 22:15 — past cutoff) |
Or skip the derivation entirely:
TIMES="06:00 09:00 14:00 19:00" # overrides START/STEP/CUTOFFPreview before committing, then apply:
claude-ping schedule # print the derived times
./install.sh # regenerate the launchd plistSchedule changes require re-running ./install.sh — the times are baked into the plist.
claude-ping status # agent state, schedule, next ping, last result
claude-ping schedule # preview derived times from the current config
claude-ping ping # ping right now
claude-ping logs # follow the log
claude-ping pause # unload the agent, keeping everything in place
claude-ping resume # load it back up
claude-ping edit # edit the config in $EDITOR
claude-ping wake # manage optional auto-wake (see below)$ claude-ping status
claude-ping
Agent loaded
Config /Users/you/.config/claude-ping/config
Model haiku
Schedule 06:00 11:05 16:10 21:15
Next ping 11:05 today
Auto-wake not enabled
Last ping [2026-07-21 06:00:03] Keep-alive ping succeeded.
If your Mac is asleep at 06:00, launchd defers the ping until you wake it — the window opens, just later than you wanted. Auto-wake schedules a system wake shortly before your first ping so it lands on time:
claude-ping wake status # show current state
claude-ping wake enable # schedule the wake (asks for sudo)
claude-ping wake disable # cancel itOpt-in and off by default. It's the only part of claude-ping that needs sudo — never enable it and you're never asked for a password.
Two things worth knowing first:
- macOS allows exactly one repeating power schedule, system-wide. Enabling auto-wake replaces any existing one.
wake enableshows you what's currently scheduled and asks before overwriting, and records the displaced entry at~/.config/claude-ping/pmset.bak— butwake disablecancels outright rather than restoring it. - Apple silicon laptops on battery with the lid closed may not wake reliably. On a desktop or a plugged-in laptop it's dependable.
Auto-wake is scheduled from START at the moment you run it. Change START later and the two drift apart — wake status detects this and tells you to re-run wake enable.
claude-ping logs
# or directly:
tail -f ~/Library/Logs/claude-ping/stdout.log./uninstall.shStops the agent, removes the plist and scripts, offers to cancel auto-wake if you enabled it, and prompts separately before deleting your config and logs — so a reinstall picks your settings back up.
claude-ping/
├── claude-ping # status & management CLI
├── claude-ping-agent.sh # the ping itself (called by launchd)
├── lib.sh # shared: config, schedule derivation, launchd, migration
├── config.example # documented defaults
├── install.sh # macOS installer
├── uninstall.sh # removal
├── LICENSE
└── README.md
Does this cost extra? No. It uses your existing subscription, and a single "hi" on Haiku is a rounding error against a 5-hour window's allocation.
Do I need a terminal or Claude Code open? No. It's a launchd agent — it runs whenever you're logged in, with nothing open.
Will it work after my Mac sleeps?
Yes. launchd runs a missed calendar job when the Mac wakes, so the ping happens late rather than not at all. Enable auto-wake if you want it exactly on time.
Does it interfere with active Claude Code sessions? No. The ping is a separate background process.
Why 5h05m instead of 5h? A 5-hour step races the window boundary — a ping landing microseconds early falls inside the expiring window instead of opening a new one. The extra 5 minutes removes the ambiguity.
How do I know it's working?
claude-ping statusMIT