cc-peak-hours 1.0.0

package/docs/superpowers/specs/2026-03-31-claude-peak-hours-design.md

@@ -0,0 +1,232 @@
+# claude-peak-hours — Design Spec
+
+## Overview
+
+Claude Code statusline plugin that permanently displays whether the user is in **peak** or **off-peak** hours, with countdown to next transition. Inspired by [isclaude-2x](https://github.com/Adiazgallici/isclaude-2x), adapted for permanent use (not tied to a temporary promotion).
+
+## Peak Hours Definition
+
+- **Peak**: 12:00 – 18:00 UTC, weekdays only (= 8AM–2PM ET / 14h–20h CET)
+- **Off-peak**: all other times (evenings, nights, weekends)
+- Defined in UTC to avoid DST ambiguity — converted to local time for display
+
+## Project Structure
+
+```
+claude-peak-hours/
+├── bin/
+│   ├── statusline.sh    # Main statusline script (bash)
+│   └── install.js       # Node installer with backup/uninstall
+├── peak-hours.json      # Remote config (peak hours definition)
+├── package.json         # npm metadata (npx claude-peak-hours)
+├── LICENSE              # MIT
+└── README.md
+```
+
+## Installation
+
+```bash
+npx claude-peak-hours                      # minimal mode, auto time format & language
+npx claude-peak-hours --full               # dashboard mode
+npx claude-peak-hours --24h               # force 24h format
+npx claude-peak-hours --lang fr            # force French
+npx claude-peak-hours --full --24h --lang fr  # combined
+npx claude-peak-hours --uninstall          # restore previous statusline
+```
+
+### Installer Behavior (install.js)
+
+1. Check dependencies (`jq`, `curl`)
+2. Backup existing statusline to `~/.claude/statusline.sh.bak`
+3. Copy `statusline.sh` to `~/.claude/statusline.sh`
+4. Update `~/.claude/settings.json` with `statusLine` config
+5. Print summary with chosen mode
+
+## Display Modes
+
+### Minimal (default) — single line
+
+**During peak (weekday 8AM-2PM ET):**
+```
+Opus 4.6 │ 39% │ 🔴 Peak ~ Off-peak 20:00 (2h15m)
+```
+
+**During off-peak:**
+```
+Opus 4.6 │ 39% │ ⚡ Off-peak ~ Peak 14:00 (5h12m)
+```
+
+**Weekend:**
+```
+Opus 4.6 │ 39% │ ⚡ Off-peak ~ Peak lun. 14:00 (1d8h)
+```
+
+### Full (`--full`) — multi-line dashboard
+
+Adds below the minimal line:
+
+- **Timeline bar**: 48 chars (2 per hour), green = off-peak, yellow = peak, `●` = now
+- **Rate limits**: session 5h (% + reset time) and weekly (% + reset date) via OAuth API
+
+**Example off-peak weekday:**
+```
+Opus 4.6 │ 39% │ ⚡ Off-peak ~ Peak 14:00 (5h12m)
+
+today  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━●━━━━━━━━━━━━━━━━━━━━  ━ off-peak ━ peak 14:00-20:00  ● now
+current ●●●●○○○○○○  42% ⟳ 22:00 │ weekly  ●●●○○○○○○○  31% ⟳ mar 20
+```
+
+**Example weekend:**
+```
+Opus 4.6 │ 12% │ ⚡ Off-peak ~ Peak lun. 14:00 (1d14h)
+
+today  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━●━━━━━━━━━━━━━━━━━━━━  ━ off-peak all day  ● now
+current ●○○○○○○○○○   5% ⟳ 20:00 │ weekly  ●●○○○○○○○○  15% ⟳ mar 22
+```
+
+## Time Format
+
+- `--24h` flag: force 24h format (`14:00`, `20:00`)
+- `--12h` flag: force 12h format (`2:00pm`, `8:00pm`)
+- No flag: auto-detect from locale:
+  - `fr_*`, `de_*`, `es_*`, `pt_*`, `it_*`, `ja_*`, `zh_*`, `ko_*`, `ru_*` → 24h
+  - `en_US`, `en_*` → 12h
+  - Fallback → 12h
+
+## Remote Config (peak-hours.json)
+
+Peak hours are defined in a JSON file hosted on the project's GitHub repo. This allows updating peak hours for all users without requiring a plugin update.
+
+### File format
+
+```json
+{
+  "version": 2,
+  "peak_windows": [
+    { "days": [1, 2, 3, 4, 5], "start_utc": 12, "end_utc": 18 }
+  ]
+}
+```
+
+- All times are in **UTC** — no timezone field needed, no DST ambiguity
+- `peak_windows`: array of peak windows, each with:
+  - `days`: ISO weekdays (1=Monday, 7=Sunday) — evaluated in UTC
+  - `start_utc` / `end_utc`: peak window boundaries (24h integers, UTC)
+- `version`: schema version for future-proofing
+- The script converts UTC boundaries to local time for display
+
+Current peak hours (8AM-2PM ET) = **12:00-18:00 UTC**.
+
+This format supports multiple peak windows:
+
+```json
+{
+  "version": 2,
+  "peak_windows": [
+    { "days": [1, 2, 3, 4, 5], "start_utc": 12, "end_utc": 18 },
+    { "days": [1, 2, 3, 4, 5], "start_utc": 22, "end_utc": 2 }
+  ]
+}
+```
+
+Note: `end_utc` < `start_utc` means the window crosses midnight UTC.
+
+### Fetch & cache strategy
+
+- **URL**: raw GitHub URL of `peak-hours.json` from the repo's `main` branch
+- **Cache**: `/tmp/claude/peak-hours-config.json`, TTL = **1 hour**
+- **Fallback**: if fetch fails (no network, GitHub down, timeout), use cached file; if no cache exists, use hardcoded defaults matching the current config above
+- **Timeout**: `curl --max-time 3` to avoid slowing down the statusline
+- The fetch happens at the same time as stdin parsing — no extra latency in the common (cached) case
+
+## Script Logic (statusline.sh)
+
+### Main Flow
+
+1. **Read stdin** — parse JSON (model, context window, usage tokens)
+1. **Load peak hours config** — from cache or remote, fallback to hardcoded defaults
+2. **Calculate context %** — color by threshold:
+   - Green: < 50%
+   - Orange: 50-70%
+   - Yellow: 70-90%
+   - Red: > 90%
+3. **Determine peak/off-peak status** (using loaded config):
+   - Get current hour and weekday in **UTC** (`TZ=UTC`)
+   - Iterate over `peak_windows[]`: check if current UTC day is in `days` AND current UTC hour is within `start_utc`–`end_utc` (handling midnight crossing)
+   - If any window matches → peak; otherwise → off-peak
+4. **Calculate countdown** to next transition:
+   - If peak → seconds until `end_utc` of the current matching window
+   - If off-peak → find the nearest upcoming window start (today or next matching day in UTC), calculate seconds until it
+5. **Convert to local time** for display (all user-facing times are local)
+5. **Convert to local time** for display
+6. **Apply time format** (12h/24h per flag or locale detection)
+
+### Full Mode Additions
+
+7. **Timeline bar** — 48 chars, 2 per hour, colored by peak/off-peak, dot for current position
+8. **OAuth rate limits fetch** (cached 60s in `/tmp/claude/`):
+   - Token from `$CLAUDE_CODE_OAUTH_TOKEN`, macOS Keychain, or `~/.claude/.credentials.json`
+   - Endpoint: `https://api.anthropic.com/api/oauth/usage`
+   - Display: session 5h (% + reset time) and weekly (% + reset date)
+
+### Colors
+
+- **Off-peak**: green `⚡` + green text
+- **Peak**: red `🔴` + red/yellow text
+- **Separator**: dim `│`
+- **Context %**: green/orange/yellow/red gradient
+
+## Dependencies
+
+- `jq` — JSON parsing (stdin + OAuth response)
+- `curl` — rate limits API fetch
+- `date` — GNU coreutils (Linux) or BSD date (macOS)
+- Auto-detection via `date --version`
+
+## Compatibility
+
+- Linux (GNU coreutils)
+- macOS (BSD date)
+
+## Localization (i18n)
+
+Two languages supported: English (default) and French.
+
+### Detection
+
+- `--lang fr` flag: force French
+- `--lang en` flag: force English
+- No flag: auto-detect from `LANG`/`LC_TIME`:
+  - `fr_*` → French
+  - Everything else → English
+
+### Translated strings
+
+| Key | English | French |
+|-----|---------|--------|
+| Peak label | `Peak` | `Pointe` |
+| Off-peak label | `Off-peak` | `Hors pointe` |
+| "all day" | `all day` | `toute la journée` |
+| "today" | `today` | `auj.` |
+| "now" | `now` | `maint.` |
+| "current" | `current` | `session` |
+| "weekly" | `weekly` | `hebdo` |
+| Weekday abbrevs | `Mon.` `Tue.` ... | `lun.` `mar.` ... |
+| Month abbrevs | `jan` `feb` ... | `jan` `fév` ... |
+
+### Implementation
+
+Strings defined as bash variables at the top of `statusline.sh`, set once based on the detected/forced language. No external translation files.
+
+## Differences from isclaude-2x
+
+| Aspect | isclaude-2x | claude-peak-hours |
+|--------|-------------|-------------------|
+| Purpose | Temporary 2x promo (Mar 13-28) | Permanent peak hours indicator |
+| Labels | "2x" / "1x" | "Off-peak" / "Peak" |
+| Promo countdown | Days remaining in promo | None |
+| Snowflake `❄` | Weekly frozen during 2x | Removed |
+| Time format | 12h only | 12h/24h with auto-detect |
+| Language | English only | English + French with auto-detect |
+| Config | Hardcoded | Remote JSON on GitHub, cached 1h, hardcoded fallback |
+| Lifespan | Expires after promo | Permanent |

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "cc-peak-hours",
+  "version": "1.0.0",
+  "description": "Claude Code statusline showing peak/off-peak hours with countdown",
+  "bin": {
+    "cc-peak-hours": "bin/install.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nickywan/claude-peak-hours.git"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "statusline",
+    "peak-hours",
+    "cli"
+  ],
+  "license": "MIT",
+  "author": "nickywan"
+}

package/peak-hours.json

@@ -0,0 +1,6 @@
+{
+  "version": 2,
+  "peak_windows": [
+    { "days": [1, 2, 3, 4, 5], "start_utc": 12, "end_utc": 18 }
+  ]
+}