استعمال کی حدیں

ccam usage دکھاتا ہے کہ ہر اکاؤنٹ نے 5 گھنٹے اور ہفتہ وار حدوں کا کتنا حصہ استعمال کر لیا ہے، اور ہر ونڈو کے ری سیٹ ہونے میں کتنا وقت باقی ہے۔ کوئی لمبا کام شروع کرنے سے پہلے، یا جب 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) کا مطلب ہے کہ وہ اینڈ پوائنٹ سے نہیں بلکہ ایک محفوظ فائل سے آئے ہیں۔ آخری لائن اس اکاؤنٹ کا نام بتاتی ہے جس کا 5 گھنٹے کا استعمال 100% سے کم اور سب سے کم ہو، اور یہ صرف تب نظر آتی ہے جب آپ کے ایک سے زیادہ اکاؤنٹس ہوں۔ جو اکاؤنٹ لاگ اِن نہ ہو وہ not logged in → ccam login <name> دکھاتا ہے، اور API key والا اکاؤنٹ 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، Claude Code کی اسٹیٹس لائن JSON اسٹینڈرڈ اِن پٹ سے پڑھتا ہے۔ اس کا واحد آپشن --wrap <command> ہے: اسٹیٹس لائن کی ایک موجودہ کمانڈ، جس کے آؤٹ پٹ کی پہلی لائن کے شروع میں اکاؤنٹ کا نام لگ جاتا ہے۔ ccam statusline install کوئی آپشن نہیں لیتا۔ دونوں --dry-run کو --dry-run is not supported by `ccam statusline`; nothing was changed کے ساتھ مسترد کرتے ہیں۔

یہ کیسے کام کرتا ہے

اعداد دو جگہوں سے آتے ہیں: Anthropic کا غیر دستاویزی usage اینڈ پوائنٹ، 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 شیئر کرتے ہیں، اس لیے اینڈ پوائنٹ سے کنکشنز دوبارہ استعمال ہوتے ہیں۔ کنکشن بنانے میں 2 s لگ سکتے ہیں، اور ہر اکاؤنٹ کو کل 3 s ملتے ہیں۔ کلائنٹ ری ڈائریکٹس پر عمل نہیں کرتا، کیونکہ ری ڈائریکٹ ٹوکن کو کسی اور جگہ دوبارہ بھیج دے گا، اور جواب کا زیادہ سے زیادہ 1 MB پڑھتا ہے۔
3. جیسے ہی ہر اکاؤنٹ مکمل ہوتا ہے، اس کی قطار دوبارہ بنتی ہے۔ جو اکاؤنٹ ناکام ہو یا وقت پر جواب نہ دے وہ محفوظ اعداد پر چلا جاتا ہے، اس لیے ایک سست اکاؤنٹ کبھی باقیوں کو نہیں روکتا۔

ہر اکاؤنٹ اینڈ پوائنٹ کے لیے اپنی goroutine میں چلتا ہے؛ جس کا وقت ختم ہو جائے وہ اس کے بجائے اپنے محفوظ اعداد دکھاتا ہے۔

personal اور work وقت پر جواب دیتے ہیں اور تازہ اعداد دکھاتے ہیں۔ side کو 3 s سے زیادہ لگتے ہیں، اس لیے fallback() اس کی دونوں کیش فائلیں پڑھتا ہے اور جو آخر میں لکھی گئی ہو وہ استعمال کرتا ہے۔ usage.Table() قطاریں بناتا ہے اور usage.Best() وہ اکاؤنٹ چنتا ہے جس کا نام آخری لائن میں آتا ہے۔

ایک اکاؤنٹ کے لیے Fetcher.Fetch یہ جانچ اسی ترتیب سے کرتا ہے:

1. --source cache کے ساتھ یہ سیدھا fallback() پر جاتا ہے۔
2. جب تک --no-cache نہ لگا ہو، ~/.local/state/ccam/usage/<name>.json میں 60 سیکنڈ (CacheTTL) سے کم پرانا تازہ نتیجہ جوں کا توں لوٹا دیا جاتا ہے۔ ccam usage کو لگاتار دو بار چلانے پر ہر اکاؤنٹ کی صرف ایک درخواست جاتی ہے۔
3. readCredentials()، .credentials.json (یا macOS Keychain) کو تبدیل کیے بغیر پڑھتا ہے، اور صرف claudeAiOauth key ڈی کوڈ ہوتی ہے۔ سبسکرپشن لاگ اِن نہ ہو تو not logged in، یا جب .claude.json میں API key ہو تو no limits (API)۔
4. میعاد ختم ہونے والا ایکسیس ٹوکن استعمال نہیں ہوتا۔ --refresh کے بغیر اکاؤنٹ اپنے محفوظ اعداد میعاد ختم ہونے کے نشان کے ساتھ دکھاتا ہے۔
5. ورنہ ccam اینڈ پوائنٹ کو کال کرتا ہے۔ 401 یا 403 کو میعاد ختم ہونے والا لاگ اِن سمجھا جاتا ہے، کوئی اور اسٹیٹس یا ایسا جواب جو پڑھا نہ جا سکے غلطی شمار ہوتا ہے، اور دونوں صورتوں میں محفوظ اعداد دکھائے جاتے ہیں۔
6. درست جواب ناپنے کے وقت کے ساتھ <name>.json میں لکھا جاتا ہے۔

fallback()، <name>.json اور <name>.statusline.json دونوں پڑھتا ہے اور نئی والی رکھتا ہے۔ محفوظ اعداد دکھانے سے پہلے یہ ہر ونڈو کے ری سیٹ کا وقت جانچتا ہے: جو ونڈو اعداد محفوظ ہونے کے بعد ری سیٹ ہو چکی ہو وہ 0% دکھاتی ہے، کیونکہ پرانا فیصد اب درست نہیں۔ اسی لیے اوپر personal، ری سیٹ کے وقت کے بغیر 0% دکھاتا ہے۔

اینڈ پوائنٹ کے جواب کے دو فارمیٹ ہیں۔ نئے فارمیٹ میں ایک limits array ہوتا ہے جس میں session (5 گھنٹے)، weekly_all اور weekly_scoped (ماڈل کے لحاظ سے) اینٹریز ہوتی ہیں۔ پرانے فارمیٹ میں five_hour، seven_day، seven_day_opus اور seven_day_sonnet آبجیکٹس ہوتے ہیں۔ ParseLive دونوں پڑھتا ہے: limits array کو ترجیح ملتی ہے، اور جو وہ شامل نہ کرے وہ پرانے آبجیکٹس سے بھرا جاتا ہے۔ جس جواب میں کوئی حد ہی نہ ہو اسے بدلا ہوا فارمیٹ بتایا جاتا ہے، جس کے بارے میں ccam doctor آپ کو بتاتا ہے۔

ٹوکنز کی تجدید

ریفریش ٹوکنز بدلتے رہتے ہیں: ایک کی تجدید سے نیا ریفریش ٹوکن ملتا ہے اور پرانا ناکارہ ہو جاتا ہے۔ اگر ccam لاگ اِن کی تجدید اس وقت کرے جب Claude Code اسی اکاؤنٹ کے طور پر چل رہا ہو، تو وہ سیشن سائن آؤٹ ہو جائے گا۔ اس لیے ccam usage ٹوکنز پڑھتا ہے اور انہیں کبھی نہیں لکھتا، جب تک آپ --refresh نہ دیں۔ تب Fetcher.refresh:

1. ccam import سے اپنی جگہ پر رجسٹر کیے گئے اکاؤنٹس کو مسترد کرتا ہے، کیونکہ سادہ claude ccam کے علم کے بغیر وہ لاگ اِن استعمال کر سکتا ہے؛
2. macOS Keychain میں محفوظ لاگ اِن مسترد کرتا ہے؛
3. ایک لاک فائل لیتا ہے، $XDG_RUNTIME_DIR/ccam/profile-<name>.refresh.lock (وہ ویری ایبل مقرر نہ ہو تو ~/.local/state/ccam/locks/ کے اندر)، تاکہ دو ccam پروسیس کبھی ایک ہی ٹوکن کی دو بار تجدید نہ کریں؛
4. لاک کے تحت، اکاؤنٹ کا کوئی سیشن چل رہا ہو تو انکار کرتا ہے، اور اگر کوئی دوسرا پروسیس پہلے ہی ٹوکن کی تجدید کر چکا ہو تو درخواست چھوڑ دیتا ہے؛
5. ریفریش ٹوکن، ٹوکن اینڈ پوائنٹ کو بھیجتا ہے اور نئے ٹوکنز fsutil.AtomicWrite سے واپس .credentials.json میں لکھتا ہے، اور فائل کی باقی ہر key برقرار رکھتا ہے۔

اسٹیٹس لائن کلیکٹر

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 key والے اکاؤنٹس کے لیے، یا سیشن کے پہلے جواب سے پہلے، JSON میں ریٹ لمٹس نہیں ہوتیں؛ تب کچھ محفوظ نہیں ہوتا۔
3. SaveStatusLine، ~/.local/state/ccam/usage/<name>.statusline.json لکھتا ہے۔ جب اینڈ پوائنٹ جواب نہ دے تو ccam usage اسے استعمال کرتا ہے۔
4. ccam [name] · model · 5h N% · 7d N% پرنٹ کرتا ہے۔ --wrap کے ساتھ یہ آپ کی کمانڈ کو اسی اِن پٹ کے ساتھ sh -c سے چلاتا ہے اور اس کے بجائے [name] کے بعد کمانڈ کی پہلی لائن پرنٹ کرتا ہے۔

لپیٹی گئی کمانڈ کو 2 سیکنڈ ملتے ہیں۔ اس کے بعد اسے بند کر دیا جاتا ہے اور لائن میں صرف اکاؤنٹ کا نام دکھتا ہے، اس لیے کوئی سست کمانڈ Claude Code کی اسٹیٹس لائن کو نہیں روک سکتی۔

ccam statusline install ہر اکاؤنٹ کی settings.json میں statusLine لکھتا ہے۔ جب کسی اکاؤنٹ میں پہلے سے اسٹیٹس لائن کی کمانڈ ہو تو ccam اسے --wrap '<old command>' کی صورت میں برقرار رکھتا ہے۔ کسی گروپ کے ذریعے شیئر کی گئی settings.json اپنے لنک کے ذریعے ایک بار لکھی جاتی ہے، اس لیے گروپ کے ہر اکاؤنٹ کو یہ مل جاتی ہے۔ دوبارہ چلانے پر ان فائلوں کے لیے (already set) پرنٹ ہوتا ہے جو پہلے سے ccam استعمال کر رہی ہیں۔

حفاظت اور خاص صورتیں

• ccam usage کبھی ٹوکن فائل تبدیل نہیں کرتا جب تک آپ --refresh نہ دیں۔ جب کسی لاگ اِن کی میعاد ختم ہو جائے تو اکاؤنٹ کو ایک بار ccam <name> سے چلائیں، Claude Code اس کی تجدید کر دے گا۔
• --refresh کبھی چلتے ہوئے اکاؤنٹس، امپورٹ کیے گئے اکاؤنٹس یا Keychain لاگ اِن کو نہیں چھیڑتا۔ مسترد کی گئی تجدید محفوظ اعداد اور وجہ دکھاتی ہے۔
• usage اینڈ پوائنٹ عوامی طور پر دستاویزی نہیں ہے اور بدل سکتا ہے۔ جب ایسا ہو تو آپ کو پھر بھی محفوظ اعداد نظر آتے ہیں، اور ccam doctor فارمیٹ کی تبدیلی کی اطلاع دیتا ہے۔
• محفوظ اعداد اور جواب دونوں نہ ہوں تو قطار میں lookup failed: اور وجہ دکھتی ہے، مثلاً --source cache کے ساتھ no saved usage۔
• کیش فائلوں میں صرف فیصد اور ری سیٹ کے اوقات ہوتے ہیں، کبھی ٹوکنز نہیں۔

متعلقہ

• استعمال کی حدیں اور اکاؤنٹ تبدیل کرنا
• اگلے اکاؤنٹ پر جانا
• استعمال کی حد کا ورک فلو
• کمانڈز