Add current-cycle limit reporting (Composer/Auto vs other models)

The default summary now shows how much of the plan's included usage has
been consumed this billing cycle — and how much is left before hitting
the limit — as two buckets, matching the dashboard's split:

  - Composer / Auto (composer-2.5, composer-2.5-fast, Auto)
  - Other models (explicitly selected / API models)

Data comes from POST /api/dashboard/get-current-period-usage (the
endpoint the web dashboard uses), with GET /api/usage-summary as a
fallback; server-computed percentages are shown verbatim. A new
--limits-json flag dumps the raw payload for scripting. The section
degrades gracefully (silently skipped) on accounts where the endpoints
are unavailable, so existing behavior is unchanged.

Bump version to 0.2.0 (new backward-compatible feature).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: cursor-usage-cli

README.md

@@ -38,12 +38,22 @@ claude-4.6-opus-high                    233.71       786,434   1,059,451
 gemini-3.5-flash                         45.77    16,097,065   1,075,904
 gpt-5.4-high                             43.65     4,069,043   1,041,967
 ...
+
+==============================================================================
+CURSOR CYCLE LIMITS  |  resets 2026-07-04
+==============================================================================
+Composer / Auto [###########...................]   36.7% used,   63.3% left
+Other models    [####..........................]   12.4% used,   87.6% left
+Included usage  $146.80 of $400.00 used  ($253.20 left)
 ```
 
 ## ✨ Features
 
 - **One command, real numbers** — per-model tokens and compute value for the
   current billing month.
+- **📊 Cycle limits** — the default summary also shows % used / % left before
+  hitting your plan's rate limit, split into **Composer / Auto** (composer-2.5,
+  composer-2.5-fast, Auto) vs **Other models**.
 - **📅 Per-day breakdown** — `--by-day` shows how much you burned each day.
 - **🧾 CSV export** — `--csv` dumps every usage event (timestamp, model, tokens,
   cost) for your own spreadsheets and charts.
@@ -72,6 +82,7 @@ That's it — if you're signed in to Cursor on this machine, it just works.
 | `cursor-usage --month 2026-05` | Window: a specific month |
 | `cursor-usage --start 2026-06-01 --end 2026-06-07` | Window: an explicit range |
 | `cursor-usage --json` | Raw aggregated JSON (for scripting) |
+| `cursor-usage --limits-json` | Raw cycle-limits JSON (for scripting) |
 | `cursor-usage -v` | Also print which session source was used |
 
 Flags combine — e.g. `cursor-usage --by-day --csv june.csv --month 2026-06`.

docs/HOW_THIS_WAS_BUILT.md

@@ -89,6 +89,8 @@ All on `https://cursor.com`, cookie `WorkosCursorSessionToken=<sub>::<jwt>`:
 | POST | `/api/dashboard/get-aggregated-usage-events` | per-model totals: `inputTokens`, `outputTokens`, `cacheReadTokens`, `cacheWriteTokens`, `totalCents` |
 | POST | `/api/dashboard/get-filtered-usage-events` | per-event log + `totalUsageEventsCount` (paginate with `page`/`pageSize`) |
 | POST | `/api/dashboard/get-hard-limit` | `{"noUsageBasedAllowed":true}` ⇒ overage off ⇒ everything is included |
+| POST | `/api/dashboard/get-current-period-usage` | current-cycle limits: `autoPercentUsed`, `apiPercentUsed`, included spend (`planUsage`) |
+| GET  | `/api/usage-summary` | fallback cycle limits (older shape via `individualUsage.plan`) |
 
 POST body shape:
 ```json

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cursor-usage"
-version = "0.1.0"
+version = "0.2.0"
 description = "Cross-platform CLI to read your Cursor (cursor.com) usage, spend, and per-event logs."
 readme = "README.md"
 license = { text = "MIT" }

src/cursor_usage/__init__.py

@@ -1,3 +1,3 @@
 """cursor-usage: read your Cursor (cursor.com) usage, spend, and per-event logs."""
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"

src/cursor_usage/api.py

@@ -5,6 +5,8 @@
   GET  /api/usage?user=<id>                          -> legacy counter + startOfMonth
   POST /api/dashboard/get-aggregated-usage-events    -> per-model tokens + cents
   POST /api/dashboard/get-filtered-usage-events       -> per-event log (paginated)
+  POST /api/dashboard/get-current-period-usage        -> cycle limits (primary)
+  GET  /api/usage-summary                             -> cycle limits (fallback)
 
 State-changing POSTs require an ``Origin: https://cursor.com`` header (CSRF guard).
 Auth is the ``WorkosCursorSessionToken`` cookie, value ``<sub>::<jwt>`` (the ``::``
@@ -73,6 +75,12 @@ def _events_page(self, user_id, start_ms, end_ms, page, page_size):
              "userId": user_id, "page": page, "pageSize": page_size},
         )
 
+    def current_period_usage(self):
+        return self._request("/api/dashboard/get-current-period-usage", "POST", {})
+
+    def usage_summary(self):
+        return self._request("/api/usage-summary")
+
     def all_events(self, user_id, start_ms, end_ms, page_size=1000, progress=None):
         """Fetch every usage event in the window by paginating.
 

src/cursor_usage/cli.py

@@ -8,7 +8,7 @@
 from . import __version__
 from .api import CursorAPIError, CursorClient
 from .auth import SessionNotFound, resolve_cookie_value
-from .report import render_by_day, render_summary, write_csv
+from .report import render_by_day, render_limits, render_summary, write_csv
 
 
 def _ms(dt):
@@ -41,6 +41,21 @@ def _resolve_window(args, client, user_id):
     return _ms(start), _ms(end), start.strftime("%Y-%m-%d"), end.strftime("%Y-%m-%d")
 
 
+def _fetch_limits(client):
+    """Return cycle-limits payload; primary endpoint first, then fallback."""
+    last_err = None
+    for fn in (client.current_period_usage, client.usage_summary):
+        try:
+            payload = fn()
+            if isinstance(payload, dict):
+                return payload
+        except (CursorAPIError, OSError, ValueError) as exc:
+            last_err = exc
+    if last_err is not None:
+        raise last_err
+    return None
+
+
 def _progress(fetched, total):
     if total:
         sys.stderr.write("\r[events] %d/%d" % (fetched, total))
@@ -61,6 +76,8 @@ def build_parser():
                    help="write the per-event log to FILE as CSV")
     p.add_argument("--json", action="store_true",
                    help="print the raw aggregated-usage JSON and exit")
+    p.add_argument("--limits-json", action="store_true",
+                   help="print the raw cycle-limits JSON and exit")
     g = p.add_argument_group("time window (default: current billing month)")
     g.add_argument("--start", metavar="YYYY-MM-DD", help="window start (inclusive)")
     g.add_argument("--end", metavar="YYYY-MM-DD", help="window end (inclusive)")
@@ -92,6 +109,21 @@ def main(argv=None):
                   "Re-authenticate: cursor-agent login", file=sys.stderr)
             return 2
 
+        if args.limits_json:
+            # No time window needed; the endpoints always report the current cycle.
+            try:
+                payload = _fetch_limits(client)
+                if payload is None:
+                    print("Cycle-limits endpoints returned no usable data.",
+                          file=sys.stderr)
+                    return 1
+                print(json.dumps(payload, indent=2))
+            except (CursorAPIError, OSError, ValueError) as exc:
+                print("Cycle-limits endpoints returned no usable JSON: %s" % exc,
+                      file=sys.stderr)
+                return 1
+            return 0
+
         start_ms, end_ms, start_label, end_label = _resolve_window(args, client, user_id)
         meta = {"email": email, "start": start_label, "end": end_label}
 
@@ -102,6 +134,15 @@ def main(argv=None):
         # The aggregated endpoint powers the summary (one cheap call).
         print(render_summary(client.aggregated_usage(user_id, start_ms, end_ms), meta))
 
+        try:
+            section = render_limits(_fetch_limits(client))
+            if section:
+                print()
+                print(section)
+        except (CursorAPIError, OSError, ValueError) as exc:
+            if args.verbose:
+                print("[limits] unavailable: %s" % exc, file=sys.stderr)
+
         # Per-event data powers --by-day and --csv; fetch it once if needed.
         if args.by_day or args.csv:
             events, total = client.all_events(

src/cursor_usage/report.py

@@ -132,3 +132,129 @@ def write_csv(events, path):
 
 def to_iso(ms):
     return datetime.fromtimestamp(ms / 1000, tz=timezone.utc).strftime("%Y-%m-%d")
+
+
+# --- cycle limits (from get-current-period-usage / usage-summary) --------
+def _optional_f(d, k):
+    if k not in d:
+        return None
+    try:
+        v = d[k]
+        if v is None:
+            return None
+        return float(v or 0)
+    except (TypeError, ValueError):
+        return None
+
+
+def _optional_i(d, k):
+    if k not in d:
+        return None
+    try:
+        v = d[k]
+        if v is None:
+            return None
+        return int(v or 0)
+    except (TypeError, ValueError):
+        return None
+
+
+def _parse_reset_date(payload):
+    raw = payload.get("billingCycleEnd")
+    if raw is None:
+        return None
+    try:
+        s = str(raw).strip()
+        if s.isdigit():
+            ms = int(s)
+            return datetime.fromtimestamp(ms / 1000, tz=timezone.utc).strftime(
+                "%Y-%m-%d")
+        return datetime.fromisoformat(s.replace("Z", "+00:00")).strftime(
+            "%Y-%m-%d")
+    except (TypeError, ValueError, OSError):
+        return None
+
+
+def _limit_bar(pct, width=30):
+    filled = int(round(pct / 100.0 * width))
+    filled = max(0, min(width, filled))
+    return "#" * filled + "." * (width - filled)
+
+
+def _limit_bucket_line(label, pct):
+    if pct is None:
+        return None
+    bar = _limit_bar(pct)
+    left = max(0.0, 100.0 - pct)
+    return "%-16s[%s] %6.1f%% used, %6.1f%% left" % (label, bar, pct, left)
+
+
+def render_limits(payload):
+    """Render cycle-limit % bars and included-usage dollars, or None."""
+    if not payload or not isinstance(payload, dict):
+        return None
+
+    plan = (payload.get("planUsage")
+            or (payload.get("individualUsage") or {}).get("plan")
+            or {})
+
+    enabled = payload.get("enabled", plan.get("enabled", True))
+    if not enabled:
+        return None
+
+    is_unlimited = bool(payload.get("isUnlimited"))
+
+    auto_pct = _optional_f(plan, "autoPercentUsed")
+    api_pct = _optional_f(plan, "apiPercentUsed")
+
+    used = None
+    if "totalSpend" in plan:
+        used = _optional_i(plan, "totalSpend")
+    if used is None and "used" in plan:
+        used = _optional_i(plan, "used")
+
+    limit = _optional_i(plan, "limit") if "limit" in plan else None
+
+    remaining = None
+    if "remaining" in plan:
+        remaining = _optional_i(plan, "remaining")
+    if remaining is None and limit is not None and used is not None:
+        remaining = max(0, limit - used)
+
+    money_line = None
+    if limit is not None and limit > 0 and used is not None and remaining is not None:
+        money_line = "%-16s%s of %s used  (%s left)" % (
+            "Included usage", _money(used), _money(limit), _money(remaining))
+
+    if (not is_unlimited and auto_pct is None and api_pct is None
+            and not money_line):
+        return None
+
+    reset = _parse_reset_date(payload)
+
+    out = ["=" * 78]
+    header = "CURSOR CYCLE LIMITS"
+    if reset:
+        header += "  |  resets %s" % reset
+    out.append(header)
+    out.append("=" * 78)
+
+    if is_unlimited:
+        out.append("Plan reports unlimited usage for this cycle.")
+        if money_line:
+            out.append(money_line)
+        return "\n".join(out)
+
+    for label, pct in [("Composer / Auto", auto_pct),
+                       ("Other models", api_pct)]:
+        line = _limit_bucket_line(label, pct)
+        if line:
+            out.append(line)
+
+    if money_line:
+        out.append(money_line)
+
+    if len(out) <= 3:
+        return None
+
+    return "\n".join(out)