Metadata-Version: 2.4
Name: ccquota
Version: 0.6.0
Summary: CLI tool to display Claude usage quota from claude.ai
Project-URL: Repository, https://github.com/sanoakr/ccquota
Author-email: SANO Akira <sano@maica.org>
License-Expression: MIT
License-File: LICENSE
Keywords: anthropic,claude,cli,quota,usage
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Utilities
Requires-Python: >=3.13
Requires-Dist: playwright>=1.58.0
Description-Content-Type: text/markdown

# ccquota

A CLI tool that displays your [Claude](https://claude.ai) usage quota — session limits, weekly limits, and optionally organization spending with per-user breakdown. Supports multiple accounts.

[日本語版 README はこちら](README.ja.md)

## 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](https://docs.astral.sh/uv/) (recommended) or pip
- Google Chrome installed on your system

## Installation

```bash
pip install ccquota
```

or with uv:

```bash
uv tool install ccquota
```

### Install from source

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

## Usage

### First-time setup

```bash
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:

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

### View usage

```bash
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

```bash
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
