ccquota 0.6.0

CLI tool to display Claude usage quota from claude.ai

ccquota

A CLI tool that displays your Claude usage quota — session limits, weekly limits, and optionally organization spending with per-user breakdown. Supports multiple accounts.

日本語版 README はこちら

How It Works

ccquota calls Claude's internal APIs directly. No browser window appears during normal use.

1. Login (one-time per account): Opens Chrome for you to sign in to claude.ai. The session is saved locally under ~/.config/ccquota/sessions/<name>/.
2. Show (default): Launches Chrome headlessly using the saved session, then fetches usage data via Playwright's built-in HTTP client — which shares the browser's cookies and TLS context, so Cloudflare is not an obstacle.

Example Output

Default — shows personal usage for all saved sessions:

  Your Usage (Alice)
  ──────────────────────────────────────────────
  Session           ░░░░░░░░░░░░░░░░░░░░░░░░░ 0%
  Weekly Limit      ██████████████████░░░░░░░ 72%
                    ↻ resets 4/29 (Wed) 17:00
  Claude Design     █████████████░░░░░░░░░░░░ 54%
                    ↻ resets 4/29 (Wed) 17:00

  Your Usage (Bob)
  ──────────────────────────────────────────────
  Session           ░░░░░░░░░░░░░░░░░░░░░░░░░ 0%
  Weekly Limit      ████████░░░░░░░░░░░░░░░░░ 32%
                    ↻ resets 4/30 (Thu) 14:00

With --org — adds organization spending and per-user breakdown for each session:

  Your Usage (Alice)
  ──────────────────────────────────────────────
  Session           ░░░░░░░░░░░░░░░░░░░░░░░░░ 0%
  Weekly Limit      ██████████████████░░░░░░░ 72%
                    ↻ resets 4/29 (Wed) 17:00
  Claude Design     █████████████░░░░░░░░░░░░ 54%
                    ↻ resets 4/29 (Wed) 17:00

  Organization (MyTeam)
  ──────────────────────────────────────────────
  Monthly Spend     ███████████████░░░░░░░░░░ 60%  ($120.09 / $200.00)
  Balance           $79.90

  Spend by User
  ──────────────────────────────────────────────
  Alice                     $95.47
  Bob                       $24.67

  Your Usage (Bob)
  ──────────────────────────────────────────────
  Session           ░░░░░░░░░░░░░░░░░░░░░░░░░ 0%
  Weekly Limit      ████████░░░░░░░░░░░░░░░░░ 32%
                    ↻ resets 4/30 (Thu) 14:00

Requirements

• Python 3.13+
• uv (recommended) or pip
• Google Chrome installed on your system

Installation

pip install ccquota

or with uv:

uv tool install ccquota

Install from source

git clone https://github.com/sanoakr/ccquota.git
cd ccquota
uv sync

Usage

First-time setup

uv run ccquota login

A Chrome window opens. Sign in to claude.ai, and the tool auto-detects completion (up to 5 min timeout). The session is saved under ~/.config/ccquota/sessions/<name>/.

Adding another account

Simply run ccquota login again and sign in with a different account:

ccquota login      # first account
ccquota login      # second account — opens a fresh browser

View usage

ccquota                  # all accounts (default)
ccquota --user Alice     # specific account only
ccquota --org            # all sessions + organization spending & per-user breakdown
ccquota --watch          # refresh every 60s
ccquota -w -n 30         # refresh every 30s
ccquota -o -w            # organization + watch mode
ccquota --debug          # print raw JSON from APIs

If installed from source, use uv tool install -e . for system-wide access. Otherwise prefix commands with uv run.

Logout

ccquota logout           # remove session (auto-selects if only one)
ccquota logout Alice     # remove a specific session
ccquota logout --all     # remove all sessions

Options

Flag	Short	Description
--user NAME	-u NAME	Show only the specified session
--org	-o	Show all sessions with organization spending and per-user breakdown
--watch	-w	Refresh periodically (default: every 60s)
--interval SEC	-n SEC	Watch interval in seconds (default: 60)
--debug		Print raw JSON data from APIs

API Endpoints Used

Endpoint	Data	When
/api/bootstrap	Organization ID, user info	Always
/api/organizations/{id}/usage	Session (5h), weekly, Design, Opus utilization	Always
/api/organizations/{id}/overage_spend_limit	Monthly spend vs. limit	--org
/api/organizations/{id}/overage_spend_limits	Per-user spend breakdown	--org
/api/organizations/{id}/prepaid/credits	Prepaid credit balance	--org

Data Storage

Session data is stored under ~/.config/ccquota/sessions/, with one subdirectory per account. Each is a Chromium user-data directory containing claude.ai session cookies. No credentials are stored elsewhere.

Legacy single-session data (~/.config/ccquota/browser/) is automatically migrated on first run.

License

MIT