حدود الاستخدام

يعرض 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) أنها تأتي من ملف محفوظ، لا من نقطة النهاية. يذكر السطر الأخير الحساب الأقل استخدامًا في نافذة الخمس ساعات دون 100%، ولا يظهر إلا إذا كان لديك أكثر من حساب. ويعرض الحساب غير المسجَّل دخوله 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 واحدًا، فيُعاد استخدام الاتصالات بنقطة النهاية. قد يستغرق الاتصال 2 s، ولكل حساب 3 s إجمالًا. ولا يتبع العميل إعادة التوجيه، لأن إعادة التوجيه سترسل الرمز إلى مكان آخر، ويقرأ 1 MB على الأكثر من الرد.
3. عندما ينتهي كل حساب، يُعاد رسم صفه. والحساب الذي يفشل أو لا يستجيب في الوقت المحدد يلجأ إلى الأرقام المحفوظة، فلا يؤخّر حساب بطيء الحسابات الأخرى أبدًا.

يعمل كل حساب في روتينه الخاص مقابل نقطة النهاية؛ والحساب الذي تنتهي مهلته يعرض أرقامه المحفوظة بدلًا من ذلك.

يستجيب 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) دون تغييره، ولا يُفك إلا المفتاح 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 ويحتفظ بالأحدث. وقبل أن يعرض الأرقام المحفوظة، يتحقق من وقت إعادة ضبط كل نافذة: النافذة التي أُعيد ضبطها منذ حفظ الأرقام تظهر بقيمة 0%، لأن النسبة القديمة لم تعد صحيحة. ولهذا يعرض 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. يرفض تسجيلات الدخول المخزنة في سلسلة المفاتيح على macOS؛
3. يأخذ ملف قفل، $XDG_RUNTIME_DIR/ccam/profile-<name>.refresh.lock (أو تحت ~/.local/state/ccam/locks/ عندما لا يكون ذلك المتغير معيّنًا)، فلا تجدّد عمليتان من ccam الرمز نفسه مرتين أبدًا؛
4. تحت القفل، يرفض إذا كانت جلسة للحساب تعمل، ويتخطى الطلب إذا كانت عملية أخرى قد جدّدت الرمز بالفعل؛
5. يرسل رمز التحديث إلى نقطة نهاية الرموز، ويكتب الرموز الجديدة في .credentials.json باستخدام fsutil.AtomicWrite، مع الإبقاء على كل المفاتيح الأخرى في الملف.

جامع بيانات سطر الحالة

يشغّل 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. لا يحتوي JSON على حدود للطلبات في حسابات مفاتيح API، أو قبل أول رد في الجلسة؛ وعندها لا يُحفظ شيء.
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 المشترك عبر مجموعة يُكتب مرة واحدة، عبر رابطه، فتحصل عليه كل حسابات المجموعة. وتشغيله مرة أخرى يطبع (already set) للملفات التي تستخدم ccam بالفعل.

الأمان والحالات الخاصة

• لا يغيّر ccam usage أبدًا ملف رموز ما لم تمرّر --refresh. وعندما ينتهي تسجيل دخول، شغّل الحساب مرة واحدة باستخدام ccam <name> وسيجدّده Claude Code.
• لا يلمس --refresh أبدًا الحسابات التي تعمل أو الحسابات المستوردة أو تسجيلات الدخول في سلسلة المفاتيح. والتجديد المرفوض يعرض الأرقام المحفوظة والسبب.
• نقطة نهاية الاستخدام غير موثقة علنًا وقد تتغير. وعندما يحدث ذلك، تظل ترى الأرقام المحفوظة، ويبلّغ ccam doctor عن تغيّر التنسيق.
• عندما لا توجد أرقام محفوظة ولا رد، يعرض الصف lookup failed: والسبب، مثلًا no saved usage مع --source cache.
• لا تحتوي ملفات ذاكرة التخزين المؤقت إلا على النسب وأوقات إعادة الضبط، ولا تحتوي على رموز أبدًا.

صفحات ذات صلة

• حدود الاستخدام والتبديل بين الحسابات
• التبديل إلى الحساب التالي
• سير العمل عند بلوغ حد الاستخدام
• الأوامر