claude-limits-bar 1.2.0__tar.gz

claude_limits_bar-1.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tilbert Balaban
+
+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_limits_bar-1.2.0/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: claude-limits-bar
+Version: 1.2.0
+Summary: Claude Code limits and reset times in the macOS menu bar
+Author: Tilbert Balaban
+License: MIT
+Project-URL: Homepage, https://github.com/TilbertBalaban/claude-limits-bar
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyobjc-framework-Cocoa>=9.0
+Requires-Dist: certifi
+Dynamic: license-file
+
+# claude-limits-bar
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](LICENSE)
+
+**Claude Code limits and their reset times, always visible in the macOS menu bar.**
+
+If you keep hitting *"Too many requests, please try again later"*, this shows you exactly how close you are to the limit and when it resets — before Claude Code cuts you off.
+
+The menu bar shows two ring gauges — the session (5-hour) limit in green and the 7-day limit in purple, percent used inside each — plus the countdown until the session limit resets:
+
+```
+◔66 ◔12  3h 26m
+```
+
+Click it for the full picture: a large donut for the session limit (weekly as a thin outer arc) and one row per limit with its reset time:
+
+```
+✳ Claude Limits          ($) (↻)
+        ╭─── 66% Used ───╮
+◔66  5-Hour Limit     Today 6:10 PM
+◔12  7-Day Limit         Sep 5 1 AM
+◔18  7-Day (Fable)       Sep 5 1 AM
+```
+
+Rings turn orange at 80% or when Anthropic reports elevated severity, and red with `!` at 100% — the session (5-hour) limit is the one that usually triggers "Too many requests".
+
+## How it works
+
+Claude Code stores its OAuth token in the macOS Keychain (service `Claude Code-credentials`). This app reads that token and polls the same official endpoint the Claude apps use (`api.anthropic.com/api/oauth/usage`) once a minute. The token is sent **only** to `api.anthropic.com` — nowhere else, nothing is logged or stored.
+
+Works on Pro and Max plans. Requires being signed in to Claude Code (`claude` → `/login`).
+
+## Install
+
+Requires macOS.
+
+### Homebrew
+
+```
+brew install tilbertbalaban/tap/claude-limits-bar
+```
+
+### uv / pipx (needs Python 3.9+)
+
+```
+uv tool install claude-limits-bar
+```
+
+(or `pipx install claude-limits-bar`)
+
+Then:
+
+```
+claude-limits-bar                # run the menu bar app
+claude-limits-bar autostart on   # start automatically at login (LaunchAgent)
+claude-limits-bar autostart off  # remove the login item
+claude-limits-bar status         # print current limits to the terminal
+```
+
+## Updating
+
+The app checks GitHub once a day and shows an **Update available** item in the menu when there's a newer version. To update:
+
+```
+brew upgrade claude-limits-bar        # Homebrew
+uv tool upgrade claude-limits-bar     # uv
+pipx upgrade claude-limits-bar        # pipx
+```
+
+Then quit the app from its menu and start it again (`claude-limits-bar`, or log out/in if you use `autostart on`).
+
+## Support
+
+If this app saves you from surprise rate limits, you can support development via the `$` button in the app or at [base.monobank.ua/tilbertbalaban](https://base.monobank.ua/tilbertbalaban).
+
+## Development
+
+```
+git clone https://github.com/TilbertBalaban/claude-limits-bar
+cd claude-limits-bar
+python3 -m unittest discover -s tests -v
+python3 -m claude_limits_bar.cli status
+```
+
+The data layer ([claude_limits_bar/limits.py](claude_limits_bar/limits.py)) is stdlib-only and fully unit-tested; only the menu bar shell ([claude_limits_bar/menubar.py](claude_limits_bar/menubar.py)) depends on PyObjC (AppKit).
+
+## Troubleshooting
+
+- **`✳ ?` in the menu bar** — open the menu for the reason: no credentials (sign in to Claude Code), an expired token (use Claude Code once — it refreshes the token itself), or no network.
+- **`Too many requests` still happens at <100%** — the API reports utilization rounded to whole percent and with a small delay; treat the orange ring as "wrap up what you're doing".

claude_limits_bar-1.2.0/README.md

@@ -0,0 +1,90 @@
+# claude-limits-bar
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](LICENSE)
+
+**Claude Code limits and their reset times, always visible in the macOS menu bar.**
+
+If you keep hitting *"Too many requests, please try again later"*, this shows you exactly how close you are to the limit and when it resets — before Claude Code cuts you off.
+
+The menu bar shows two ring gauges — the session (5-hour) limit in green and the 7-day limit in purple, percent used inside each — plus the countdown until the session limit resets:
+
+```
+◔66 ◔12  3h 26m
+```
+
+Click it for the full picture: a large donut for the session limit (weekly as a thin outer arc) and one row per limit with its reset time:
+
+```
+✳ Claude Limits          ($) (↻)
+        ╭─── 66% Used ───╮
+◔66  5-Hour Limit     Today 6:10 PM
+◔12  7-Day Limit         Sep 5 1 AM
+◔18  7-Day (Fable)       Sep 5 1 AM
+```
+
+Rings turn orange at 80% or when Anthropic reports elevated severity, and red with `!` at 100% — the session (5-hour) limit is the one that usually triggers "Too many requests".
+
+## How it works
+
+Claude Code stores its OAuth token in the macOS Keychain (service `Claude Code-credentials`). This app reads that token and polls the same official endpoint the Claude apps use (`api.anthropic.com/api/oauth/usage`) once a minute. The token is sent **only** to `api.anthropic.com` — nowhere else, nothing is logged or stored.
+
+Works on Pro and Max plans. Requires being signed in to Claude Code (`claude` → `/login`).
+
+## Install
+
+Requires macOS.
+
+### Homebrew
+
+```
+brew install tilbertbalaban/tap/claude-limits-bar
+```
+
+### uv / pipx (needs Python 3.9+)
+
+```
+uv tool install claude-limits-bar
+```
+
+(or `pipx install claude-limits-bar`)
+
+Then:
+
+```
+claude-limits-bar                # run the menu bar app
+claude-limits-bar autostart on   # start automatically at login (LaunchAgent)
+claude-limits-bar autostart off  # remove the login item
+claude-limits-bar status         # print current limits to the terminal
+```
+
+## Updating
+
+The app checks GitHub once a day and shows an **Update available** item in the menu when there's a newer version. To update:
+
+```
+brew upgrade claude-limits-bar        # Homebrew
+uv tool upgrade claude-limits-bar     # uv
+pipx upgrade claude-limits-bar        # pipx
+```
+
+Then quit the app from its menu and start it again (`claude-limits-bar`, or log out/in if you use `autostart on`).
+
+## Support
+
+If this app saves you from surprise rate limits, you can support development via the `$` button in the app or at [base.monobank.ua/tilbertbalaban](https://base.monobank.ua/tilbertbalaban).
+
+## Development
+
+```
+git clone https://github.com/TilbertBalaban/claude-limits-bar
+cd claude-limits-bar
+python3 -m unittest discover -s tests -v
+python3 -m claude_limits_bar.cli status
+```
+
+The data layer ([claude_limits_bar/limits.py](claude_limits_bar/limits.py)) is stdlib-only and fully unit-tested; only the menu bar shell ([claude_limits_bar/menubar.py](claude_limits_bar/menubar.py)) depends on PyObjC (AppKit).
+
+## Troubleshooting
+
+- **`✳ ?` in the menu bar** — open the menu for the reason: no credentials (sign in to Claude Code), an expired token (use Claude Code once — it refreshes the token itself), or no network.
+- **`Too many requests` still happens at <100%** — the API reports utilization rounded to whole percent and with a small delay; treat the orange ring as "wrap up what you're doing".

claude_limits_bar-1.2.0/claude_limits_bar/__init__.py

@@ -0,0 +1 @@
+VERSION = "1.2.0"

claude_limits_bar-1.2.0/claude_limits_bar/cli.py

@@ -0,0 +1,79 @@
+import argparse
+import plistlib
+import subprocess
+import sys
+from pathlib import Path
+
+from . import VERSION
+from .limits import (
+    CredentialsNotFound, TokenRejected, UsageRateLimited, get_limits, limit_line,
+)
+
+LAUNCH_AGENT = Path.home() / "Library" / "LaunchAgents" / "com.claude-limits-bar.plist"
+
+
+def cmd_status() -> int:
+    try:
+        limits = get_limits()
+    except CredentialsNotFound:
+        print("No Claude Code credentials found — run `claude` and sign in first.")
+        return 1
+    except TokenRejected:
+        print("Stored token was rejected — use Claude Code once so it refreshes the token.")
+        return 1
+    except UsageRateLimited:
+        print("The usage API is rate-limited right now — try again in a minute.")
+        return 1
+    if not limits:
+        print("No limits reported for this account.")
+        return 0
+    for limit in limits:
+        print(limit_line(limit))
+    return 0
+
+
+def cmd_autostart(state: str) -> int:
+    if state == "off":
+        if LAUNCH_AGENT.exists():
+            subprocess.run(["launchctl", "unload", str(LAUNCH_AGENT)], capture_output=True)
+            LAUNCH_AGENT.unlink()
+        print("Autostart disabled.")
+        return 0
+    executable = Path(sys.argv[0]).resolve()
+    plist = {
+        "Label": "com.claude-limits-bar",
+        "ProgramArguments": [str(executable)],
+        "RunAtLoad": True,
+    }
+    LAUNCH_AGENT.parent.mkdir(parents=True, exist_ok=True)
+    LAUNCH_AGENT.write_bytes(plistlib.dumps(plist))
+    subprocess.run(["launchctl", "unload", str(LAUNCH_AGENT)], capture_output=True)
+    subprocess.run(["launchctl", "load", str(LAUNCH_AGENT)], capture_output=True)
+    print("Autostart enabled (%s)." % LAUNCH_AGENT)
+    return 0
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        prog="claude-limits-bar",
+        description="Claude limits and reset times in the macOS menu bar.",
+    )
+    parser.add_argument("--version", action="version", version=VERSION)
+    sub = parser.add_subparsers(dest="command")
+    sub.add_parser("status", help="print current limits to the terminal")
+    autostart = sub.add_parser("autostart", help="start automatically at login")
+    autostart.add_argument("state", choices=["on", "off"])
+    args = parser.parse_args()
+
+    if args.command == "status":
+        return cmd_status()
+    if args.command == "autostart":
+        return cmd_autostart(args.state)
+
+    from .menubar import main as run_menubar
+    run_menubar()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

claude_limits_bar-1.2.0/claude_limits_bar/limits.py

@@ -0,0 +1,234 @@
+"""Read Claude Code OAuth credentials and fetch the account's rate limits.
+
+Standard library only, so everything here is unit-testable without a Mac GUI.
+"""
+
+import json
+import os
+import ssl
+import subprocess
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import List, Optional
+
+USAGE_URL = "https://api.anthropic.com/api/oauth/usage"
+KEYCHAIN_SERVICE = "Claude Code-credentials"
+CREDENTIALS_FILE = Path.home() / ".claude" / ".credentials.json"
+REQUEST_TIMEOUT = 15
+
+WARN_PERCENT = 80
+
+
+class CredentialsNotFound(Exception):
+    """No Claude Code OAuth token in the Keychain or ~/.claude/.credentials.json."""
+
+
+class TokenRejected(Exception):
+    """The API returned 401/403 — the stored token is expired or revoked."""
+
+
+class UsageRateLimited(Exception):
+    """The usage endpoint itself returned 429 — back off, keep last data."""
+
+
+@dataclass
+class Limit:
+    kind: str            # "session", "weekly_all", "weekly_scoped", ...
+    label: str           # human-readable, e.g. "Session (5h)"
+    percent: float
+    severity: str        # "normal" | anything else means Anthropic flags it
+    resets_at: Optional[datetime]
+    is_active: bool
+
+    @property
+    def exhausted(self) -> bool:
+        return self.percent >= 100
+
+    @property
+    def warning(self) -> bool:
+        return self.percent >= WARN_PERCENT or self.severity not in ("normal", "")
+
+
+def _read_keychain() -> Optional[str]:
+    try:
+        out = subprocess.run(
+            ["security", "find-generic-password", "-s", KEYCHAIN_SERVICE, "-w"],
+            capture_output=True, text=True, timeout=10,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return None
+    return out.stdout.strip() if out.returncode == 0 and out.stdout.strip() else None
+
+
+def _read_credentials_file() -> Optional[str]:
+    try:
+        return CREDENTIALS_FILE.read_text()
+    except OSError:
+        return None
+
+
+def get_access_token() -> str:
+    raw = _read_keychain() or _read_credentials_file()
+    if not raw:
+        raise CredentialsNotFound()
+    return parse_access_token(raw)
+
+
+def parse_access_token(raw: str) -> str:
+    try:
+        token = json.loads(raw).get("claudeAiOauth", {}).get("accessToken")
+    except (json.JSONDecodeError, AttributeError):
+        raise CredentialsNotFound()
+    if not token:
+        raise CredentialsNotFound()
+    return token
+
+
+def _ssl_context() -> ssl.SSLContext:
+    ctx = ssl.create_default_context()
+    if ctx.cert_store_stats().get("x509_ca"):
+        return ctx
+    # python.org macOS builds ship without a CA bundle unless the user ran
+    # "Install Certificates.command" — fall back to certifi or the system bundle.
+    try:
+        import certifi
+        return ssl.create_default_context(cafile=certifi.where())
+    except ImportError:
+        pass
+    if os.path.exists("/etc/ssl/cert.pem"):
+        return ssl.create_default_context(cafile="/etc/ssl/cert.pem")
+    return ctx
+
+
+def fetch_usage(token: str) -> dict:
+    req = urllib.request.Request(USAGE_URL, headers={
+        "Authorization": "Bearer " + token,
+        "anthropic-beta": "oauth-2025-04-20",
+        "Content-Type": "application/json",
+        "User-Agent": "claude-limits-bar",
+    })
+    try:
+        with urllib.request.urlopen(req, timeout=REQUEST_TIMEOUT, context=_ssl_context()) as resp:
+            return json.loads(resp.read().decode("utf-8"))
+    except urllib.error.HTTPError as e:
+        if e.code in (401, 403):
+            raise TokenRejected() from e
+        if e.code == 429:
+            raise UsageRateLimited() from e
+        raise
+
+
+def get_limits() -> List[Limit]:
+    return parse_limits(fetch_usage(get_access_token()))
+
+
+def parse_limits(data: dict) -> List[Limit]:
+    limits = []
+    for item in data.get("limits") or []:
+        resets_at = _parse_iso(item.get("resets_at"))
+        limits.append(Limit(
+            kind=item.get("kind") or "",
+            label=_label(item),
+            percent=float(item.get("percent") or 0),
+            severity=item.get("severity") or "normal",
+            resets_at=resets_at,
+            is_active=bool(item.get("is_active")),
+        ))
+    return limits
+
+
+def _label(item: dict) -> str:
+    kind = item.get("kind") or ""
+    if kind == "session":
+        return "5-Hour Limit"
+    if kind == "weekly_all":
+        return "7-Day Limit"
+    if kind == "weekly_scoped":
+        model = ((item.get("scope") or {}).get("model") or {}).get("display_name")
+        return "7-Day (%s)" % model if model else "7-Day (scoped)"
+    return kind.replace("_", " ").capitalize() or "Limit"
+
+
+def _parse_iso(value: Optional[str]) -> Optional[datetime]:
+    if not value:
+        return None
+    try:
+        return datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except ValueError:
+        return None
+
+
+# --- display helpers ---------------------------------------------------------
+
+def primary_limit(limits: List[Limit]) -> Optional[Limit]:
+    """What to show in the menu bar: the session limit by default (it is what
+    usually triggers "Too many requests"), unless another limit is worse and
+    already in warning territory."""
+    if not limits:
+        return None
+    session = next((l for l in limits if l.kind == "session"), None)
+    worst = max(limits, key=lambda l: l.percent)
+    if worst.warning and (session is None or worst.percent > session.percent):
+        return worst
+    return session or worst
+
+
+def time_until(resets_at: Optional[datetime], now: Optional[datetime] = None) -> str:
+    if resets_at is None:
+        return "?"
+    now = now or datetime.now(timezone.utc)
+    seconds = (resets_at - now).total_seconds()
+    if seconds <= 0:
+        return "now"
+    minutes = int(seconds // 60)
+    days, minutes = divmod(minutes, 1440)
+    hours, minutes = divmod(minutes, 60)
+    if days:
+        return "%dd %dh" % (days, hours)
+    if hours:
+        return "%dh %02dm" % (hours, minutes)
+    return "%dm" % max(minutes, 1)
+
+
+def local_reset_time(resets_at: Optional[datetime], now: Optional[datetime] = None) -> str:
+    if resets_at is None:
+        return "?"
+    now = (now or datetime.now(timezone.utc)).astimezone()
+    local = resets_at.astimezone()
+    if local.date() == now.date():
+        return local.strftime("%H:%M")
+    return local.strftime("%a %H:%M")
+
+
+def reset_label(resets_at: Optional[datetime], now: Optional[datetime] = None) -> str:
+    """Reset moment the way the menu rows show it: "Today 6:10 PM", "Sep 5 1 AM"."""
+    if resets_at is None:
+        return "?"
+    now_local = (now or datetime.now(timezone.utc)).astimezone()
+    local = resets_at.astimezone()
+    time_part = local.strftime("%-I %p") if local.minute == 0 else local.strftime("%-I:%M %p")
+    if local.date() == now_local.date():
+        return "Today " + time_part
+    return local.strftime("%b %-d ") + time_part
+
+
+def bar_title(limits: List[Limit], now: Optional[datetime] = None) -> str:
+    p = primary_limit(limits)
+    if p is None:
+        return "✳ ?"
+    if p.exhausted:
+        return "✳ ⛔ %s" % time_until(p.resets_at, now)
+    prefix = "✳ ⚠️ " if any(l.warning for l in limits) else "✳ "
+    return "%s%d%% · %s" % (prefix, round(p.percent), time_until(p.resets_at, now))
+
+
+def limit_line(limit: Limit, now: Optional[datetime] = None) -> str:
+    return "%s: %d%% — resets %s (in %s)" % (
+        limit.label,
+        round(limit.percent),
+        local_reset_time(limit.resets_at, now),
+        time_until(limit.resets_at, now),
+    )

claude_limits_bar-1.2.0/claude_limits_bar/menubar.py

@@ -0,0 +1,354 @@
+"""macOS menu bar app: ring gauges for Claude limits, reset times in the menu.
+
+Menu bar shows two mini rings (session + weekly, percent inside) plus the
+time until the 5-hour limit resets. The dropdown shows a large session donut
+with the weekly limit as a thin outer arc, and one row per limit.
+"""
+
+import threading
+import time
+import webbrowser
+
+import objc
+from AppKit import (
+    NSApplication, NSApplicationActivationPolicyAccessory,
+    NSAttributedString, NSBezierPath, NSButton, NSColor, NSFont,
+    NSFontAttributeName, NSForegroundColorAttributeName, NSImage, NSMakeRect,
+    NSMenu, NSMenuItem, NSMutableParagraphStyle, NSParagraphStyleAttributeName,
+    NSStatusBar, NSTextAlignmentCenter, NSTextAlignmentLeft,
+    NSTextAlignmentRight, NSVariableStatusItemLength, NSView,
+)
+from Foundation import NSObject, NSTimer
+from PyObjCTools import AppHelper
+
+from .limits import (
+    CredentialsNotFound, TokenRejected, UsageRateLimited,
+    get_limits, reset_label, time_until,
+)
+from .update import CHECK_INTERVAL_SECONDS, RELEASES_URL, available_update
+
+REFRESH_SECONDS = 60
+MENU_WIDTH = 264
+RATE_LIMIT_ERROR = "Usage API rate-limited — showing last known data"
+DONATE_URL = "https://base.monobank.ua/tilbertbalaban"
+USAGE_URL = "https://claude.ai/settings/usage"
+
+GREEN = NSColor.systemGreenColor()
+PURPLE = NSColor.systemPurpleColor()
+ORANGE = NSColor.systemOrangeColor()
+RED = NSColor.systemRedColor()
+
+
+def ring_color(limit):
+    if limit.exhausted:
+        return RED
+    if limit.warning:
+        return ORANGE
+    return GREEN if limit.kind == "session" else PURPLE
+
+
+def draw_ring(center, radius, line_width, percent, color, track_color):
+    track = NSBezierPath.bezierPath()
+    track.appendBezierPathWithArcWithCenter_radius_startAngle_endAngle_(
+        center, radius, 0, 360)
+    track.setLineWidth_(line_width)
+    track_color.setStroke()
+    track.stroke()
+    fraction = min(max(percent, 0), 100) / 100.0
+    if fraction <= 0:
+        return
+    arc = NSBezierPath.bezierPath()
+    # Start at 12 o'clock and sweep clockwise, like a countdown dial.
+    arc.appendBezierPathWithArcWithCenter_radius_startAngle_endAngle_clockwise_(
+        center, radius, 90, 90 - 360 * fraction, True)
+    arc.setLineWidth_(line_width)
+    arc.setLineCapStyle_(1)  # round
+    color.setStroke()
+    arc.stroke()
+
+
+def text_attrs(size, color, bold=False, align=NSTextAlignmentCenter):
+    style = NSMutableParagraphStyle.alloc().init()
+    style.setAlignment_(align)
+    font = NSFont.boldSystemFontOfSize_(size) if bold else NSFont.systemFontOfSize_(size)
+    return {
+        NSFontAttributeName: font,
+        NSForegroundColorAttributeName: color,
+        NSParagraphStyleAttributeName: style,
+    }
+
+
+def draw_text(text, rect, attrs):
+    s = NSAttributedString.alloc().initWithString_attributes_(text, attrs)
+    h = s.size().height
+    s.drawInRect_(NSMakeRect(rect.origin.x,
+                             rect.origin.y + (rect.size.height - h) / 2.0,
+                             rect.size.width, h))
+
+
+def status_bar_image(limits, dark):
+    """Two mini rings with the percent inside, like the reference app."""
+    size = 18
+    gap = 3
+    count = max(len(limits), 1)
+    img = NSImage.alloc().initWithSize_((count * size + (count - 1) * gap, 20))
+    img.lockFocus()
+    number_color = NSColor.whiteColor() if dark else NSColor.blackColor()
+    track = (NSColor.whiteColor() if dark else NSColor.blackColor()).colorWithAlphaComponent_(0.18)
+    for i, limit in enumerate(limits):
+        x = i * (size + gap)
+        center = (x + size / 2.0, 1 + size / 2.0)
+        draw_ring(center, size / 2.0 - 1.5, 2.5, limit.percent, ring_color(limit), track)
+        pct = round(limit.percent)
+        label = "!" if pct >= 100 else str(pct)
+        draw_text(label, NSMakeRect(x, 1, size, size),
+                  text_attrs(7.5, number_color, bold=True))
+    img.unlockFocus()
+    return img
+
+
+def _symbol_button(symbol, fallback, tooltip, target, action):
+    image = NSImage.imageWithSystemSymbolName_accessibilityDescription_(
+        symbol, tooltip)
+    if image is not None:
+        button = NSButton.buttonWithImage_target_action_(image, target, action)
+    else:
+        button = NSButton.buttonWithTitle_target_action_(fallback, target, action)
+    button.setBordered_(False)
+    button.setToolTip_(tooltip)
+    return button
+
+
+class HeaderView(NSView):
+    """App title with the donate ($) and refresh icon buttons on the right."""
+
+    def initWithTarget_(self, target):
+        self = objc.super(HeaderView, self).initWithFrame_(
+            NSMakeRect(0, 0, MENU_WIDTH, 38))
+        if self is None:
+            return None
+        stats = _symbol_button("chart.bar.xaxis", "📊",
+                               "Open claude.ai usage stats", target, "openUsage:")
+        stats.setFrame_(NSMakeRect(MENU_WIDTH - 100, 7, 26, 24))
+        self.addSubview_(stats)
+        donate = _symbol_button("dollarsign.circle", "$",
+                                "Support the developer", target, "donate:")
+        donate.setFrame_(NSMakeRect(MENU_WIDTH - 70, 7, 26, 24))
+        self.addSubview_(donate)
+        refresh = _symbol_button("arrow.clockwise", "↻",
+                                 "Refresh", target, "refresh:")
+        refresh.setFrame_(NSMakeRect(MENU_WIDTH - 40, 7, 26, 24))
+        self.addSubview_(refresh)
+        return self
+
+    def drawRect_(self, rect):
+        draw_text("✳ Claude Limits", NSMakeRect(16, 3, MENU_WIDTH - 120, 32),
+                  text_attrs(14, NSColor.labelColor(), bold=True,
+                             align=NSTextAlignmentLeft))
+
+
+class DonutView(NSView):
+    """Large session donut with the weekly limit as a thin outer arc."""
+
+    def initWithLimits_(self, limits):
+        self = objc.super(DonutView, self).initWithFrame_(
+            NSMakeRect(0, 0, MENU_WIDTH, 170))
+        if self is None:
+            return None
+        self._limits = limits
+        return self
+
+    def drawRect_(self, rect):
+        session = next((l for l in self._limits if l.kind == "session"), None)
+        weekly = next((l for l in self._limits if l.kind == "weekly_all"), None)
+        primary = session or (self._limits[0] if self._limits else None)
+        if primary is None:
+            return
+        center = (MENU_WIDTH / 2.0, 85)
+        track = NSColor.labelColor().colorWithAlphaComponent_(0.12)
+        draw_ring(center, 62, 11, primary.percent, ring_color(primary), track)
+        if weekly is not None:
+            draw_ring(center, 74, 3.5, weekly.percent, ring_color(weekly),
+                      NSColor.clearColor())
+        draw_text("%d%%" % round(primary.percent),
+                  NSMakeRect(0, 78, MENU_WIDTH, 40),
+                  text_attrs(28, NSColor.labelColor(), bold=True))
+        draw_text("Used", NSMakeRect(0, 54, MENU_WIDTH, 20),
+                  text_attrs(12, NSColor.secondaryLabelColor()))
+
+
+class LimitRowView(NSView):
+    """Mini ring + limit name + reset time, like the reference app's rows."""
+
+    def initWithLimit_(self, limit):
+        self = objc.super(LimitRowView, self).initWithFrame_(
+            NSMakeRect(0, 0, MENU_WIDTH, 36))
+        if self is None:
+            return None
+        self._limit = limit
+        return self
+
+    def drawRect_(self, rect):
+        bg = NSBezierPath.bezierPathWithRoundedRect_xRadius_yRadius_(
+            NSMakeRect(10, 2, MENU_WIDTH - 20, 32), 8, 8)
+        NSColor.labelColor().colorWithAlphaComponent_(0.06).setFill()
+        bg.fill()
+        limit = self._limit
+        track = NSColor.labelColor().colorWithAlphaComponent_(0.15)
+        draw_ring((20 + 9, 18), 7.5, 2.5, limit.percent, ring_color(limit), track)
+        pct = round(limit.percent)
+        draw_text("!" if pct >= 100 else str(pct), NSMakeRect(20, 9, 18, 18),
+                  text_attrs(6.5, NSColor.labelColor(), bold=True))
+        draw_text(limit.label, NSMakeRect(46, 2, 92, 32),
+                  text_attrs(13, NSColor.secondaryLabelColor(),
+                             align=NSTextAlignmentLeft))
+        draw_text(reset_label(limit.resets_at), NSMakeRect(120, 2, MENU_WIDTH - 136, 32),
+                  text_attrs(13, NSColor.labelColor(), bold=True,
+                             align=NSTextAlignmentRight))
+
+
+class ErrorRowView(NSView):
+    """Fixed-width warning row so long messages never widen the menu."""
+
+    def initWithMessage_(self, message):
+        self = objc.super(ErrorRowView, self).initWithFrame_(
+            NSMakeRect(0, 0, MENU_WIDTH, 34))
+        if self is None:
+            return None
+        self._message = message
+        return self
+
+    def drawRect_(self, rect):
+        attrs = text_attrs(11, NSColor.secondaryLabelColor(),
+                           align=NSTextAlignmentLeft)
+        NSAttributedString.alloc().initWithString_attributes_(
+            "⚠️ " + self._message, attrs).drawInRect_(
+            NSMakeRect(16, 2, MENU_WIDTH - 32, 30))
+
+
+class StatusApp(NSObject):
+    def applicationDidFinishLaunching_(self, _notification):
+        self._limits = []
+        self._error = None
+        self._skip_ticks = 0
+        self._update = None
+        self._last_update_check = 0.0
+        self.status_item = NSStatusBar.systemStatusBar().statusItemWithLength_(
+            NSVariableStatusItemLength)
+        self.status_item.button().setImagePosition_(2)  # NSImageLeft
+        self.menu = NSMenu.alloc().init()
+        self.status_item.setMenu_(self.menu)
+        self._render()
+        NSTimer.scheduledTimerWithTimeInterval_target_selector_userInfo_repeats_(
+            REFRESH_SECONDS, self, "tick:", None, True)
+        self.tick_(None)
+
+    def tick_(self, _timer):
+        if self._skip_ticks > 0:
+            self._skip_ticks -= 1
+            return
+        threading.Thread(target=self._fetch, daemon=True).start()
+
+    @objc.python_method
+    def _fetch(self):
+        if time.time() - self._last_update_check > CHECK_INTERVAL_SECONDS:
+            self._last_update_check = time.time()
+            self._update = available_update()
+        limits, error = None, None
+        try:
+            limits = get_limits()
+        except CredentialsNotFound:
+            error = "No Claude Code credentials — run `claude` and sign in"
+        except TokenRejected:
+            error = "Token expired — use Claude Code once to refresh it"
+        except UsageRateLimited:
+            error = RATE_LIMIT_ERROR
+        except Exception:
+            error = "Could not reach api.anthropic.com"
+        AppHelper.callAfter(self._apply, limits, error)
+
+    @objc.python_method
+    def _apply(self, limits, error):
+        if limits is not None:
+            self._limits = limits
+        self._error = error
+        # The usage endpoint has its own rate limit; poll gently after a 429.
+        self._skip_ticks = 4 if error == RATE_LIMIT_ERROR else 0
+        self._render()
+
+    @objc.python_method
+    def _render(self):
+        button = self.status_item.button()
+        bar_limits = [l for l in self._limits
+                      if l.kind in ("session", "weekly_all")] or self._limits[:2]
+        session = next((l for l in self._limits if l.kind == "session"), None)
+        if bar_limits:
+            dark = "dark" in str(button.effectiveAppearance().name()).lower()
+            button.setImage_(status_bar_image(bar_limits, dark))
+            button.setTitle_(" " + time_until(session.resets_at) if session else "")
+        else:
+            button.setImage_(None)
+            button.setTitle_("✳ …" if self._error is None else "✳ ?")
+        self._rebuild_menu()
+
+    @objc.python_method
+    def _rebuild_menu(self):
+        self.menu.removeAllItems()
+        header_item = NSMenuItem.alloc().init()
+        header_item.setView_(HeaderView.alloc().initWithTarget_(self))
+        self.menu.addItem_(header_item)
+        if self._limits:
+            donut_item = NSMenuItem.alloc().init()
+            donut_item.setView_(DonutView.alloc().initWithLimits_(self._limits))
+            self.menu.addItem_(donut_item)
+            for limit in self._limits:
+                row = NSMenuItem.alloc().init()
+                row.setView_(LimitRowView.alloc().initWithLimit_(limit))
+                self.menu.addItem_(row)
+        if self._error:
+            err = NSMenuItem.alloc().init()
+            err.setView_(ErrorRowView.alloc().initWithMessage_(self._error))
+            self.menu.addItem_(err)
+        if self._update:
+            self.menu.addItem_(NSMenuItem.separatorItem())
+            self._add_action("Update available — v" + self._update, "openReleases:")
+        self.menu.addItem_(NSMenuItem.separatorItem())
+        self._add_action("Quit", "quit:")
+
+    @objc.python_method
+    def _add_action(self, title, selector):
+        item = NSMenuItem.alloc().initWithTitle_action_keyEquivalent_(
+            title, selector, "")
+        item.setTarget_(self)
+        self.menu.addItem_(item)
+
+    def refresh_(self, _sender):
+        self._skip_ticks = 0
+        self.tick_(None)
+
+    def openUsage_(self, _sender):
+        self.menu.cancelTracking()
+        webbrowser.open(USAGE_URL)
+
+    def donate_(self, _sender):
+        self.menu.cancelTracking()
+        webbrowser.open(DONATE_URL)
+
+    def openReleases_(self, _sender):
+        self.menu.cancelTracking()
+        webbrowser.open(RELEASES_URL)
+
+    def quit_(self, _sender):
+        NSApplication.sharedApplication().terminate_(None)
+
+
+def main():
+    app = NSApplication.sharedApplication()
+    app.setActivationPolicy_(NSApplicationActivationPolicyAccessory)
+    delegate = StatusApp.alloc().init()
+    app.setDelegate_(delegate)
+    AppHelper.runEventLoop()
+
+
+if __name__ == "__main__":
+    main()

claude_limits_bar-1.2.0/claude_limits_bar/update.py

@@ -0,0 +1,40 @@
+"""Once-a-day check for a newer release on GitHub."""
+
+import json
+import urllib.request
+from typing import Optional
+
+from . import VERSION
+from .limits import _ssl_context
+
+RELEASES_API = ("https://api.github.com/repos/"
+                "TilbertBalaban/claude-limits-bar/releases/latest")
+RELEASES_URL = "https://github.com/TilbertBalaban/claude-limits-bar/releases"
+CHECK_INTERVAL_SECONDS = 24 * 3600
+
+
+def latest_version(timeout: int = 10) -> Optional[str]:
+    req = urllib.request.Request(RELEASES_API, headers={
+        "User-Agent": "claude-limits-bar",
+        "Accept": "application/vnd.github+json",
+    })
+    with urllib.request.urlopen(req, timeout=timeout, context=_ssl_context()) as resp:
+        tag = json.loads(resp.read().decode("utf-8")).get("tag_name") or ""
+    return tag.lstrip("v") or None
+
+
+def is_newer(candidate: Optional[str], current: str = VERSION) -> bool:
+    try:
+        parse = lambda v: tuple(int(part) for part in v.split("."))
+        return parse(candidate) > parse(current)
+    except (AttributeError, ValueError):
+        return False
+
+
+def available_update() -> Optional[str]:
+    """Version string of a newer release, or None. Never raises."""
+    try:
+        latest = latest_version()
+    except Exception:
+        return None
+    return latest if is_newer(latest) else None

claude_limits_bar-1.2.0/claude_limits_bar.egg-info/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: claude-limits-bar
+Version: 1.2.0
+Summary: Claude Code limits and reset times in the macOS menu bar
+Author: Tilbert Balaban
+License: MIT
+Project-URL: Homepage, https://github.com/TilbertBalaban/claude-limits-bar
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyobjc-framework-Cocoa>=9.0
+Requires-Dist: certifi
+Dynamic: license-file
+
+# claude-limits-bar
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](LICENSE)
+
+**Claude Code limits and their reset times, always visible in the macOS menu bar.**
+
+If you keep hitting *"Too many requests, please try again later"*, this shows you exactly how close you are to the limit and when it resets — before Claude Code cuts you off.
+
+The menu bar shows two ring gauges — the session (5-hour) limit in green and the 7-day limit in purple, percent used inside each — plus the countdown until the session limit resets:
+
+```
+◔66 ◔12  3h 26m
+```
+
+Click it for the full picture: a large donut for the session limit (weekly as a thin outer arc) and one row per limit with its reset time:
+
+```
+✳ Claude Limits          ($) (↻)
+        ╭─── 66% Used ───╮
+◔66  5-Hour Limit     Today 6:10 PM
+◔12  7-Day Limit         Sep 5 1 AM
+◔18  7-Day (Fable)       Sep 5 1 AM
+```
+
+Rings turn orange at 80% or when Anthropic reports elevated severity, and red with `!` at 100% — the session (5-hour) limit is the one that usually triggers "Too many requests".
+
+## How it works
+
+Claude Code stores its OAuth token in the macOS Keychain (service `Claude Code-credentials`). This app reads that token and polls the same official endpoint the Claude apps use (`api.anthropic.com/api/oauth/usage`) once a minute. The token is sent **only** to `api.anthropic.com` — nowhere else, nothing is logged or stored.
+
+Works on Pro and Max plans. Requires being signed in to Claude Code (`claude` → `/login`).
+
+## Install
+
+Requires macOS.
+
+### Homebrew
+
+```
+brew install tilbertbalaban/tap/claude-limits-bar
+```
+
+### uv / pipx (needs Python 3.9+)
+
+```
+uv tool install claude-limits-bar
+```
+
+(or `pipx install claude-limits-bar`)
+
+Then:
+
+```
+claude-limits-bar                # run the menu bar app
+claude-limits-bar autostart on   # start automatically at login (LaunchAgent)
+claude-limits-bar autostart off  # remove the login item
+claude-limits-bar status         # print current limits to the terminal
+```
+
+## Updating
+
+The app checks GitHub once a day and shows an **Update available** item in the menu when there's a newer version. To update:
+
+```
+brew upgrade claude-limits-bar        # Homebrew
+uv tool upgrade claude-limits-bar     # uv
+pipx upgrade claude-limits-bar        # pipx
+```
+
+Then quit the app from its menu and start it again (`claude-limits-bar`, or log out/in if you use `autostart on`).
+
+## Support
+
+If this app saves you from surprise rate limits, you can support development via the `$` button in the app or at [base.monobank.ua/tilbertbalaban](https://base.monobank.ua/tilbertbalaban).
+
+## Development
+
+```
+git clone https://github.com/TilbertBalaban/claude-limits-bar
+cd claude-limits-bar
+python3 -m unittest discover -s tests -v
+python3 -m claude_limits_bar.cli status
+```
+
+The data layer ([claude_limits_bar/limits.py](claude_limits_bar/limits.py)) is stdlib-only and fully unit-tested; only the menu bar shell ([claude_limits_bar/menubar.py](claude_limits_bar/menubar.py)) depends on PyObjC (AppKit).
+
+## Troubleshooting
+
+- **`✳ ?` in the menu bar** — open the menu for the reason: no credentials (sign in to Claude Code), an expired token (use Claude Code once — it refreshes the token itself), or no network.
+- **`Too many requests` still happens at <100%** — the API reports utilization rounded to whole percent and with a small delay; treat the orange ring as "wrap up what you're doing".

claude_limits_bar-1.2.0/claude_limits_bar.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+README.md
+pyproject.toml
+claude_limits_bar/__init__.py
+claude_limits_bar/cli.py
+claude_limits_bar/limits.py
+claude_limits_bar/menubar.py
+claude_limits_bar/update.py
+claude_limits_bar.egg-info/PKG-INFO
+claude_limits_bar.egg-info/SOURCES.txt
+claude_limits_bar.egg-info/dependency_links.txt
+claude_limits_bar.egg-info/entry_points.txt
+claude_limits_bar.egg-info/requires.txt
+claude_limits_bar.egg-info/top_level.txt
+tests/test_limits.py
+tests/test_update.py

claude_limits_bar-1.2.0/claude_limits_bar.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

claude_limits_bar-1.2.0/claude_limits_bar.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+claude-limits-bar = claude_limits_bar.cli:main

claude_limits_bar-1.2.0/claude_limits_bar.egg-info/requires.txt

@@ -0,0 +1,2 @@
+pyobjc-framework-Cocoa>=9.0
+certifi

claude_limits_bar-1.2.0/claude_limits_bar.egg-info/top_level.txt

@@ -0,0 +1 @@
+claude_limits_bar

claude_limits_bar-1.2.0/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "claude-limits-bar"
+version = "1.2.0"
+description = "Claude Code limits and reset times in the macOS menu bar"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "Tilbert Balaban" }]
+requires-python = ">=3.9"
+dependencies = ["pyobjc-framework-Cocoa>=9.0", "certifi"]
+
+[project.urls]
+Homepage = "https://github.com/TilbertBalaban/claude-limits-bar"
+
+[project.scripts]
+claude-limits-bar = "claude_limits_bar.cli:main"
+
+[tool.setuptools]
+packages = ["claude_limits_bar"]

claude_limits_bar-1.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

claude_limits_bar-1.2.0/tests/test_limits.py

@@ -0,0 +1,126 @@
+import unittest
+from datetime import datetime, timedelta, timezone
+
+from claude_limits_bar.limits import (
+    CredentialsNotFound, Limit,
+    bar_title, limit_line, local_reset_time, parse_access_token,
+    parse_limits, primary_limit, reset_label, time_until,
+)
+
+NOW = datetime(2026, 9, 2, 12, 30, tzinfo=timezone.utc)
+
+SAMPLE_RESPONSE = {
+    "limits": [
+        {"kind": "session", "group": "session", "percent": 41, "severity": "normal",
+         "resets_at": "2026-09-02T15:10:00.026681+00:00", "scope": None, "is_active": True},
+        {"kind": "weekly_all", "group": "weekly", "percent": 9, "severity": "normal",
+         "resets_at": "2026-09-04T22:00:00.026699+00:00", "scope": None, "is_active": False},
+        {"kind": "weekly_scoped", "group": "weekly", "percent": 13, "severity": "normal",
+         "resets_at": "2026-09-04T22:00:00.026844+00:00",
+         "scope": {"model": {"id": None, "display_name": "Fable"}, "surface": None},
+         "is_active": False},
+    ],
+}
+
+
+def make_limit(kind="session", label="5-Hour Limit", percent=41.0, severity="normal",
+               resets_at=NOW + timedelta(hours=2, minutes=40), is_active=True):
+    return Limit(kind=kind, label=label, percent=percent, severity=severity,
+                 resets_at=resets_at, is_active=is_active)
+
+
+class TestParseAccessToken(unittest.TestCase):
+    def test_valid(self):
+        raw = '{"claudeAiOauth": {"accessToken": "sk-ant-oat01-abc"}}'
+        self.assertEqual(parse_access_token(raw), "sk-ant-oat01-abc")
+
+    def test_missing_token(self):
+        with self.assertRaises(CredentialsNotFound):
+            parse_access_token('{"claudeAiOauth": {}}')
+
+    def test_invalid_json(self):
+        with self.assertRaises(CredentialsNotFound):
+            parse_access_token("not json")
+
+
+class TestParseLimits(unittest.TestCase):
+    def test_sample_response(self):
+        limits = parse_limits(SAMPLE_RESPONSE)
+        self.assertEqual(len(limits), 3)
+        session, weekly, scoped = limits
+        self.assertEqual(session.label, "5-Hour Limit")
+        self.assertEqual(session.percent, 41)
+        self.assertTrue(session.is_active)
+        self.assertEqual(session.resets_at.tzinfo.utcoffset(None), timedelta(0))
+        self.assertEqual(weekly.label, "7-Day Limit")
+        self.assertEqual(scoped.label, "7-Day (Fable)")
+
+    def test_empty_and_missing(self):
+        self.assertEqual(parse_limits({}), [])
+        self.assertEqual(parse_limits({"limits": None}), [])
+
+    def test_unknown_kind_gets_readable_label(self):
+        limits = parse_limits({"limits": [{"kind": "weekly_opus", "percent": 5}]})
+        self.assertEqual(limits[0].label, "Weekly opus")
+        self.assertIsNone(limits[0].resets_at)
+
+
+class TestPrimaryLimit(unittest.TestCase):
+    def test_prefers_session(self):
+        session = make_limit(percent=20)
+        weekly = make_limit(kind="weekly_all", label="7-Day Limit", percent=50)
+        self.assertIs(primary_limit([weekly, session]), session)
+
+    def test_worse_limit_wins_when_warning(self):
+        session = make_limit(percent=20)
+        weekly = make_limit(kind="weekly_all", label="7-Day Limit", percent=85)
+        self.assertIs(primary_limit([session, weekly]), weekly)
+
+    def test_no_limits(self):
+        self.assertIsNone(primary_limit([]))
+
+
+class TestTimeFormatting(unittest.TestCase):
+    def test_time_until(self):
+        self.assertEqual(time_until(NOW + timedelta(hours=2, minutes=40), NOW), "2h 40m")
+        self.assertEqual(time_until(NOW + timedelta(minutes=5), NOW), "5m")
+        self.assertEqual(time_until(NOW + timedelta(days=2, hours=9, minutes=30), NOW), "2d 9h")
+        self.assertEqual(time_until(NOW - timedelta(minutes=1), NOW), "now")
+        self.assertEqual(time_until(None, NOW), "?")
+
+    def test_local_reset_time_same_day_has_no_weekday(self):
+        self.assertNotIn(" ", local_reset_time(NOW + timedelta(hours=1), NOW))
+        self.assertIn(" ", local_reset_time(NOW + timedelta(days=2), NOW))
+
+    def test_reset_label(self):
+        same_day = NOW.astimezone().replace(hour=18, minute=10)
+        self.assertEqual(reset_label(same_day, NOW), "Today 6:10 PM")
+        other_day = datetime(2026, 9, 5, 1, 0, tzinfo=NOW.astimezone().tzinfo)
+        label = reset_label(other_day, NOW)
+        self.assertEqual(label, "Sep 5 1 AM")
+        self.assertEqual(reset_label(None, NOW), "?")
+
+
+class TestBarTitle(unittest.TestCase):
+    def test_normal(self):
+        self.assertEqual(bar_title([make_limit()], NOW), "✳ 41% · 2h 40m")
+
+    def test_warning(self):
+        self.assertEqual(bar_title([make_limit(percent=85)], NOW), "✳ ⚠️ 85% · 2h 40m")
+
+    def test_exhausted_shows_time_to_reset(self):
+        self.assertEqual(bar_title([make_limit(percent=100)], NOW), "✳ ⛔ 2h 40m")
+
+    def test_no_data(self):
+        self.assertEqual(bar_title([], NOW), "✳ ?")
+
+
+class TestLimitLine(unittest.TestCase):
+    def test_contains_label_percent_and_countdown(self):
+        line = limit_line(make_limit(), NOW)
+        self.assertIn("5-Hour Limit: 41%", line)
+        self.assertIn("in 2h 40m", line)
+
+
+if __name__ == "__main__":
+    unittest.main()

claude_limits_bar-1.2.0/tests/test_update.py

@@ -0,0 +1,23 @@
+import unittest
+
+from claude_limits_bar.update import is_newer
+
+
+class TestIsNewer(unittest.TestCase):
+    def test_newer(self):
+        self.assertTrue(is_newer("1.1.0", "1.0.5"))
+        self.assertTrue(is_newer("2.0.0", "1.9.9"))
+        self.assertTrue(is_newer("1.0.10", "1.0.9"))
+
+    def test_not_newer(self):
+        self.assertFalse(is_newer("1.0.5", "1.0.5"))
+        self.assertFalse(is_newer("1.0.4", "1.0.5"))
+
+    def test_garbage(self):
+        self.assertFalse(is_newer(None, "1.0.5"))
+        self.assertFalse(is_newer("", "1.0.5"))
+        self.assertFalse(is_newer("not-a-version", "1.0.5"))
+
+
+if __name__ == "__main__":
+    unittest.main()