claude-powernap 0.3.0__tar.gz

claude_powernap-0.3.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+.DS_Store
+dist/
+build/
+*.egg-info/
+.venv/

claude_powernap-0.3.0/CHANGELOG.md

@@ -0,0 +1,96 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
+versioning: [SemVer](https://semver.org/).
+
+## [0.3.0] - 2026-07-18
+
+### Added
+- **PyPI packaging**: installable via `pip install claude-powernap` /
+  `uvx claude-powernap setup`; new `setup` / `remove` CLI subcommands replace
+  the platform installer scripts (install.sh/.ps1 remain as thin wrappers).
+- **Claude Code plugin**: the repo is its own marketplace —
+  `/plugin marketplace add asiagenawi/claude-powernap` then
+  `/plugin install powernap@claude-powernap`. Hooks activate with no file
+  deployment; `/powernap:watcher` schedules the OS-level fallback watcher;
+  `/powernap:status` and `/powernap:toggle` included
+  (`watcher-setup`/`watcher-remove` CLI subcommands back them).
+- `claude-powernap version` command.
+- CI: package build + wheel install + entry-point smoke test job; PyPI
+  publish workflow on GitHub releases (trusted publishing).
+
+### Changed
+- Repo restructured to a src-layout Python package (`src/claude_powernap/`);
+  install logic consolidated into one cross-platform code path.
+
+### Fixed (pre-release audit)
+- Rescue paths now share one ledger — a warned session that then hard-hit
+  the limit can no longer be resumed twice (forked).
+- macOS liveness check fails toward "alive" on lsof errors, matching Windows.
+- Warnings are no longer emitted (and marked delivered) on Stop events,
+  where injected context reaches no model turn.
+- Local estimation dedupes by request/message id — `claude --resume` copies
+  history into a new transcript and previously double-counted it.
+- Keychain: full-keychain enumeration (`dump-keychain`) now runs only on a
+  cache miss, never on the steady-state path; check cadence has a 15s floor.
+- Usage requests self-identify as `claude-powernap/<version>` (verified
+  accepted) instead of a claude-cli User-Agent.
+- uvx installs embed a stable system interpreter (not uv's collectible
+  cache path) into hooks/shims/scheduled jobs; re-running setup repairs a
+  stale interpreter in existing hooks.
+- Account switches also reset burn-rate samples; source flips
+  (endpoint↔local) reset them too, preventing phantom burn spikes.
+- Warn keys bucket the reset time to the hour, so endpoint drift can't
+  re-warn mid-window; an active weekly stop suppresses the contradictory
+  5h resume instruction.
+- Watcher dry-run is truly read-only; rescue retries on failed resumes;
+  resumed/notified ledgers prune after 24h; cwd is shell-quoted (and falls
+  back to home when deleted) in resume commands.
+- `status` reads state under the lock; `--debug` never writes unlocked.
+- Partial `token_weights` config merges over defaults instead of crashing
+  the scan; multi-machine calibration guarded by a substantial-usage floor
+  and smoothing; missing-budget rescans throttled to hourly.
+- Empty hook session_id falls back to the transcript filename.
+- Removed a stale committed wheel from `dist/` (would have broken future
+  publishes); sdist excludes demo/CI files; README/SECURITY corrections
+  (Keychain enumeration disclosure, honest UA, cadence and trigger accuracy,
+  uninstall matrix per install method, sleep/`caffeinate` caveat, absolute
+  image URLs for PyPI).
+
+## [0.2.0] - 2026-07-18
+
+### Added
+- **Burn-rate prediction**: warnings also fire when the recent burn rate
+  projects the limit within `safety_margin_min` minutes — catches fast
+  (subagent-heavy) burns the static threshold misses.
+- **Adaptive check cadence**: 30s above 80% usage, every hook event above 90%.
+- **Pause ledger + rescue**: every pause is recorded; the watcher resumes
+  napping sessions whose in-session alarm died (sleep/reboot/crash).
+- **Weekly guard** (opt-in, `weekly_guard: true`): warn/pause on the weekly
+  window; pauses without scheduling a resume since weekly resets are days out.
+- **Account-switch detection**: per-account cached state clears automatically
+  on `/login` to a different account.
+- **Cross-platform state locking**: concurrent sessions can no longer race
+  state.json (fcntl/msvcrt; 12-process CI test).
+
+## [0.1.0] - 2026-07-18
+
+Initial release.
+
+### Added
+- Usage monitor hook (`PostToolUse`/`UserPromptSubmit`/`Stop`): warns the live
+  session at a configurable threshold (default 90%) of the 5-hour window,
+  with the pause-checkpoint-reschedule protocol injected into context.
+- Hybrid usage source: exact numbers from the OAuth usage endpoint with
+  automatic fallback to local transcript estimation, continuously calibrated
+  against endpoint truth.
+- Fallback watcher: detects sessions that hard-hit the limit, waits for the
+  reset, and resumes them visibly (new terminal window) — with a
+  never-fork-a-live-session guarantee; notifies instead when in doubt.
+- `claude-powernap on|off|status|log` CLI.
+- Platforms: macOS (Keychain/launchd/osascript), Linux incl. WSL
+  (credentials file/systemd user timer/notify-send, terminal auto-detect),
+  native Windows experimental (Task Scheduler/toasts/wt).
+- CI: full install→monitor→hook→watcher→uninstall cycle on macOS, Ubuntu,
+  and Windows runners.

claude_powernap-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 asiagenawi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

claude_powernap-0.3.0/PKG-INFO

@@ -0,0 +1,218 @@
+Metadata-Version: 2.4
+Name: claude-powernap
+Version: 0.3.0
+Summary: Your Claude Code session sees the 5-hour limit coming, checkpoints its work, and resumes itself when the window resets.
+Project-URL: Homepage, https://github.com/asiagenawi/claude-powernap
+Project-URL: Changelog, https://github.com/asiagenawi/claude-powernap/blob/main/CHANGELOG.md
+Author: asiagenawi
+License-Expression: MIT
+License-File: LICENSE
+Keywords: anthropic,auto-resume,claude,claude-code,rate-limit,usage-limit
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# claude-powernap
+
+[![CI](https://github.com/asiagenawi/claude-powernap/actions/workflows/ci.yml/badge.svg)](https://github.com/asiagenawi/claude-powernap/actions/workflows/ci.yml)
+[![Release](https://img.shields.io/github/v/release/asiagenawi/claude-powernap)](https://github.com/asiagenawi/claude-powernap/releases)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/asiagenawi/claude-powernap/blob/main/LICENSE)
+![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey)
+![Deps](https://img.shields.io/badge/deps-stdlib%20only-brightgreen)
+
+**Your Claude Code session sees the usage limit coming, saves its work, and
+resumes itself when the window resets. You do nothing.**
+
+*(Demo below is an illustrative mock-up of a real cycle the tool ran.)*
+
+![claude-powernap demo: a session gets warned at 91%, checkpoints, pauses, and self-resumes after the window resets](https://raw.githubusercontent.com/asiagenawi/claude-powernap/main/demo/powernap.gif)
+
+## The problem
+
+You kick off a long Claude Code automation — a big refactor, a batch
+migration, an overnight research run. You check back three hours later and
+find it died 40 minutes in:
+
+```
+You've hit your session limit · resets 3:00am
+```
+
+Everything since the last commit is in limbo. The context that session had
+built up is sitting frozen mid-thought. And the limit reset hours ago — the
+session just had no way to know, no way to save itself, and no way to come
+back. Your subscription's 5-hour window reset while your automation sat
+dead in a terminal.
+
+## The idea
+
+A session that's *about* to hit the limit still has tokens left. That's
+enough budget to do something smarter than die:
+
+1. **A hook watches your usage** (every ~2 min normally, tightening to ~15s
+   near the limit; zero workflow changes). It knows your exact window percentage and reset time — the same
+   numbers Claude Code's own `/usage` screen shows.
+2. **At 90% — or earlier if your burn rate projects the limit within ~9
+   minutes — the session itself gets warned**: the hook injects a message
+   into the live conversation: *"you're at 91%, window resets at 3:00am,
+   pause now."*
+3. **Claude wraps up gracefully**: finishes the current step, writes a
+   checkpoint file (what's done, what's in flight, exact next steps), and —
+   when the session has a scheduled-tasks capability — schedules a one-shot
+   task for just after the reset. Then it idles.
+4. **At reset, the session wakes itself** — same terminal, same context,
+   reads its checkpoint, keeps going. Sessions without a scheduler instead
+   checkpoint and tell you when to send any message to resume — and the
+   watcher (below) still notifies or reopens as needed.
+
+If the estimate is ever wrong and a session hard-hits the wall anyway, a
+background watcher catches that too: after the reset it reopens the session
+in a visible terminal window with the "continue from your checkpoint" prompt
+already submitted. If the original window is still open, you get a
+notification instead — it will never fork a live session.
+
+## How it compares
+
+| | warns before the limit | session saves its work | resumes automatically | needs tmux |
+|---|---|---|---|---|
+| **claude-powernap** | ✅ | ✅ | ✅ same session | no |
+| usage monitors (ccusage, claude-monitor) | ⚠️ warns *you*, not the session | ❌ | ❌ | — |
+| auto-retriers (unsnooze, claude-auto-retry, …) | ❌ reacts after death | ❌ dies mid-thought | ✅ | mostly yes |
+
+Free, privacy-first, local-only, no dependencies (Python 3 stdlib only). macOS, Linux (incl.
+WSL), native Windows (experimental).
+
+## Install
+
+As a Claude Code plugin (inside any Claude Code session):
+
+```
+/plugin marketplace add asiagenawi/claude-powernap
+/plugin install powernap@claude-powernap
+```
+
+The plugin activates the monitoring hooks immediately. The one thing a
+plugin can't do itself is register the fallback watcher (an OS-level
+background job) — so on first run the hook notices it's missing and has the
+session offer you the one command to set it up (or run `/powernap:watcher`
+yourself anytime). Also ships `/powernap:status` and `/powernap:toggle
+on|off`.
+
+From PyPI (all platforms):
+
+```bash
+uvx claude-powernap setup        # or: pipx install claude-powernap && claude-powernap setup
+```
+
+Or from a clone, if you'd rather read what you run first:
+
+```bash
+git clone https://github.com/asiagenawi/claude-powernap.git && cd claude-powernap
+./install.sh        # macOS / Linux / WSL — same as `claude-powernap setup`
+```
+
+Native Windows clone (PowerShell 7 recommended): `.\install.ps1`
+
+Pick ONE install method — plugin or pip/clone. (Both at once is harmless —
+the shared state throttle makes duplicate checks no-ops — but pointless.)
+
+That's the whole setup. Every Claude Code session on the machine is covered —
+no per-project config, no special launcher, no flags to remember. Start your
+long automations exactly the way you already do.
+
+Setup is deliberately boring and inspectable: it copies a few Python files
+to `~/.claude/claude-powernap/`, merges three hook entries into
+`~/.claude/settings.json` (backing it up first), and schedules the fallback
+watcher (launchd / systemd user timer / Task Scheduler).
+`claude-powernap remove` (or `./uninstall.sh`) reverses all of it. If you
+set `CLAUDE_CONFIG_DIR`, setup follows it — run setup from a normal shell,
+not from inside a Claude Code session, so the right settings file is edited.
+
+On macOS the first usage check may trigger one Keychain prompt — the monitor
+reads Claude Code's own OAuth token to ask Anthropic for your real usage
+numbers (see Caveats). Click "Always Allow".
+
+## Toggle
+
+```bash
+claude-powernap on       # enable everything
+claude-powernap off      # disable everything
+claude-powernap status   # current 5h + weekly usage, watcher state
+claude-powernap log      # what the watcher and monitor have been doing
+```
+
+## Configure — `~/.claude/claude-powernap/config.json`
+
+| key | default | meaning |
+|---|---|---|
+| `enabled` | `true` | master switch (what `on`/`off` flips) |
+| `threshold_pct` | `90` | warn/pause threshold for the 5h window |
+| `check_interval_s` | `120` | base seconds between checks (auto-tightens to 30s above 80%, every event above 90%) |
+| `safety_margin_min` | `9` | also warn when the current burn rate projects the limit within this many minutes |
+| `weekly_guard` | `false` | opt-in: also warn/pause on the **weekly** window (no auto-resume — its reset is days away) |
+| `weekly_threshold_pct` | `90` | weekly-guard warning threshold |
+| `endpoint_enabled` | `true` | `false` = fully local estimation only |
+| `terminal_app` | `Terminal` | macOS: `Terminal`/`iTerm2`; Linux: terminal binary name (auto-detected if unset) |
+| `resume_grace_min` | `3` | schedule resume this long after reset |
+| `headless_resume_extra_args` | `[]` | extra flags for last-resort headless resume |
+| `local_budget_weighted_tokens` | `null` | manual budget for local estimation |
+| `token_weights` | in/out/cache | per-token-type weights for local estimation |
+
+## Plays by the rules
+
+claude-powernap works *with* the usage limit, not around it:
+
+- **Zero extra usage.** The same quota, consumed the same way. It never
+  gets you more tokens — it just stops a session from dying mid-thought
+  and picks the work back up when your own window resets.
+- **Genuine client, official hooks.** Everything runs inside the real
+  Claude Code client through its documented hooks system. It never spoofs
+  a client identity and never touches permission systems.
+- **Privacy-first, local-only.** Checkpoints, transcripts, config — all of
+  it stays on your machine. The one outbound call is the same usage query
+  the built-in `/usage` screen makes, and `endpoint_enabled: false` turns
+  even that off.
+
+## Caveats
+
+- **Undocumented usage endpoint** — exact percentages come from the same
+  unpublished API `/usage` uses (read-only, via the OAuth token already on
+  your machine; a ToS gray area). Handled: if the endpoint fails or
+  you set `endpoint_enabled: false`, the tool switches automatically to
+  local transcript estimation, self-calibrated whenever endpoint data was
+  available.
+- **The paused session must stay open** — that's the point. If its alarm
+  dies anyway (sleep, reboot, crash), the watcher notices the missed wake-up
+  and resumes the session itself.
+- **Windows is experimental** — Windows can't reliably tell whether a session
+  is still open, so the watcher errs toward caution there: when unsure it
+  notifies you instead of auto-resuming (one click, never a forked session).
+  CI runs the full cycle on real Windows runners. WSL users: use
+  `./install.sh` inside WSL.
+- **Sleep beats timers** — a sleeping laptop fires nothing: the in-session
+  alarm and the watcher both wait until the machine wakes, then the watcher
+  catches up (rescuing any missed wake-ups). For unattended overnight runs
+  keep the machine awake, e.g. `caffeinate -is` on macOS.
+- **Linux notes**: terminal emulator auto-detected; headless servers fall
+  through to headless resume; `loginctl enable-linger $USER` keeps the
+  watcher running while logged out.
+
+## Uninstall
+
+By install method:
+
+| installed via | uninstall with |
+|---|---|
+| plugin | run `python3 ~/.claude/claude-powernap/cli.py watcher-remove` (if you set up the watcher), then `/plugin uninstall powernap` |
+| PyPI | `claude-powernap remove` (add `--purge` to delete config/state too), **then** `pip uninstall claude-powernap` — in that order |
+| clone | `./uninstall.sh` (or `--purge`); Windows: `.\uninstall.ps1` (or `-Purge`) |
+
+## License
+
+MIT

claude_powernap-0.3.0/README.md

@@ -0,0 +1,197 @@
+# claude-powernap
+
+[![CI](https://github.com/asiagenawi/claude-powernap/actions/workflows/ci.yml/badge.svg)](https://github.com/asiagenawi/claude-powernap/actions/workflows/ci.yml)
+[![Release](https://img.shields.io/github/v/release/asiagenawi/claude-powernap)](https://github.com/asiagenawi/claude-powernap/releases)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/asiagenawi/claude-powernap/blob/main/LICENSE)
+![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey)
+![Deps](https://img.shields.io/badge/deps-stdlib%20only-brightgreen)
+
+**Your Claude Code session sees the usage limit coming, saves its work, and
+resumes itself when the window resets. You do nothing.**
+
+*(Demo below is an illustrative mock-up of a real cycle the tool ran.)*
+
+![claude-powernap demo: a session gets warned at 91%, checkpoints, pauses, and self-resumes after the window resets](https://raw.githubusercontent.com/asiagenawi/claude-powernap/main/demo/powernap.gif)
+
+## The problem
+
+You kick off a long Claude Code automation — a big refactor, a batch
+migration, an overnight research run. You check back three hours later and
+find it died 40 minutes in:
+
+```
+You've hit your session limit · resets 3:00am
+```
+
+Everything since the last commit is in limbo. The context that session had
+built up is sitting frozen mid-thought. And the limit reset hours ago — the
+session just had no way to know, no way to save itself, and no way to come
+back. Your subscription's 5-hour window reset while your automation sat
+dead in a terminal.
+
+## The idea
+
+A session that's *about* to hit the limit still has tokens left. That's
+enough budget to do something smarter than die:
+
+1. **A hook watches your usage** (every ~2 min normally, tightening to ~15s
+   near the limit; zero workflow changes). It knows your exact window percentage and reset time — the same
+   numbers Claude Code's own `/usage` screen shows.
+2. **At 90% — or earlier if your burn rate projects the limit within ~9
+   minutes — the session itself gets warned**: the hook injects a message
+   into the live conversation: *"you're at 91%, window resets at 3:00am,
+   pause now."*
+3. **Claude wraps up gracefully**: finishes the current step, writes a
+   checkpoint file (what's done, what's in flight, exact next steps), and —
+   when the session has a scheduled-tasks capability — schedules a one-shot
+   task for just after the reset. Then it idles.
+4. **At reset, the session wakes itself** — same terminal, same context,
+   reads its checkpoint, keeps going. Sessions without a scheduler instead
+   checkpoint and tell you when to send any message to resume — and the
+   watcher (below) still notifies or reopens as needed.
+
+If the estimate is ever wrong and a session hard-hits the wall anyway, a
+background watcher catches that too: after the reset it reopens the session
+in a visible terminal window with the "continue from your checkpoint" prompt
+already submitted. If the original window is still open, you get a
+notification instead — it will never fork a live session.
+
+## How it compares
+
+| | warns before the limit | session saves its work | resumes automatically | needs tmux |
+|---|---|---|---|---|
+| **claude-powernap** | ✅ | ✅ | ✅ same session | no |
+| usage monitors (ccusage, claude-monitor) | ⚠️ warns *you*, not the session | ❌ | ❌ | — |
+| auto-retriers (unsnooze, claude-auto-retry, …) | ❌ reacts after death | ❌ dies mid-thought | ✅ | mostly yes |
+
+Free, privacy-first, local-only, no dependencies (Python 3 stdlib only). macOS, Linux (incl.
+WSL), native Windows (experimental).
+
+## Install
+
+As a Claude Code plugin (inside any Claude Code session):
+
+```
+/plugin marketplace add asiagenawi/claude-powernap
+/plugin install powernap@claude-powernap
+```
+
+The plugin activates the monitoring hooks immediately. The one thing a
+plugin can't do itself is register the fallback watcher (an OS-level
+background job) — so on first run the hook notices it's missing and has the
+session offer you the one command to set it up (or run `/powernap:watcher`
+yourself anytime). Also ships `/powernap:status` and `/powernap:toggle
+on|off`.
+
+From PyPI (all platforms):
+
+```bash
+uvx claude-powernap setup        # or: pipx install claude-powernap && claude-powernap setup
+```
+
+Or from a clone, if you'd rather read what you run first:
+
+```bash
+git clone https://github.com/asiagenawi/claude-powernap.git && cd claude-powernap
+./install.sh        # macOS / Linux / WSL — same as `claude-powernap setup`
+```
+
+Native Windows clone (PowerShell 7 recommended): `.\install.ps1`
+
+Pick ONE install method — plugin or pip/clone. (Both at once is harmless —
+the shared state throttle makes duplicate checks no-ops — but pointless.)
+
+That's the whole setup. Every Claude Code session on the machine is covered —
+no per-project config, no special launcher, no flags to remember. Start your
+long automations exactly the way you already do.
+
+Setup is deliberately boring and inspectable: it copies a few Python files
+to `~/.claude/claude-powernap/`, merges three hook entries into
+`~/.claude/settings.json` (backing it up first), and schedules the fallback
+watcher (launchd / systemd user timer / Task Scheduler).
+`claude-powernap remove` (or `./uninstall.sh`) reverses all of it. If you
+set `CLAUDE_CONFIG_DIR`, setup follows it — run setup from a normal shell,
+not from inside a Claude Code session, so the right settings file is edited.
+
+On macOS the first usage check may trigger one Keychain prompt — the monitor
+reads Claude Code's own OAuth token to ask Anthropic for your real usage
+numbers (see Caveats). Click "Always Allow".
+
+## Toggle
+
+```bash
+claude-powernap on       # enable everything
+claude-powernap off      # disable everything
+claude-powernap status   # current 5h + weekly usage, watcher state
+claude-powernap log      # what the watcher and monitor have been doing
+```
+
+## Configure — `~/.claude/claude-powernap/config.json`
+
+| key | default | meaning |
+|---|---|---|
+| `enabled` | `true` | master switch (what `on`/`off` flips) |
+| `threshold_pct` | `90` | warn/pause threshold for the 5h window |
+| `check_interval_s` | `120` | base seconds between checks (auto-tightens to 30s above 80%, every event above 90%) |
+| `safety_margin_min` | `9` | also warn when the current burn rate projects the limit within this many minutes |
+| `weekly_guard` | `false` | opt-in: also warn/pause on the **weekly** window (no auto-resume — its reset is days away) |
+| `weekly_threshold_pct` | `90` | weekly-guard warning threshold |
+| `endpoint_enabled` | `true` | `false` = fully local estimation only |
+| `terminal_app` | `Terminal` | macOS: `Terminal`/`iTerm2`; Linux: terminal binary name (auto-detected if unset) |
+| `resume_grace_min` | `3` | schedule resume this long after reset |
+| `headless_resume_extra_args` | `[]` | extra flags for last-resort headless resume |
+| `local_budget_weighted_tokens` | `null` | manual budget for local estimation |
+| `token_weights` | in/out/cache | per-token-type weights for local estimation |
+
+## Plays by the rules
+
+claude-powernap works *with* the usage limit, not around it:
+
+- **Zero extra usage.** The same quota, consumed the same way. It never
+  gets you more tokens — it just stops a session from dying mid-thought
+  and picks the work back up when your own window resets.
+- **Genuine client, official hooks.** Everything runs inside the real
+  Claude Code client through its documented hooks system. It never spoofs
+  a client identity and never touches permission systems.
+- **Privacy-first, local-only.** Checkpoints, transcripts, config — all of
+  it stays on your machine. The one outbound call is the same usage query
+  the built-in `/usage` screen makes, and `endpoint_enabled: false` turns
+  even that off.
+
+## Caveats
+
+- **Undocumented usage endpoint** — exact percentages come from the same
+  unpublished API `/usage` uses (read-only, via the OAuth token already on
+  your machine; a ToS gray area). Handled: if the endpoint fails or
+  you set `endpoint_enabled: false`, the tool switches automatically to
+  local transcript estimation, self-calibrated whenever endpoint data was
+  available.
+- **The paused session must stay open** — that's the point. If its alarm
+  dies anyway (sleep, reboot, crash), the watcher notices the missed wake-up
+  and resumes the session itself.
+- **Windows is experimental** — Windows can't reliably tell whether a session
+  is still open, so the watcher errs toward caution there: when unsure it
+  notifies you instead of auto-resuming (one click, never a forked session).
+  CI runs the full cycle on real Windows runners. WSL users: use
+  `./install.sh` inside WSL.
+- **Sleep beats timers** — a sleeping laptop fires nothing: the in-session
+  alarm and the watcher both wait until the machine wakes, then the watcher
+  catches up (rescuing any missed wake-ups). For unattended overnight runs
+  keep the machine awake, e.g. `caffeinate -is` on macOS.
+- **Linux notes**: terminal emulator auto-detected; headless servers fall
+  through to headless resume; `loginctl enable-linger $USER` keeps the
+  watcher running while logged out.
+
+## Uninstall
+
+By install method:
+
+| installed via | uninstall with |
+|---|---|
+| plugin | run `python3 ~/.claude/claude-powernap/cli.py watcher-remove` (if you set up the watcher), then `/plugin uninstall powernap` |
+| PyPI | `claude-powernap remove` (add `--purge` to delete config/state too), **then** `pip uninstall claude-powernap` — in that order |
+| clone | `./uninstall.sh` (or `--purge`); Windows: `.\uninstall.ps1` (or `-Purge`) |
+
+## License
+
+MIT

claude_powernap-0.3.0/SECURITY.md

@@ -0,0 +1,35 @@
+# Security
+
+## What this tool touches
+
+- **Reads** Claude Code's OAuth token. macOS: a `security
+  find-generic-password` lookup of the cached Claude Code credentials entry;
+  on a cache miss only, it runs `security dump-keychain` once to find the
+  right entry name — that command lists metadata (names, not secrets) for
+  the whole login keychain. Linux/Windows: reads
+  `~/.claude/.credentials.json`. The token is used in memory for one request
+  and never written anywhere.
+- **Periodic outbound HTTPS requests** to `api.anthropic.com` (the usage
+  endpoint — the same query the built-in `/usage` screen makes), at most one
+  per check interval (120s normally, down to 15s near the limit). Requests
+  identify themselves honestly as `claude-powernap/<version>`. This is the
+  only network traffic the tool ever makes; disable with
+  `endpoint_enabled: false` for fully-offline operation.
+- **Edits** `~/.claude/settings.json` to register three hooks (a backup copy
+  `settings.json.powernap-backup` is written first; `claude-powernap remove`
+  reverses the edit).
+- **Reads** your local Claude Code transcripts (`~/.claude/projects/`) for
+  token math and limit detection. Nothing from them leaves your machine.
+- **Schedules** the fallback watcher via launchd / systemd user timer /
+  Task Scheduler, running as your user.
+
+## Supply chain
+
+Python 3 standard library only — no pip packages, no npm, no curl|bash. What
+you clone is what runs: ~1,400 lines of Python you can read first.
+
+## Reporting a vulnerability
+
+Use GitHub's private vulnerability reporting on this repository
+(Security → Report a vulnerability). Best-effort response from a single
+maintainer.

claude_powernap-0.3.0/install.ps1

@@ -0,0 +1,6 @@
+# claude-powernap installer (native Windows). Idempotent.
+# Thin wrapper: all logic lives in the package CLI (`claude-powernap setup`).
+$ErrorActionPreference = "Stop"
+Set-Location (Split-Path -Parent $MyInvocation.MyCommand.Path)
+$env:PYTHONPATH = "src"
+python -m claude_powernap setup

claude_powernap-0.3.0/install.sh

@@ -0,0 +1,7 @@
+#!/bin/bash
+# claude-powernap installer (macOS / Linux / WSL). Idempotent.
+# Thin wrapper: all logic lives in the package CLI (`claude-powernap setup`).
+set -euo pipefail
+cd "$(dirname "$0")"
+command -v python3 >/dev/null || { echo "ERROR: python3 required"; exit 1; }
+PYTHONPATH=src exec python3 -m claude_powernap setup

claude_powernap-0.3.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "claude-powernap"
+version = "0.3.0"
+description = "Your Claude Code session sees the 5-hour limit coming, checkpoints its work, and resumes itself when the window resets."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+authors = [{ name = "asiagenawi" }]
+keywords = ["claude", "claude-code", "anthropic", "usage-limit", "rate-limit", "auto-resume"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: MacOS",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: Microsoft :: Windows",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Build Tools",
+]
+
+[project.urls]
+Homepage = "https://github.com/asiagenawi/claude-powernap"
+Changelog = "https://github.com/asiagenawi/claude-powernap/blob/main/CHANGELOG.md"
+
+[project.scripts]
+claude-powernap = "claude_powernap.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/claude_powernap"]
+
+[tool.hatch.build.targets.sdist]
+exclude = ["demo", ".github", "scripts", ".claude-plugin", "hooks", "commands"]

claude_powernap-0.3.0/src/claude_powernap/__init__.py

@@ -0,0 +1,2 @@
+"""claude-powernap: proactive 5-hour-limit pause-and-resume for Claude Code."""
+__version__ = "0.3.0"

claude_powernap-0.3.0/src/claude_powernap/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    main()

claude_powernap-0.3.0/src/claude_powernap/assets/claude-powernap.service

@@ -0,0 +1,6 @@
+[Unit]
+Description=claude-powernap fallback watcher (resume Claude Code sessions after limit reset)
+
+[Service]
+Type=oneshot
+ExecStart=/usr/bin/env python3 %h/.claude/claude-powernap/fallback_watch.py

claude_powernap-0.3.0/src/claude_powernap/assets/claude-powernap.timer

@@ -0,0 +1,9 @@
+[Unit]
+Description=Run claude-powernap fallback watcher every 2 minutes
+
+[Timer]
+OnBootSec=2min
+OnUnitActiveSec=2min
+
+[Install]
+WantedBy=timers.target