ccusage 0.3.0__tar.gz → 0.4.0__tar.gz

ccusage-0.4.0/.gitignore

@@ -0,0 +1,4 @@
+__pycache__/
+.venv/
+dist/
+dist-wrappers/

{ccusage-0.3.0 → ccusage-0.4.0}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 wakamex
+Copyright (c) 2026 Mihai
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

ccusage-0.4.0/PKG-INFO

@@ -0,0 +1,25 @@
+Metadata-Version: 2.5
+Name: ccusage
+Version: 0.4.0
+Summary: Claude Code usage limit monitor
+Project-URL: Homepage, https://github.com/wakamex/clanker-usage
+Project-URL: Source, https://github.com/wakamex/clanker-usage
+License-Expression: MIT
+License-File: LICENSE
+Keywords: anthropic,claude,claude-code,cli,rate-limits,statusline,usage
+Requires-Python: >=3.12
+Requires-Dist: clanker-usage==0.4.0
+Description-Content-Type: text/markdown
+
+# ccusage
+
+Monitor your Claude Code quota from the terminal: current usage, a one-line statusline, and a daemon that keeps a cache fresh.
+
+```sh
+uv tool install ccusage
+ccusage              # current quotas
+ccusage statusline   # one line, from a cache less than five minutes old
+ccusage json         # the usage-v1 document
+```
+
+`ccusage` is the Claude Code command of [clanker-usage](https://github.com/wakamex/clanker-usage), so it installs clanker-usage at the same version. The documentation lives there.

ccusage-0.4.0/README.md

@@ -0,0 +1,12 @@
+# ccusage
+
+Monitor your Claude Code quota from the terminal: current usage, a one-line statusline, and a daemon that keeps a cache fresh.
+
+```sh
+uv tool install ccusage
+ccusage              # current quotas
+ccusage statusline   # one line, from a cache less than five minutes old
+ccusage json         # the usage-v1 document
+```
+
+`ccusage` is the Claude Code command of [clanker-usage](https://github.com/wakamex/clanker-usage), so it installs clanker-usage at the same version. The documentation lives there.

ccusage-0.4.0/ccusage/__init__.py

@@ -0,0 +1,7 @@
+"""ccusage: the Claude Code command of clanker-usage."""
+
+from clanker_usage import run
+
+
+def main():
+    return run("claude")

ccusage-0.4.0/ccusage/__main__.py

@@ -0,0 +1,3 @@
+from . import main
+
+raise SystemExit(main())

ccusage-0.4.0/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["hatchling==1.32.4"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ccusage"
+version = "0.4.0"
+description = "Claude Code usage limit monitor"
+readme = "README.md"
+keywords = ["claude", "claude-code", "anthropic", "usage", "rate-limits", "statusline", "cli"]
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+dependencies = ["clanker-usage==0.4.0"]
+
+[project.urls]
+Homepage = "https://github.com/wakamex/clanker-usage"
+Source = "https://github.com/wakamex/clanker-usage"
+
+[project.scripts]
+ccusage = "ccusage:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["ccusage"]

ccusage-0.3.0/.github/workflows/publish.yml

@@ -1,29 +0,0 @@
-name: Publish to PyPI
-
-on:
-  push:
-    tags: ["v*"]
-
-permissions:
-  contents: read
-
-jobs:
-  validate:
-    uses: wakamex/release-actions/.github/workflows/python-validation.yml@stable
-
-  publish:
-    needs: validate
-    runs-on: ubuntu-24.04
-    environment: pypi
-    permissions:
-      contents: read
-      id-token: write
-    steps:
-      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-      - uses: wakamex/release-actions/pypi-publish@stable
-
-  github-release:
-    needs: publish
-    permissions:
-      contents: write
-    uses: wakamex/release-actions/.github/workflows/github-release.yml@stable

ccusage-0.3.0/.github/workflows/release-eligibility.yml

@@ -1,12 +0,0 @@
-name: Release eligibility
-
-on:
-  push:
-    branches: [main]
-
-permissions:
-  contents: read
-
-jobs:
-  release-eligible:
-    uses: wakamex/release-actions/.github/workflows/python-validation.yml@stable

ccusage-0.3.0/.gitignore

@@ -1,10 +0,0 @@
-# Python-generated files
-__pycache__/
-*.py[oc]
-build/
-dist/
-wheels/
-*.egg-info
-
-# Virtual environments
-.venv

ccusage-0.3.0/.python-version

@@ -1 +0,0 @@
-3.13

ccusage-0.3.0/PKG-INFO

@@ -1,196 +0,0 @@
-Metadata-Version: 2.5
-Name: ccusage
-Version: 0.3.0
-Summary: Claude Code usage monitor — fetches rate limits from Anthropic's API
-Project-URL: Homepage, https://github.com/wakamex/ccusage
-Project-URL: Source, https://github.com/wakamex/ccusage
-License-Expression: MIT
-License-File: LICENSE
-Requires-Python: >=3.12
-Description-Content-Type: text/markdown
-
-# ccusage
-
-Claude Code usage monitor. Fetches your real rate limit data from Anthropic's API and displays it in the Claude Code statusline.
-
-## Example output
-
-`ccusage` command:
-
-```
-Plan: max_5x
-  Session              39%  resets 1h26m
-  Week (all)           15%  resets 143h26m
-  Week (Sonnet)        39%  resets 65h26m
-  Extra usage          $0.00 / $1000.00
-```
-
-Claude Code statusline (self-caching — refreshes from API when stale, no daemon needed):
-
-```
-~/projects/myapp [Opus 4.6] sess:39% 7d:15% son:39% | $1.37 | max_5x | reset:1h26m
-```
-
-## Install
-
-```bash
-uv tool install ccusage
-```
-
-Then run:
-
-```bash
-# Check usage once
-ccusage
-
-# Run the daemon (keeps usage-limits.json updated)
-ccusage daemon
-```
-
-Configure the statusline in `~/.claude/settings.json`:
-
-```json
-{
-  "statusLine": {
-    "type": "command",
-    "command": "ccusage statusline"
-  }
-}
-```
-
-If Claude Code uses `CLAUDE_CONFIG_DIR`, ccusage reads credentials and writes
-`usage-limits.json` in that directory instead.
-
-Each refresh also saves a copy under `usage-limits/<account uuid>.json`, tagged with the logged-in account's UUID and email from Claude Code's `.claude.json`. If you switch between Claude accounts with `/login`, the account you logged out of keeps its last usage there. An idle account cannot use quota, so that snapshot stays accurate until its windows reset.
-
-To keep a second account current while you are logged into another, give it its own config directory with a permanent login, run a second daemon there with `CLAUDE_CONFIG_DIR` set, and symlink that directory's `usage-limits` folder to the main one so both daemons share their snapshots. Start that daemon with `--defer`: it then skips a refresh whenever another daemon saved the same account's snapshot within the last one and a half intervals, so an account logged in under two config directories is polled once.
-
-## Commands
-
-| Command | Description |
-|---------|-------------|
-| `ccusage` | Show current usage (colored terminal output) |
-| `ccusage json` | Print raw JSON |
-| `ccusage daemon [-i SECS] [--defer]` | Run in foreground, refresh every 5 min (customizable) |
-| `ccusage statusline` | Claude Code statusline (self-caching, no daemon needed) |
-| `ccusage install` | Print setup instructions |
-
-## How Claude Code rate limiting works
-
-Discovered by inspecting Claude Code's bundled `cli.js` (v2.1.32).
-
-### Data sources
-
-Claude Code gets rate limit data from two places:
-
-1. **`/api/oauth/usage` endpoint** — Called by the `/status` slash command. Returns utilization percentages and reset times for each rate limit bucket. Requires the `anthropic-beta: oauth-2025-04-20` header.
-
-2. **Response headers on every API call** — Every message response includes headers like:
-   - `anthropic-ratelimit-unified-{claim}-utilization` (0-100 float)
-   - `anthropic-ratelimit-unified-{claim}-reset` (unix timestamp)
-   - `anthropic-ratelimit-unified-status` (`allowed` / `allowed_warning` / `rejected`)
-   - `anthropic-ratelimit-unified-fallback` (`available` when fallback models are available)
-   - `anthropic-ratelimit-unified-overage-status` / `overage-reset`
-   - `anthropic-ratelimit-unified-representative-claim`
-
-### Rate limit types
-
-| Type | Key in API response | Description |
-|------|-------------------|-------------|
-| `five_hour` | `five_hour` | Rolling 5-hour session window |
-| `seven_day` | `seven_day` | Rolling 7-day all-models window |
-| `seven_day_sonnet` | `seven_day_sonnet` | Rolling 7-day Sonnet-specific window |
-| `seven_day_opus` | `seven_day_opus` | Rolling 7-day Opus-specific window |
-| `overage` | `extra_usage` | Extra/overage usage (if enabled) |
-
-The flat `seven_day_*` keys above are all `null` now — the live quota data
-lives in a structured `limits` array, which ccusage reads. Each entry is
-self-describing: `kind` (`session` / `weekly_all` / `weekly_scoped`),
-`percent`, `resets_at`, and for scoped limits a `scope.model.display_name`.
-Because the structured response does not include a session duration, ccusage
-labels that limit `Session` and caches it under `session` rather than assuming
-it is always five hours. Existing `5h` cache files remain readable.
-Model-scoped weekly windows (Opus, Sonnet, and a newly added **Fable**) are
-keyed by their model name, so any new one is auto-detected and displayed with
-no code change (e.g. `scope.model.display_name: "Fable"` → "Week (Fable)",
-statusline `fab:`).
-
-### API response format
-
-```
-GET https://api.anthropic.com/api/oauth/usage
-Authorization: Bearer <oauth_access_token>
-anthropic-beta: oauth-2025-04-20
-```
-
-```json
-{
-    "five_hour": {
-        "utilization": 35.0,
-        "resets_at": "2026-02-06T22:00:00+00:00"
-    },
-    "seven_day": {
-        "utilization": 14.0,
-        "resets_at": "2026-02-12T20:00:00+00:00"
-    },
-    "seven_day_sonnet": {
-        "utilization": 39.0,
-        "resets_at": "2026-02-09T14:00:00+00:00"
-    },
-    "seven_day_opus": null,
-    "seven_day_oauth_apps": null,
-    "seven_day_cowork": null,
-    "iguana_necktie": null,
-    "extra_usage": {
-        "is_enabled": true,
-        "monthly_limit": 100000,
-        "used_credits": 0.0,
-        "utilization": null
-    }
-}
-```
-
-### Authentication
-
-The OAuth token normally lives at `~/.claude/.credentials.json`, or under
-`CLAUDE_CONFIG_DIR` when that environment variable is set:
-
-```json
-{
-    "claudeAiOauth": {
-        "accessToken": "sk-ant-oat01-...",
-        "refreshToken": "sk-ant-ort01-...",
-        "expiresAt": 1770412938485,
-        "subscriptionType": "team",
-        "rateLimitTier": "default_claude_max_5x"
-    }
-}
-```
-
-The access token expires roughly hourly. When it's expired (or rejected with a 401/403), ccusage refreshes it itself using the `refreshToken` and writes the rotated credentials back to `.credentials.json` — the same flow Claude Code uses, so the two stay in sync and no active Claude Code session is needed.
-
-### Warning thresholds (from cli.js)
-
-Claude Code shows inline warnings based on these thresholds:
-
-```
-five_hour:  90% utilization when 72% of window has passed
-seven_day:  75% at 60%, 50% at 35%, 25% at 15%
-```
-
-### Other endpoints found in cli.js
-
-- `/api/oauth/profile` — User profile
-- `/api/oauth/account/settings` — Account settings
-- `/api/claude_code/policy_limits` — Org policy limits (needs `organizationUuid`)
-- `/api/organization/claude_code_first_token_date` — Org onboarding date
-
-### Local files Claude Code uses
-
-| File | Written by | Contains |
-|------|-----------|----------|
-| `~/.claude/.credentials.json` | Claude Code | OAuth tokens, plan tier |
-| `~/.claude/stats-cache.json` | Claude Code | Local usage stats (message counts, token counts per model) |
-| `~/.claude/usage-limits.json` | ccusage daemon | Cached API usage data (this tool) |
-| `~/.claude/usage-limits/<account uuid>.json` | ccusage daemon | Last usage seen for each Claude account (this tool) |
-| `~/.claude/statsig/` | Claude Code | Feature flags, experiment assignments |

ccusage-0.3.0/README.md

@@ -1,185 +0,0 @@
-# ccusage
-
-Claude Code usage monitor. Fetches your real rate limit data from Anthropic's API and displays it in the Claude Code statusline.
-
-## Example output
-
-`ccusage` command:
-
-```
-Plan: max_5x
-  Session              39%  resets 1h26m
-  Week (all)           15%  resets 143h26m
-  Week (Sonnet)        39%  resets 65h26m
-  Extra usage          $0.00 / $1000.00
-```
-
-Claude Code statusline (self-caching — refreshes from API when stale, no daemon needed):
-
-```
-~/projects/myapp [Opus 4.6] sess:39% 7d:15% son:39% | $1.37 | max_5x | reset:1h26m
-```
-
-## Install
-
-```bash
-uv tool install ccusage
-```
-
-Then run:
-
-```bash
-# Check usage once
-ccusage
-
-# Run the daemon (keeps usage-limits.json updated)
-ccusage daemon
-```
-
-Configure the statusline in `~/.claude/settings.json`:
-
-```json
-{
-  "statusLine": {
-    "type": "command",
-    "command": "ccusage statusline"
-  }
-}
-```
-
-If Claude Code uses `CLAUDE_CONFIG_DIR`, ccusage reads credentials and writes
-`usage-limits.json` in that directory instead.
-
-Each refresh also saves a copy under `usage-limits/<account uuid>.json`, tagged with the logged-in account's UUID and email from Claude Code's `.claude.json`. If you switch between Claude accounts with `/login`, the account you logged out of keeps its last usage there. An idle account cannot use quota, so that snapshot stays accurate until its windows reset.
-
-To keep a second account current while you are logged into another, give it its own config directory with a permanent login, run a second daemon there with `CLAUDE_CONFIG_DIR` set, and symlink that directory's `usage-limits` folder to the main one so both daemons share their snapshots. Start that daemon with `--defer`: it then skips a refresh whenever another daemon saved the same account's snapshot within the last one and a half intervals, so an account logged in under two config directories is polled once.
-
-## Commands
-
-| Command | Description |
-|---------|-------------|
-| `ccusage` | Show current usage (colored terminal output) |
-| `ccusage json` | Print raw JSON |
-| `ccusage daemon [-i SECS] [--defer]` | Run in foreground, refresh every 5 min (customizable) |
-| `ccusage statusline` | Claude Code statusline (self-caching, no daemon needed) |
-| `ccusage install` | Print setup instructions |
-
-## How Claude Code rate limiting works
-
-Discovered by inspecting Claude Code's bundled `cli.js` (v2.1.32).
-
-### Data sources
-
-Claude Code gets rate limit data from two places:
-
-1. **`/api/oauth/usage` endpoint** — Called by the `/status` slash command. Returns utilization percentages and reset times for each rate limit bucket. Requires the `anthropic-beta: oauth-2025-04-20` header.
-
-2. **Response headers on every API call** — Every message response includes headers like:
-   - `anthropic-ratelimit-unified-{claim}-utilization` (0-100 float)
-   - `anthropic-ratelimit-unified-{claim}-reset` (unix timestamp)
-   - `anthropic-ratelimit-unified-status` (`allowed` / `allowed_warning` / `rejected`)
-   - `anthropic-ratelimit-unified-fallback` (`available` when fallback models are available)
-   - `anthropic-ratelimit-unified-overage-status` / `overage-reset`
-   - `anthropic-ratelimit-unified-representative-claim`
-
-### Rate limit types
-
-| Type | Key in API response | Description |
-|------|-------------------|-------------|
-| `five_hour` | `five_hour` | Rolling 5-hour session window |
-| `seven_day` | `seven_day` | Rolling 7-day all-models window |
-| `seven_day_sonnet` | `seven_day_sonnet` | Rolling 7-day Sonnet-specific window |
-| `seven_day_opus` | `seven_day_opus` | Rolling 7-day Opus-specific window |
-| `overage` | `extra_usage` | Extra/overage usage (if enabled) |
-
-The flat `seven_day_*` keys above are all `null` now — the live quota data
-lives in a structured `limits` array, which ccusage reads. Each entry is
-self-describing: `kind` (`session` / `weekly_all` / `weekly_scoped`),
-`percent`, `resets_at`, and for scoped limits a `scope.model.display_name`.
-Because the structured response does not include a session duration, ccusage
-labels that limit `Session` and caches it under `session` rather than assuming
-it is always five hours. Existing `5h` cache files remain readable.
-Model-scoped weekly windows (Opus, Sonnet, and a newly added **Fable**) are
-keyed by their model name, so any new one is auto-detected and displayed with
-no code change (e.g. `scope.model.display_name: "Fable"` → "Week (Fable)",
-statusline `fab:`).
-
-### API response format
-
-```
-GET https://api.anthropic.com/api/oauth/usage
-Authorization: Bearer <oauth_access_token>
-anthropic-beta: oauth-2025-04-20
-```
-
-```json
-{
-    "five_hour": {
-        "utilization": 35.0,
-        "resets_at": "2026-02-06T22:00:00+00:00"
-    },
-    "seven_day": {
-        "utilization": 14.0,
-        "resets_at": "2026-02-12T20:00:00+00:00"
-    },
-    "seven_day_sonnet": {
-        "utilization": 39.0,
-        "resets_at": "2026-02-09T14:00:00+00:00"
-    },
-    "seven_day_opus": null,
-    "seven_day_oauth_apps": null,
-    "seven_day_cowork": null,
-    "iguana_necktie": null,
-    "extra_usage": {
-        "is_enabled": true,
-        "monthly_limit": 100000,
-        "used_credits": 0.0,
-        "utilization": null
-    }
-}
-```
-
-### Authentication
-
-The OAuth token normally lives at `~/.claude/.credentials.json`, or under
-`CLAUDE_CONFIG_DIR` when that environment variable is set:
-
-```json
-{
-    "claudeAiOauth": {
-        "accessToken": "sk-ant-oat01-...",
-        "refreshToken": "sk-ant-ort01-...",
-        "expiresAt": 1770412938485,
-        "subscriptionType": "team",
-        "rateLimitTier": "default_claude_max_5x"
-    }
-}
-```
-
-The access token expires roughly hourly. When it's expired (or rejected with a 401/403), ccusage refreshes it itself using the `refreshToken` and writes the rotated credentials back to `.credentials.json` — the same flow Claude Code uses, so the two stay in sync and no active Claude Code session is needed.
-
-### Warning thresholds (from cli.js)
-
-Claude Code shows inline warnings based on these thresholds:
-
-```
-five_hour:  90% utilization when 72% of window has passed
-seven_day:  75% at 60%, 50% at 35%, 25% at 15%
-```
-
-### Other endpoints found in cli.js
-
-- `/api/oauth/profile` — User profile
-- `/api/oauth/account/settings` — Account settings
-- `/api/claude_code/policy_limits` — Org policy limits (needs `organizationUuid`)
-- `/api/organization/claude_code_first_token_date` — Org onboarding date
-
-### Local files Claude Code uses
-
-| File | Written by | Contains |
-|------|-----------|----------|
-| `~/.claude/.credentials.json` | Claude Code | OAuth tokens, plan tier |
-| `~/.claude/stats-cache.json` | Claude Code | Local usage stats (message counts, token counts per model) |
-| `~/.claude/usage-limits.json` | ccusage daemon | Cached API usage data (this tool) |
-| `~/.claude/usage-limits/<account uuid>.json` | ccusage daemon | Last usage seen for each Claude account (this tool) |
-| `~/.claude/statsig/` | Claude Code | Feature flags, experiment assignments |

ccusage-0.3.0/pyproject.toml

@@ -1,23 +0,0 @@
-[project]
-name = "ccusage"
-version = "0.3.0"
-description = "Claude Code usage monitor — fetches rate limits from Anthropic's API"
-readme = "README.md"
-requires-python = ">=3.12"
-license = "MIT"
-license-files = ["LICENSE"]
-dependencies = []
-
-[tool.uv]
-package = true
-
-[build-system]
-requires = ["hatchling"]
-build-backend = "hatchling.build"
-
-[project.urls]
-Homepage = "https://github.com/wakamex/ccusage"
-Source = "https://github.com/wakamex/ccusage"
-
-[project.scripts]
-ccusage = "ccusage:main"

ccusage-0.3.0/release-notes/v0.2.0.md

@@ -1,20 +0,0 @@
-ccusage now remembers the usage of every Claude account you log into, so switching accounts with `/login` no longer loses the other account's numbers. The package is also licensed under MIT.
-
-## Highlights
-
-- Each refresh also saves a copy of the usage to `~/.claude/usage-limits/<account uuid>.json`, tagged with the logged-in account's UUID and email. The account you switched away from keeps its last usage there, and since an idle account can't use quota, that copy stays accurate until its windows reset. `usage-limits.json` also gains an `account` field and is otherwise unchanged. ([`e2ed247`](https://github.com/wakamex/ccusage/commit/e2ed247b0b677c7e36220cb5b83f916022e0d14b))
-- If you switch accounts in the middle of a refresh, ccusage skips the per-account copy for that refresh, so usage is never saved under the wrong account. Both cache files are now written atomically, so readers never see a half-written file. ([`e2ed247`](https://github.com/wakamex/ccusage/commit/e2ed247b0b677c7e36220cb5b83f916022e0d14b))
-- The wheel and sdist now include a LICENSE file and declare `License-Expression: MIT`. ([`adbcbdb`](https://github.com/wakamex/ccusage/commit/adbcbdb40450f0e231a46026ad00848b0d188ac1))
-
-## Changes
-
-- Create the GitHub Release from committed release notes ([`146bf16`](https://github.com/wakamex/ccusage/commit/146bf165297bdd16c7300bd0dfdac3240d568fbf))
-- Use the shared release actions ([`e623b1d`](https://github.com/wakamex/ccusage/commit/e623b1d0f5189e71b561f1fbb5fda1c92b788069))
-- Remove the Markdown fence from the release workflows ([`614db37`](https://github.com/wakamex/ccusage/commit/614db372050760ba84f34469acd2ade6e03b0206))
-- Pin runners and actions, and follow release-actions stable ([`1ef57c9`](https://github.com/wakamex/ccusage/commit/1ef57c9009a6604b2bd0804ba654f84064a5b090))
-- Keep the last usage of each Claude account ([`e2ed247`](https://github.com/wakamex/ccusage/commit/e2ed247b0b677c7e36220cb5b83f916022e0d14b))
-- License ccusage under MIT ([`adbcbdb`](https://github.com/wakamex/ccusage/commit/adbcbdb40450f0e231a46026ad00848b0d188ac1))
-
-## History
-
-[v0.1.12...v0.2.0](https://github.com/wakamex/ccusage/compare/v0.1.12...v0.2.0)

ccusage-0.3.0/release-notes/v0.3.0.md

@@ -1,11 +0,0 @@
-`ccusage daemon --defer` lets you keep several Claude accounts current without polling any of them twice.
-
-To track an account you are not logged into, give it its own config directory with a permanent login, run a second daemon there with `CLAUDE_CONFIG_DIR` set, and symlink that directory's `usage-limits` folder to the main one. If you then log your main directory into the same account, both daemons would poll it. A daemon started with `--defer` skips a refresh whenever another daemon saved the same account's snapshot within the last one and a half refresh intervals, and starts refreshing again once that other daemon moves to a different account. Daemons without the flag behave as before.
-
-## Changes
-
-- Add daemon --defer to poll an account once across config directories ([`97d96a2`](https://github.com/wakamex/ccusage/commit/97d96a2b70e3424cece8f32bc8cac440df93c68c))
-
-## History
-
-[v0.2.0...v0.3.0](https://github.com/wakamex/ccusage/compare/v0.2.0...v0.3.0)