سقف مصرف

ccam usage نشان می‌دهد هر حساب چه مقدار از سقف ۵ ساعته و هفتگی خود را مصرف کرده است، همراه با زمان باقی‌مانده تا بازنشانی هر پنجره. پیش از شروع یک کار طولانی، یا وقتی Claude Code به شما می‌گوید به سقف نزدیک شده‌اید، از آن استفاده کنید تا ببینید کدام حساب هنوز ظرفیت دارد. ccam statusline فرمان خط وضعیت برای Claude Code است: نام حساب و مصرف آن را داخل Claude Code نشان می‌دهد و عددها را برای ccam usage ذخیره می‌کند.

استفاده

ccam usage                  # every account, once
ccam u                      # the same, shorter
ccam usage --watch          # redraw every 60 seconds until Ctrl+C
ccam usage --watch=10       # redraw every 10 seconds
ccam usage -v               # add per-model weekly limits and the data source
ccam usage --json           # machine-readable, one object per account
ccam usage --source cache   # saved numbers only, no network
ccam usage --refresh        # also renew expired logins of accounts not running
ccam statusline install     # set the status line in every account's settings.json

$ ccam usage
 Account     5-hour        Resets    Weekly        Resets    As of
 1 personal  ░░░░░░░░   0% -         ██████░░  70% 2d 16h    9h 36m ago (cached)
 2 work      ██░░░░░░  24% 2h 29m    ███░░░░░  41% 3d 11h    just now (cached)
 3 side      login expired, run `ccam side` once to refresh
→ Most headroom: personal   (open it with ccam next --auto)

در ترمینال، جدول بلافاصله با fetching… در هر ردیف نمایش داده می‌شود و هر ردیف به محض پاسخ دادن حساب آن دوباره رسم می‌شود. As of نشان می‌دهد عددها چقدر قدیمی‌اند؛ (cached) یعنی عددها از یک فایل ذخیره‌شده آمده‌اند، نه از نقطه پایانی. خط آخر حسابی را نام می‌برد که کمترین مصرف ۵ ساعته زیر ۱۰۰٪ را دارد و فقط وقتی نمایش داده می‌شود که بیش از یک حساب داشته باشید. حسابی که وارد نشده است not logged in → ccam login <name> را نشان می‌دهد و حساب کلید API پیام no limits (API) را.

پس از ccam statusline install، Claude Code خطی مانند [work] · Opus · 5h 24% · 7d 41% را نشان می‌دهد.

گزینه‌ها

هر مقدار دیگری برای --source با --source must be live or cache خطا می‌دهد. ccam usage هیچ آرگومانی نمی‌گیرد.

ccam statusline JSON خط وضعیت Claude Code را از ورودی استاندارد می‌خواند. تنها گزینه آن --wrap <command> است: یک فرمان خط وضعیت موجود که نام حساب پیش از نخستین خط خروجی آن قرار می‌گیرد. ccam statusline install هیچ گزینه‌ای نمی‌گیرد. هر دو --dry-run را با --dry-run is not supported by `ccam statusline`; nothing was changed رد می‌کنند.

چگونه کار می‌کند

عددها از دو جا می‌آیند: نقطه پایانی مصرف Anthropic که مستند نشده است، یعنی GET https://api.anthropic.com/api/oauth/usage، که با ورود خود هر حساب فراخوانی می‌شود، و مقدارهایی که Claude Code به فرمان خط وضعیت خود می‌دهد. همه این‌ها در internal/usage قرار دارد.

1. cli.usageCmd فایل config.toml را بارگذاری می‌کند و برای هر حساب یک usage.Account می‌سازد: پوشه آن ~/.local/share/ccam/profiles/<name>/، پوشه نشست آن (برای اینکه ببیند در حال اجراست یا نه) و اینکه آیا در همان محل وارد شده است.
2. Fetcher.FetchAll برای هر حساب یک goroutine آغاز می‌کند. همه آن‌ها یک http.Client مشترک دارند، بنابراین اتصال‌ها به نقطه پایانی دوباره استفاده می‌شوند. برقراری اتصال می‌تواند ۲ ثانیه طول بکشد و هر حساب روی هم ۳ ثانیه فرصت دارد. کلاینت هدایت‌ها را دنبال نمی‌کند، چون یک هدایت توکن را به جای دیگری می‌فرستد، و حداکثر ۱ MB از پاسخ را می‌خواند.
3. با تمام شدن کار هر حساب، ردیف آن دوباره رسم می‌شود. حسابی که ناموفق باشد یا به‌موقع پاسخ ندهد به عددهای ذخیره‌شده برمی‌گردد، بنابراین یک حساب کند هرگز بقیه را معطل نمی‌کند.

هر حساب در goroutine خودش با نقطه پایانی کار می‌کند؛ حسابی که مهلتش تمام شود به‌جای آن عددهای ذخیره‌شده خود را نشان می‌دهد.

personal و work به‌موقع پاسخ می‌دهند و عددهای زنده را نشان می‌دهند. side بیش از ۳ ثانیه طول می‌کشد، پس fallback() دو فایل حافظه نهان آن را می‌خواند و از هر کدام که آخر نوشته شده استفاده می‌کند. usage.Table() ردیف‌ها را رسم می‌کند و usage.Best() حسابی را که در خط آخر نام برده می‌شود انتخاب می‌کند.

برای یک حساب، Fetcher.Fetch این بررسی‌ها را به ترتیب انجام می‌دهد:

1. با --source cache، مستقیم به fallback() می‌رود.
2. مگر اینکه --no-cache تنظیم شده باشد، یک نتیجه زنده در ~/.local/state/ccam/usage/<name>.json که کمتر از ۶۰ ثانیه (CacheTTL) از آن گذشته باشد همان‌طور که هست برگردانده می‌شود. اجرای دو بار پشت سر هم ccam usage برای هر حساب فقط یک درخواست هزینه دارد.
3. readCredentials() فایل .credentials.json (یا Keychain سیستم macOS) را بدون تغییر می‌خواند و فقط کلید claudeAiOauth رمزگشایی می‌شود. نبودن ورود اشتراکی یعنی not logged in، یا no limits (API) وقتی .claude.json یک کلید API دارد.
4. توکن دسترسی منقضی‌شده استفاده نمی‌شود. بدون --refresh، حساب عددهای ذخیره‌شده خود را با علامت منقضی‌شده نشان می‌دهد.
5. در غیر این صورت ccam نقطه پایانی را فراخوانی می‌کند. پاسخ 401 یا 403 به‌عنوان ورود منقضی‌شده و هر وضعیت دیگر یا بدنه‌ای که نتواند بخواند به‌عنوان خطا به حساب می‌آید و در هر دو حالت به عددهای ذخیره‌شده برمی‌گردد.
6. پاسخ درست همراه با زمان اندازه‌گیری در <name>.json نوشته می‌شود.

fallback() هر دو فایل <name>.json و <name>.statusline.json را می‌خواند و جدیدتر را نگه می‌دارد. پیش از نشان دادن عددهای ذخیره‌شده، زمان بازنشانی هر پنجره را بررسی می‌کند: پنجره‌ای که پس از ذخیره عددها بازنشانی شده باشد ۰٪ نشان می‌دهد، چون درصد قدیمی دیگر معتبر نیست. به همین دلیل personal در بالا 0% را بدون زمان بازنشانی نشان می‌دهد.

نقطه پایانی دو قالب پاسخ دارد. قالب جدیدتر یک آرایه limits با ورودی‌های session (۵ ساعته)، weekly_all و weekly_scoped (ویژه هر مدل) دارد. قالب قدیمی‌تر شیءهای five_hour، seven_day، seven_day_opus و seven_day_sonnet را دارد. ParseLive هر دو را می‌خواند: آرایه limits اولویت دارد و شیءهای قدیمی آنچه را که آن پوشش نمی‌دهد کامل می‌کنند. بدنه‌ای که هیچ سقفی نداشته باشد به‌عنوان قالب تغییرکرده گزارش می‌شود و ccam doctor آن را به شما اطلاع می‌دهد.

تمدید توکن‌ها

توکن‌های تمدید چرخشی‌اند: تمدید یکی از آن‌ها یک توکن تمدید جدید به شما می‌دهد و توکن قبلی را باطل می‌کند. اگر ccam ورود را در حالی تمدید کند که Claude Code با همان حساب در حال اجراست، آن نشست از حساب خارج می‌شود. بنابراین ccam usage توکن‌ها را می‌خواند و هرگز آن‌ها را نمی‌نویسد، مگر اینکه --refresh را بدهید. در آن صورت Fetcher.refresh:

1. حساب‌هایی را که با ccam import در همان محل ثبت شده‌اند رد می‌کند، چون claude معمولی ممکن است بدون اطلاع ccam از آن ورود استفاده کند؛
2. ورودهایی را که در Keychain سیستم macOS ذخیره شده‌اند رد می‌کند؛
3. یک فایل قفل، $XDG_RUNTIME_DIR/ccam/profile-<name>.refresh.lock (یا زیر ~/.local/state/ccam/locks/ وقتی آن متغیر تنظیم نشده باشد) می‌گیرد، تا دو فرایند ccam هرگز یک توکن را دو بار تمدید نکنند؛
4. زیر قفل، اگر نشستی از آن حساب در حال اجرا باشد رد می‌کند، و اگر فرایند دیگری توکن را از قبل تمدید کرده باشد از درخواست صرف‌نظر می‌کند؛
5. توکن تمدید را به نقطه پایانی توکن می‌فرستد و توکن‌های جدید را با fsutil.AtomicWrite در .credentials.json می‌نویسد و همه کلیدهای دیگر فایل را نگه می‌دارد.

جمع‌آوری‌کننده خط وضعیت

Claude Code فرمان خط وضعیت را اجرا می‌کند و یک سند JSON را به ورودی آن می‌فرستد. ccam نام مدل و rate_limits را از آن می‌خواند:

1. runStatusline حساب را از CCAM_PROFILE پیدا می‌کند که ccam هنگام اجرای Claude Code تنظیم می‌کند، یا در غیر این صورت با مقایسه CLAUDE_CONFIG_DIR با پوشه‌های حساب‌ها.
2. ParseStatusLine مقدارهای rate_limits.five_hour و rate_limits.seven_day را می‌خواند. برای حساب‌های کلید API، یا پیش از نخستین پاسخ نشست، JSON هیچ سقف نرخی ندارد؛ در این حالت چیزی ذخیره نمی‌شود.
3. SaveStatusLine فایل ~/.local/state/ccam/usage/<name>.statusline.json را می‌نویسد. ccam usage وقتی نقطه پایانی پاسخ ندهد از آن استفاده می‌کند.
4. ccam خط [name] · model · 5h N% · 7d N% را چاپ می‌کند. با --wrap، فرمان شما را با همان ورودی از طریق sh -c اجرا می‌کند و به‌جای آن [name] و پس از آن نخستین خط خروجی فرمان را چاپ می‌کند.

فرمان پیچیده‌شده ۲ ثانیه فرصت دارد. پس از آن متوقف می‌شود و خط فقط نام حساب را نشان می‌دهد، بنابراین یک فرمان کند نمی‌تواند خط وضعیت Claude Code را مسدود کند.

ccam statusline install مقدار statusLine را در settings.json هر حساب می‌نویسد. وقتی یک حساب از قبل فرمان خط وضعیت داشته باشد، ccam آن را به شکل --wrap '<old command>' نگه می‌دارد. settings.json که از طریق یک گروه به اشتراک گذاشته شده است یک بار و از طریق پیوند خود نوشته می‌شود، بنابراین همه حساب‌های گروه آن را دریافت می‌کنند. اجرای دوباره آن برای فایل‌هایی که از قبل از ccam استفاده می‌کنند (already set) را چاپ می‌کند.

ایمنی و حالت‌های خاص

• ccam usage هرگز فایل توکن را تغییر نمی‌دهد، مگر اینکه --refresh را بدهید. وقتی یک ورود منقضی شده باشد، حساب را یک بار با ccam <name> اجرا کنید تا Claude Code آن را تمدید کند.
• --refresh هرگز به حساب‌های در حال اجرا، حساب‌های واردشده یا ورودهای Keychain دست نمی‌زند. تمدیدی که رد شود عددهای ذخیره‌شده و دلیل آن را نشان می‌دهد.
• نقطه پایانی مصرف به‌طور عمومی مستند نشده است و ممکن است تغییر کند. وقتی تغییر کند، همچنان عددهای ذخیره‌شده را می‌بینید و ccam doctor تغییر قالب را گزارش می‌دهد.
• وقتی نه عدد ذخیره‌شده‌ای باشد و نه پاسخی، ردیف lookup failed: و دلیل آن را نشان می‌دهد، برای مثال no saved usage با --source cache.
• فایل‌های حافظه نهان فقط درصدها و زمان‌های بازنشانی را نگه می‌دارند، هرگز توکن‌ها را.

مرتبط

• سقف مصرف و جابه‌جایی بین حساب‌ها
• رفتن به حساب بعدی
• راهنمای کار با سقف مصرف
• فرمان‌ها