claude-limit-statusline 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ann0nip
+
+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.

package/README.md

@@ -0,0 +1,157 @@
+# claude-limit-statusline
+
+A [Claude Code](https://code.claude.com/docs) status line that shows your **real
+subscription limits** — the 5‑hour session window and the 7‑day weekly window —
+with a **live reset countdown**.
+
+```
+🤖 Opus 4.8 (1M context) | 🧠 42k (4%) | ⏳ Session 17% · resets in 0h47m (23:12) | 📅 Week 10% · resets in 2d 21h (Jun 03 19:54)
+```
+
+Unlike tools that estimate the 5‑hour block from local logs, this reads the
+**official `rate_limits` payload** that Claude Code provides on stdin — the same
+numbers you see when you run `/usage`. No guessing, no rounding to the hour.
+
+## Who is this for?
+
+This shows the **subscription rate limits** that Anthropic exposes only to
+**Claude.ai Pro/Max** users. If you use the **pay‑as‑you‑go API**, the
+`rate_limits` field is not present — you probably want a cost tracker like
+[`ccusage`](https://github.com/ryoppippi/ccusage) instead.
+
+| | Pro/Max subscription | Pay‑as‑you‑go API |
+| --- | --- | --- |
+| `rate_limits` in status line | ✅ yes | ❌ no |
+| What this tool shows | 5h + 7d limit % and reset | — |
+
+## Install
+
+```bash
+npm install -g claude-limit-statusline
+cc-limits --install
+```
+
+That's it. `--install` writes the `statusLine` entry into `~/.claude/settings.json`
+for you (merging, never clobbering your other settings). Then open a **new**
+Claude Code session and send one message — `rate_limits` populates after the
+first API response.
+
+Want only the two limits? Pass your display options straight through:
+
+```bash
+cc-limits --install --segments=session,week
+```
+
+To remove it again:
+
+```bash
+cc-limits --uninstall
+```
+
+> **Why `--install` instead of editing by hand?** It records an **absolute**
+> `node` + script path, so it works even under nvm/Volta where a globally
+> installed command isn't on the `PATH` of the non‑login shell Claude Code uses
+> for the status line.
+
+<details>
+<summary>Manual setup (if you prefer)</summary>
+
+Add this to `~/.claude/settings.json`:
+
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "cc-limits"
+  }
+}
+```
+
+If the bar stays blank (nvm/Volta `PATH` issue), use absolute paths instead —
+`"command": "/path/to/node /path/to/cli.js"` (find them with `which node` and
+`npm root -g`), which is exactly what `cc-limits --install` does automatically.
+
+</details>
+
+## Output
+
+| Segment | Meaning | Source |
+| --- | --- | --- |
+| `🤖 model` | Active model | local |
+| `🧠 42k (4%)` | Tokens in the current context window | local |
+| `⏳ Session 17% · resets in 0h47m (23:12)` | **Real** 5‑hour limit used + reset | server |
+| `📅 Week 10% · resets in 2d 21h (Jun 03 19:54)` | **Real** 7‑day limit used + reset | server |
+
+The percentage **is** your "how close am I to the limit" gauge. Subscription
+limits are dynamic, so Anthropic does not expose a fixed token cap — only a
+percentage, which is exactly what this surfaces.
+
+Before the first API response (and right after `/compact`) the session segment
+shows `⏳ Session --` until fresh data arrives.
+
+## Configuration
+
+Pick **which segments** to show (and their order). The four segments are
+`model`, `context`, `session`, `week`.
+
+```jsonc
+// Only the two limits, nothing else:
+"command": "cc-limits --segments=session,week"
+
+// Everything except the context tokens:
+"command": "cc-limits --no-context"
+```
+
+Pick **which reset countdowns** to show:
+
+```jsonc
+"command": "cc-limits --reset=session"   // session reset only
+"command": "cc-limits --no-reset"        // just percentages, no countdowns
+```
+
+### Flags
+
+| Flag | Description |
+| --- | --- |
+| `--segments=a,b,c` | Allowlist + order. Subset of `model,context,session,week` |
+| `--no-<segment>` | Hide one segment (e.g. `--no-context`). Repeatable |
+| `--reset=both\|session\|week\|none` | Which reset countdowns to show (default `both`) |
+| `--no-reset` | Shorthand for `--reset=none` |
+| `--no-color` | Disable ANSI colors |
+| `--demo` | Print a sample line (no stdin needed) |
+| `-h`, `--help` | Show help |
+
+### Environment variables
+
+Equivalent to the flags, handy if you don't want to edit the command string:
+
+| Env var | Default | Description |
+| --- | --- | --- |
+| `CC_LIMITS_SEGMENTS` | `model,context,session,week` | Segments + order |
+| `CC_LIMITS_RESET` | `both` | `both` / `session` / `week` / `none` |
+| `CC_LIMITS_WARN` | `70` | % at/above which a limit turns yellow |
+| `CC_LIMITS_CRIT` | `90` | % at/above which a limit turns red |
+| `CC_LIMITS_SEP` | `" \| "` | Separator between segments |
+| `NO_COLOR` | — | Set to disable ANSI colors |
+
+```bash
+cc-limits --demo
+cc-limits --segments=session,week --reset=session --demo
+```
+
+## How it works
+
+Claude Code runs your status-line command on every update and pipes a JSON
+[status-line payload](https://code.claude.com/docs/en/statusline) to stdin. This
+program parses it and reads:
+
+- `rate_limits.five_hour.used_percentage` / `.resets_at`
+- `rate_limits.seven_day.used_percentage` / `.resets_at`
+- `context_window.*` for the token/context segment
+
+`resets_at` is Unix epoch seconds; the countdown is computed against the current
+time. Everything runs with **zero dependencies** for fast startup.
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,364 @@
+#!/usr/bin/env node
+"use strict";
+
+/**
+ * claude-limit-statusline
+ *
+ * A Claude Code status line that shows your REAL subscription rate limits
+ * (5-hour session + 7-day weekly) with a live reset countdown.
+ *
+ * Claude Code pipes a JSON payload on stdin. For Claude.ai Pro/Max
+ * subscribers it contains a `rate_limits` object sourced from Anthropic's
+ * servers — the same numbers you see in `/usage`. This reads those fields
+ * and prints a single status line. It does NOT estimate locally.
+ *
+ * Docs: https://code.claude.com/docs/en/statusline
+ */
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+
+const argv = process.argv.slice(2);
+
+// ---------- arg / env helpers ----------
+function getFlagValue(key) {
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === key) {
+      const next = argv[i + 1];
+      return next && !next.startsWith("--") ? next : "";
+    }
+    if (a.startsWith(key + "=")) return a.slice(key.length + 1);
+  }
+  return undefined;
+}
+function parseList(val) {
+  return String(val)
+    .split(",")
+    .map((s) => s.trim().toLowerCase())
+    .filter(Boolean);
+}
+function numEnv(name, def) {
+  const v = Number(process.env[name]);
+  return Number.isFinite(v) ? v : def;
+}
+
+// ---------- config ----------
+const ALL_SEGMENTS = ["model", "context", "session", "week"];
+
+// Which segments to show. --segments / CC_LIMITS_SEGMENTS = allowlist (and order).
+// Otherwise the full set minus any --no-<segment> flags.
+let SEGMENTS;
+const segSel = getFlagValue("--segments") || process.env.CC_LIMITS_SEGMENTS;
+if (segSel != null && segSel !== "") {
+  SEGMENTS = parseList(segSel).filter((s) => ALL_SEGMENTS.includes(s));
+} else {
+  SEGMENTS = ALL_SEGMENTS.filter((s) => !argv.includes(`--no-${s}`));
+}
+
+// Which reset countdowns to show: both | session | week | none.
+let RESET_MODE = (
+  getFlagValue("--reset") ||
+  process.env.CC_LIMITS_RESET ||
+  "both"
+).toLowerCase();
+if (argv.includes("--no-reset")) RESET_MODE = "none";
+function showReset(which) {
+  return RESET_MODE === "both" || RESET_MODE === which;
+}
+
+const WARN_PCT = numEnv("CC_LIMITS_WARN", 70);
+const CRIT_PCT = numEnv("CC_LIMITS_CRIT", 90);
+const SEP = process.env.CC_LIMITS_SEP || " | ";
+const NO_COLOR =
+  argv.includes("--no-color") ||
+  (process.env.NO_COLOR != null && process.env.NO_COLOR !== "");
+
+// ---------- colors ----------
+const C = {
+  reset: "\x1b[0m",
+  dim: "\x1b[2m",
+  red: "\x1b[31m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  cyan: "\x1b[36m",
+  gray: "\x1b[90m",
+};
+function paint(s, color) {
+  if (NO_COLOR || !color) return s;
+  return color + s + C.reset;
+}
+function pctColor(p) {
+  if (p >= CRIT_PCT) return C.red;
+  if (p >= WARN_PCT) return C.yellow;
+  return C.green;
+}
+
+// ---------- formatters ----------
+const MON = [
+  "Jan", "Feb", "Mar", "Apr", "May", "Jun",
+  "Jul", "Aug", "Sep", "Oct", "Nov", "Dec",
+];
+function pad(n) {
+  return String(n).padStart(2, "0");
+}
+// Strip control chars / ANSI escapes from untrusted string fields before
+// printing them to the terminal.
+function clean(s) {
+  return String(s).replace(/[\x00-\x1f\x7f]/g, "");
+}
+function round(n) {
+  return Math.round(Number(n));
+}
+function humanTokens(n) {
+  n = Number(n) || 0;
+  if (n >= 1000) return Math.round(n / 1000) + "k";
+  return String(n);
+}
+function fmtCountdown(epochSec) {
+  let diff = Math.floor(epochSec - Date.now() / 1000);
+  if (diff < 0) diff = 0;
+  const d = Math.floor(diff / 86400);
+  const h = Math.floor((diff % 86400) / 3600);
+  const m = Math.floor((diff % 3600) / 60);
+  if (d > 0) return `${d}d ${h}h`;
+  return `${h}h${pad(m)}m`;
+}
+function fmtClock(epochSec, withDate) {
+  const d = new Date(epochSec * 1000);
+  const time = `${pad(d.getHours())}:${pad(d.getMinutes())}`;
+  if (withDate) return `${MON[d.getMonth()]} ${pad(d.getDate())} ${time}`;
+  return time;
+}
+
+// ---------- segment renderers ----------
+function renderModel(data) {
+  const model = clean(data?.model?.display_name || "Claude");
+  return paint("🤖 " + model, C.cyan);
+}
+function renderContext(data) {
+  const cw = data?.context_window || {};
+  const tokens =
+    (Number(cw.total_input_tokens) || 0) +
+    (Number(cw.total_output_tokens) || 0);
+  let s = "🧠 " + humanTokens(tokens);
+  if (cw.used_percentage != null) s += ` (${round(cw.used_percentage)}%)`;
+  return paint(s, C.gray);
+}
+function renderLimit(limit, { icon, label, which, withDate }) {
+  if (!limit || limit.used_percentage == null) {
+    return paint(`${icon} ${label} --`, C.dim);
+  }
+  const p = round(limit.used_percentage);
+  let s = `${icon} ${label} ${paint(p + "%", pctColor(p))}`;
+  if (limit.resets_at > 0 && showReset(which)) {
+    s += paint(
+      ` · resets in ${fmtCountdown(limit.resets_at)} (${fmtClock(
+        limit.resets_at,
+        withDate
+      )})`,
+      C.dim
+    );
+  }
+  return s;
+}
+
+function render(data) {
+  const rl = data?.rate_limits || {};
+  const out = [];
+  for (const seg of SEGMENTS) {
+    if (seg === "model") out.push(renderModel(data));
+    else if (seg === "context") out.push(renderContext(data));
+    else if (seg === "session")
+      out.push(
+        renderLimit(rl.five_hour, {
+          icon: "⏳",
+          label: "Session",
+          which: "session",
+          withDate: false,
+        })
+      );
+    else if (seg === "week")
+      out.push(
+        renderLimit(rl.seven_day, {
+          icon: "📅",
+          label: "Week",
+          which: "week",
+          withDate: true,
+        })
+      );
+  }
+  return out.join(SEP);
+}
+
+// ---------- demo payload ----------
+function demoPayload() {
+  const now = Math.floor(Date.now() / 1000);
+  return {
+    model: { display_name: "Opus 4.8 (1M context)" },
+    context_window: {
+      used_percentage: 4,
+      total_input_tokens: 40000,
+      total_output_tokens: 2328,
+    },
+    rate_limits: {
+      five_hour: { used_percentage: 17, resets_at: now + 2880 },
+      seven_day: { used_percentage: 10, resets_at: now + 250000 },
+    },
+  };
+}
+
+// ---------- main ----------
+function out(line) {
+  process.stdout.write(line + "\n");
+}
+
+if (argv.includes("--help") || argv.includes("-h")) {
+  out(
+    [
+      "claude-limit-statusline (cc-limits)",
+      "",
+      "Reads Claude Code's JSON status-line payload on stdin and prints your",
+      "real Pro/Max rate limits (5h session + 7d week) with reset countdowns.",
+      "",
+      "Setup (writes ~/.claude/settings.json for you):",
+      "  cc-limits --install                      configure the status line",
+      "  cc-limits --install --segments=session,week   ...with display options",
+      "  cc-limits --uninstall                    remove it again",
+      "",
+      "Or set it manually in ~/.claude/settings.json:",
+      '  "statusLine": { "type": "command", "command": "cc-limits" }',
+      "",
+      "Segments (default: all, in this order): model, context, session, week",
+      "  --segments=session,week   Show only these, in this order",
+      "  --no-context              Hide a single segment (repeatable)",
+      "  --no-model --no-week      ...",
+      "",
+      "Reset countdowns:",
+      "  --reset=both|session|week|none   Which resets to show (default both)",
+      "  --no-reset                       Same as --reset=none",
+      "",
+      "Other flags: --demo, --no-color, -h/--help",
+      "",
+      "Env vars:",
+      "  CC_LIMITS_SEGMENTS=model,context,session,week",
+      "  CC_LIMITS_RESET=both|session|week|none",
+      "  CC_LIMITS_WARN=70    yellow threshold (% of a limit)",
+      "  CC_LIMITS_CRIT=90    red threshold",
+      "  CC_LIMITS_SEP=' | '  segment separator",
+      "  NO_COLOR             disable colors",
+    ].join("\n")
+  );
+  process.exit(0);
+}
+
+// ---------- install / uninstall into ~/.claude/settings.json ----------
+function settingsPath() {
+  return path.join(os.homedir(), ".claude", "settings.json");
+}
+function quoteArg(s) {
+  return /[\s"\\]/.test(s) ? '"' + s.replace(/(["\\])/g, "\\$1") + '"' : s;
+}
+function buildCommand(passthrough) {
+  // Absolute node + script path => immune to the non-login-shell PATH issue
+  // (e.g. nvm) that can leave a globally-installed `cc-limits` off the PATH.
+  return [process.execPath, __filename, ...passthrough].map(quoteArg).join(" ");
+}
+function readSettings(p) {
+  let raw;
+  try {
+    raw = fs.readFileSync(p, "utf8");
+  } catch (e) {
+    if (e.code === "ENOENT") return { settings: {}, existed: false };
+    console.error("cc-limits: cannot read " + p + ": " + e.message);
+    process.exit(1);
+  }
+  try {
+    return { settings: raw.trim() ? JSON.parse(raw) : {}, existed: true };
+  } catch {
+    console.error(
+      "cc-limits: " + p + " is not valid JSON — aborting so it isn't clobbered.\n" +
+        "Fix or remove it, then re-run, or configure the status line manually."
+    );
+    process.exit(1);
+  }
+}
+function doInstall(passthrough) {
+  const p = settingsPath();
+  const { settings, existed } = readSettings(p);
+  settings.statusLine = { type: "command", command: buildCommand(passthrough) };
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, JSON.stringify(settings, null, 2) + "\n");
+  console.log("cc-limits: status line " + (existed ? "updated in " : "written to ") + p);
+  console.log("→ " + settings.statusLine.command);
+  console.log("Open a NEW Claude Code session and send one message to see it.");
+}
+function doUninstall() {
+  const p = settingsPath();
+  const { settings, existed } = readSettings(p);
+  if (!existed || !settings.statusLine) {
+    console.log("cc-limits: no status line configured in " + p + " — nothing to do.");
+    return;
+  }
+  delete settings.statusLine;
+  fs.writeFileSync(p, JSON.stringify(settings, null, 2) + "\n");
+  console.log("cc-limits: removed status line from " + p);
+}
+
+if (argv.includes("--install")) {
+  const passthrough = argv.filter((a) => a !== "--install" && a !== "--uninstall");
+  doInstall(passthrough);
+  process.exit(0);
+}
+if (argv.includes("--uninstall")) {
+  doUninstall();
+  process.exit(0);
+}
+
+if (argv.includes("--demo")) {
+  out(render(demoPayload()));
+  process.exit(0);
+}
+
+if (process.stdin.isTTY) {
+  out(
+    render(demoPayload()) +
+      "  " +
+      paint("(demo — pipe Claude Code JSON in)", C.dim)
+  );
+  process.exit(0);
+}
+
+const MAX_INPUT = 1 << 20; // 1 MB safety cap on stdin
+let input = "";
+let done = false;
+
+function finish(raw) {
+  if (done) return;
+  done = true;
+  let data = {};
+  try {
+    data = raw ? JSON.parse(raw) : {};
+  } catch {
+    data = {};
+  }
+  out(render(data));
+}
+
+// Never hang: if no EOF arrives, render with whatever we have after 2s.
+const timer = setTimeout(() => finish(input), 2000);
+if (timer.unref) timer.unref();
+
+process.stdin.setEncoding("utf8");
+process.stdin.on("data", (chunk) => {
+  if (input.length < MAX_INPUT) input += chunk;
+});
+process.stdin.on("error", () => {
+  clearTimeout(timer);
+  finish("");
+});
+process.stdin.on("end", () => {
+  clearTimeout(timer);
+  finish(input);
+});

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "claude-limit-statusline",
+  "version": "0.2.0",
+  "description": "Claude Code status line that shows your REAL Pro/Max subscription limits — 5-hour session and 7-day weekly usage with a live reset countdown. Uses the official rate_limits payload, not a local estimate.",
+  "type": "commonjs",
+  "bin": {
+    "cc-limits": "bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "demo": "node bin/cli.js --demo"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "statusline",
+    "status-line",
+    "rate-limits",
+    "usage",
+    "pro",
+    "max",
+    "subscription",
+    "anthropic"
+  ],
+  "author": "Ann0nip (https://github.com/ann0nip)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ann0nip/claude-limit-statusline.git"
+  },
+  "homepage": "https://github.com/ann0nip/claude-limit-statusline#readme",
+  "bugs": {
+    "url": "https://github.com/ann0nip/claude-limit-statusline/issues"
+  }
+}