rhythm

Health & momentum tracker for Claude Code. Zero-config. Reads your existing prompt history, then shows pace, sleep patterns, streaks, and break classification at every session start.

🕐 Last session: 2h 15m (47p) in my-saas-app — ended 3m ago
   ▓▓▓▓▓▓▓░░░ 7h 12m today · 9h 27m/d weekly · ✓ on pace
   🔥 14-day streak · 🎯 focused on my-saas-app

Overdoing it? You'll know:

   ██████████ 13h 22m today · 9h 27m/d weekly · ⚠ overdoing
   🌀 last night 02:47 · 🟠 5/7 nights past midnight — take a break

Come back from holiday? AI knows:

┌─ ⏰ VIRTUAL WAKE-UP ─────────────────────────────────
│ Welcome back from holiday!
│ Holiday break: 10 days 6h offline (Sat 05 Apr → Tue 15 Apr Bangkok)
│ ░░░░░░░░░░ 0m today · 8h 40m/d weekly · 💤 resting
│ 🆘 broken streak (was 14 days)
└────────────────────────────────────────────────────

Quick Install (1 command)

git clone https://github.com/boatnoy/rhythm-claude.git ~/tools/rhythm && ~/tools/rhythm/install.sh

That's it. Next Claude Code session starts showing rhythm signals.

What it measures

Three axes from ~/.claude/history.jsonl (already on your machine):

| Axis | What | Signals | |---|---|---| | PACE | Today vs your 7-day avg | 💤 resting · 🌱 warming up · ✓ on pace · ⚡ strong · ⚠ overdoing · ☢ burnout risk | | HEALTH | Sleep time, late-night patterns | 🌙 early night · 🌑 past midnight · 🌀 graveyard · 🟡 sleep debt · 🔴 chronic | | MOMENTUM | Streaks, focus, breaks | 🏁 fresh start · 💪 consistent · 🏆 marathon · 🎯 focused · 🧩 scattered |

Full signal library: docs/SIGNALS.md

Architecture

~/.claude/settings.json          (hooks config — points to scripts)
     │
     ├─ SessionStart ──→ hooks.py start ──→ banner (3 lines)
     ├─ UserPromptSubmit → hooks.py prompt → virtual wake-up check
     └─ Stop ───────────→ hooks.py stop
                              │
                   ┌──────────┴──────────┐
                   │                     │
              timelog.jsonl          signals.py
           (append-only log)    (pace/health/momentum)
                                      │
                                history.jsonl
                             (Claude Code built-in)

Data flow: Hooks fire on every Claude Code event → append to timelog.jsonl → on SessionStart (or virtual wake-up), signals.py reads history.jsonl to compute 3-axis signals → formatted as 2-3 lines → shown to user + given to AI as context.

Files

scripts/
  hooks.py      Event handler. SessionStart banner + virtual wake-up detection.
  signals.py    Pure signal computation. PACE/HEALTH/MOMENTUM axes.
  hours.py      /hours CLI. Workday breakdown, blocks, Pandan cross-validation.
docs/
  DESIGN.md     Philosophy, definitions, display rules, roadmap.
  SIGNALS.md    Every emoji, threshold, and when it triggers.
SKILL.md        Claude Code skill definition for /hours command.
install.sh      One-command install + auto-configure hooks.
uninstall.sh    Clean removal.

Data files (created at runtime, not in repo)

~/.claude/skills/hours/
  timelog.jsonl   Hook events (session_start, prompt, stop, resume_session)
  cache/          Cached computation results for /hours CLI

Customization

Edit scripts/signals.py to tune for your rhythm:

| Setting | Default | Where | Why | |---|---|---|---| | TZ | UTC+7 (Bangkok) | signals.py:8 | Your timezone. Affects workday boundary. | | WORKDAY_CUTOFF_HOUR | 4 (04:00) | signals.py:9 | When "today" starts. If you finish at 2am, it's still today. | | BREAK_MS | 3600000 (60 min) | signals.py:10 | Gaps longer than this = not active time. | | Pace thresholds | 40/70/85/115/140/170/220% | _pace_signal() | Tune after 2 weeks of real data. | | Wake-up threshold | 4 hours | hooks.py:31 | Gap before triggering virtual wake-up. |

macOS users: If wasp clean or similar needs high file descriptors, add ulimit -n 10240 to ~/.zshrc.

For Other Machines (YOGI, SHIBA, etc.)

# On the new machine:
git clone https://github.com/boatnoy/rhythm-claude.git ~/tools/rhythm
cd ~/tools/rhythm
./install.sh

# Verify:
echo '{}' | python3 ~/.claude/skills/hours/scripts/hooks.py start
# Should output JSON with systemMessage

The install script:

1. Copies scripts to ~/.claude/skills/hours/
2. Auto-patches ~/.claude/settings.json with the 3 hooks (backs up first)
3. No dependencies — pure Python 3.8+ (ships with macOS)

History builds up from the first session. Signals need ~3 days of data to be meaningful (7-day avg needs 7 days).

npm (future)

# Coming soon:
npx rhythm-claude install

Tracked in the roadmap. The package will wrap install.sh + add rhythm update for pulling new versions.

Commands

/hours                  # today's workday breakdown
/hours --week           # last 7 workdays table
/hours --month          # last 30 workdays
/hours --all            # since day 1 summary
/hours --pandan         # cross-validate with Pandan app (macOS)
/hours --day 2026-04-15 # specific day
/hours --project my-app  # filter by project
/hours --export         # JSON dump

Why

Built to answer: "Am I overworking, or am I slacking — honestly?"

No self-report. No timer app. No manual tracking. Just the data that's already there — every prompt you type is timestamped in history.jsonl. Rhythm turns that into self-awareness.

Self-relative, not absolute. Your baseline is your 7-day rhythm, not a global average. Warn both ways — below 40% is also information.

MIT License.