convez.ai
Plugin
zhuchenxi113

ai-limit

zhuchenxi113/ai-limit

Ver no GitHub
BomPluginScore · de 0 a 100

A tool to monitor Claude Code and CodeX usage limits, quota, and token consumption — with both CLI and GUI | 实时监控 Claude Code 与 Codex 的用量、配额和 Token 消耗,支持 CLI 与 GUI 双模式

Instalação

$npx convez-ai zhuchenxi113/ai-limit

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
56
Forks
7
Acompanhando
0
Saúde
42%
Último commit
há 2 meses
Versão
v0.3.28
Issues abertas
1
Contribuidores
1

README

A tradução para o português deste README ainda está na fila.

ai-limit

English | 中文说明

A lightweight tool to monitor real-time Claude Code and Codex usage limits, quota consumption, and token statistics — so you can adjust your AI usage before hitting rate limits. Available as a macOS menu bar app or a CLI.

If you find it useful, a Star would be appreciated: GitHub · Gitee

macOS Menu Bar App

Lives in the menu bar, shows live quota at a glance — no terminal needed. Because it displays text data directly in the menu bar, it takes up more space than a typical icon-only app; a menu bar manager like Bartender is recommended.

Menu bar screenshot

Menu bar in context

Menu bar in context

One-line install

curl -fsSL https://raw.githubusercontent.com/zhuchenxi113/ai-limit/main/install.sh | bash

First launch: right-click the app → Open → Open Anyway (bypasses Gatekeeper; the app is not notarized)

Features

  • Chinese / English UI toggle
  • 5-hour / 7-day quota window toggle
  • Claude and Codex shown simultaneously, each independently configurable
  • Manual refresh
  • Click to expand details (plan, usage, reset time)

Build from source

cd menubar
/opt/homebrew/bin/python3.13 setup.py py2app
bash make-dmg.sh

Homebrew Python is required. Anaconda Python causes dylib path conflicts that prevent the packaged app from launching.


CLI

Output language is detected automatically from your system locale.

Preview

CLI screenshot (English)

CLI screenshot (Chinese)

Requirements

  • macOS
  • Python 3.8+
  • Chrome or Firefox signed in to claude.ai (for Claude quota)
  • Chrome or Firefox signed in to chatgpt.com (recommended path for Codex quota)
  • Optional: Codex CLI installed and signed in (fallback when browser cookies are unavailable)

Usage Prerequisites

ai-limit only reads your existing local Claude / ChatGPT browser session and local usage records. It does not provide subscriptions and does not bypass any quota limits.

  • If Claude Code is available and signed in, Claude Code quota is shown.
  • If ChatGPT / Codex is available and signed in, Codex quota is shown.
  • Services that are unavailable or not signed in show a ⚠️ warning. You can hide each service from the menu bar app under Services.
  • If both services are unavailable, the menu bar shows ai-limit ⚠️ or the corresponding error state.

Installation

1. Clone the repo

git clone https://github.com/zhuchenxi113/ai-limit.git ~/Developer/ai-limit

2. Install dependencies

pip install -r requirements.txt

3. Add an alias

Add to ~/.zshrc:

alias ai-limit="python3 ~/Developer/ai-limit/usage.py"

Then reload:

source ~/.zshrc

Usage

ai-limit              # Last 7 days (default)
ai-limit --days 1     # Today only
ai-limit --all        # Full history
ai-limit --detail     # Show per-model token breakdown

Output language is auto-detected from the system locale (Chinese on zh systems, English elsewhere). Override with AI_LIMIT_LANG:

AI_LIMIT_LANG=en ai-limit   # force English
AI_LIMIT_LANG=zh ai-limit   # force Chinese

Data Sources

Claude Code

DataSource
Token usage details~/.claude/projects/**/*.jsonl
Live quotaBrowser cookie → claude.ai/api/organizations/{orgId}/usage

Quota reading requires an active browser session on claude.ai. Falls back gracefully with an error message and a direct link if the cookie is missing or expired.

Codex

Data sources are tried in priority order:

PriorityDataSourceTriggers 5h window?
1Live quotaBrowser cookie → chatgpt.com/backend-api/codex/usage❌ No
2Live quotacodex app-server WebSocket → account/rateLimits/read⚠️ Yes
3Local fallback~/.codex/sessions/**/*.jsonl❌ No

The browser path (1) reuses the same analytics endpoint that powers the chatgpt.com dashboard. It returns merged Cloud + CLI usage, is read-only, and does not trigger a new window. This is the recommended default.

⚠️ Side-effect warning (Codex protocol limitation): When path 1 fails (not signed in to chatgpt.com / cookies expired / network issue), ai-limit falls back to codex app-server. That path sends an initialize call, which OpenAI counts as a session start — if the current 5-hour window has already expired, this triggers a new 5-hour rolling window. This is an inherent consequence of how the Codex CLI exposes its data; no workaround exists at the tool level.

Notes

  • macOS only: browser cookie reading relies on the system Keychain to decrypt Chrome cookies
  • Unofficial API: Claude quota is fetched from an internal claude.ai endpoint, not an official API — it may break with future updates
  • Occasional ⚠️ (Cloudflare challenge): claude.ai / chatgpt.com may temporarily serve a Cloudflare bot-challenge to non-browser requests (based on TLS fingerprint — even a valid cookie can be blocked), surfaced as a ⚠️. It usually clears on its own. This affects any non-browser tool accessing these sites — the official Claude Code / Codex CLIs hit the same thing — so it is not a defect of ai-limit and generally needs no action. If the warning persists, open the Claude usage page or CodeX dashboard from the menu and keep the tab open — the active browser session accelerates recovery
  • <synthetic> model entries are error placeholders written by Claude Code on API failures; they are excluded from all statistics
  • Per-model output share is only available for Claude Code; Codex does not expose per-model breakdown

Maintenance

This is a personal tool maintained on a best-effort basis. Issues and PRs are welcome but not guaranteed to be addressed promptly. No long-term support is promised.

Other projects by the author

License

Project code: Apache License 2.0

Third-party dependency: browser-cookie3 is licensed under LGPL.

Ver o original no GitHub

Bom para

Relacionados