mattsebastianh

Claude Session Ping

Productivity community

SOURCE https://github.com/mattsebastianh/claude-session-ping

Description

macOS launchd agent that keeps Claude Code's 5-hour session window open on a fixed daily schedule — reads the real window from /usage, detects when a ping was absorbed, self-schedules a backup ping to close the gap, and optionally reports to Telegram with a schedule Q&A bot

Installation

This entry records only its repository, not the path inside it, so there is no exact command to give. Open the source below and copy the folder into ~/.claude/skills/, or the file into ~/.claude/agents/.

README

claude-session-ping

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) [![Platform: macOS](https://img.shields.io/badge/platform-macOS-lightgrey.svg)](https://www.apple.com/macos/) [![Shell: zsh](https://img.shields.io/badge/shell-zsh-89e051.svg)](scripts/claude_session_ping.sh)

A macOS `launchd` agent that pings Claude Code on a fixed daily schedule to activate/keep alive the 5-hour session usage window — no LLM required to decide *when* to fire, only plain system scheduling and shell code.

How it works

**`launchd/com.claude-session-ping.plist`** — a launch agent template. macOS's own scheduler (`StartCalendarInterval`) fires it daily at:
- 07:02
- 12:02
- 17:02
- 22:02
launchd runs jobs with a minimal environment (bare `PATH`, no `USER`/ `LOGNAME`), which isn't enough to find the `claude` CLI or for it to look up your login/auth. The template sets `PATH` (including `~/.local/bin`, where `claude` is commonly installed) and `USER`/ `LOGNAME` explicitly via `EnvironmentVariables`, templated with `{{HOME_DIR}}`/`{{USER}}` placeholders that `install.sh` fills in.
**`scripts/claude_session_ping.sh`** — the script launchd runs. It:
1. Checks the current time is at one of the four targets above, or up to 65 minutes after one (CLAUDE_SESSION_PING_GRACE_MINUTES) — see Sleep below.
2. Sends a keepalive ping (defaults to claude -p "...").
3. If it detects a usage-limit/blocked response, retries up to 4 times, waiting 5 minutes between attempts (5 attempts total per window).
4. Logs everything to logs/claude-session-ping.log in the project directory (override with CLAUDE_SESSION_PING_LOG).
5. Asks Claude for the real usage window via claude -p "/usage" and reports the true start/end in notifications. That question fires the moment the ping returns, so it can arrive before the just-opened window has registered; if the answer is "no session",