ccusage - أداة تحليل استخدام كود كلود

نظرة عامة على المشروع

ccusage هي أداة سطر أوامر (CLI) تُستخدم لتحليل بيانات الاستخدام من ملفات JSONL المحلية الخاصة بـ Claude Code. تم تطوير هذا المشروع بواسطة @ryoppippi، مستوحى من مقال حول تتبع تكاليف استخدام Claude Code.

الميزات الرئيسية

📊 أنواع تقارير متعددة

• التقرير اليومي: يلخص استخدام التوكنات والتكلفة حسب التاريخ
• التقرير الشهري: يلخص استخدام التوكنات والتكلفة حسب الشهر
• تقرير الجلسات: يعرض الاستخدام مجمعًا حسب جلسة المحادثة
• تقرير الكتل الزمنية (5 ساعات): تقرير يستند إلى نافذة الفوترة ذات الخمس ساعات
• سطر الحالة: سطر حالة مدمج للاستخدام مع الـ hooks (إصدار تجريبي)

🎯 ميزات تصفية وتحليل قوية

• تصفية التاريخ: تصفية التقارير حسب النطاق الزمني باستخدام --since و --until
• تحليل المشاريع: التجميع حسب المشروع/المثيل، مع دعم تصفية المشاريع المحددة
• تفصيل تكلفة النموذج: تفصيل التكلفة لكل نموذج
• المنطقة الزمنية واللغة المحلية: يدعم المنطقة الزمنية UTC وتنسيق اللغة المحلية اليابانية

🎨 إخراج وعرض جذاب

• عرض بتنسيق جدول ملون، مع تخطيط تلقائي متجاوب
• الجداول الذكية: وضع مدمج تلقائي للشاشات الطرفية الضيقة (<100 حرف)، يعرض الأعمدة الأساسية
• الوضع المدمج: استخدام علامة --compact لفرض تخطيط جدول مدمج، مثالي للقطات الشاشة والمشاركة
• عرض النموذج المحسّن: أسماء النماذج معروضة في قائمة نقطية لتحسين سهولة القراءة

💰 ميزات تتبع التكلفة

• عرض التكلفة اليومية/الشهرية/لكل جلسة بالدولار الأمريكي
• دعم توكنات التخزين المؤقت: تتبع وعرض توكنات إنشاء التخزين المؤقت وقراءة التخزين المؤقت بشكل منفصل
• وضع عدم الاتصال: استخدام --offline لاستخدام بيانات التسعير المخزنة مؤقتًا مسبقًا عند عدم وجود اتصال بالشبكة (نماذج Claude فقط)

⚡ المراقبة في الوقت الفعلي

• لوحة تحكم للاستخدام في الوقت الفعلي
• المراقبة في الوقت الفعلي: ccusage blocks --live

التثبيت والاستخدام

البدء السريع (بدون تثبيت)

نظرًا لحجم حزمة ccusage الصغير جدًا، يمكن تشغيلها مباشرة دون الحاجة إلى التثبيت:

# باستخدام bunx (موصى به، أسرع)
bunx ccusage

# باستخدام npx
npx ccusage@latest

# باستخدام deno (مع علامات الأمان)
deno run -E -R=$HOME/.claude/projects/ -S=homedir -N='raw.githubusercontent.com:443' npm:ccusage@latest

التثبيت العام

# التثبيت العام باستخدام npm
npm install -g ccusage

# التثبيت العام باستخدام bun
bun install -g ccusage

# ثم قم بالتشغيل
ccusage

بيئة التطوير

# استنساخ المستودع
git clone https://github.com/ryoppippi/ccusage.git
cd ccusage

# تثبيت التبعيات
bun install

# تشغيل الأداة
bun run report [subcommand] [options]

الاستخدام الأساسي

التقرير اليومي

# عرض جميع حالات الاستخدام اليومية
ccusage daily

# التصفية حسب النطاق الزمني
ccusage daily --since 20250525 --until 20250530

# استخدام دليل بيانات Claude مخصص
ccusage daily --path /custom/path/to/.claude

# الإخراج بتنسيق JSON
ccusage daily --json

# تفصيل التكلفة لكل نموذج
ccusage daily --breakdown

# استخدام المنطقة الزمنية UTC
ccusage daily --timezone UTC

# استخدام اللغة المحلية اليابانية
ccusage daily --locale ja-JP

تحليل المشاريع

# التجميع حسب المشروع/المثيل
ccusage daily --instances

# التصفية لمشروع معين
ccusage daily --project myproject

# الاستخدام المشترك
ccusage daily --instances --project myproject --json

تقرير الجلسات

# عرض جميع الجلسات
ccusage session

# تصفية الجلسات حسب تاريخ آخر نشاط
ccusage session --since 20250525

# دمج عوامل التصفية
ccusage session --since 20250525 --until 20250530 --path /custom/path

# الإخراج بتنسيق JSON
ccusage session --json

المراقبة في الوقت الفعلي

# لوحة تحكم للاستخدام في الوقت الفعلي
ccusage blocks --live

# نافذة الفوترة ذات الخمس ساعات
ccusage blocks

# سطر الحالة (إصدار تجريبي)
ccusage statusline

الوضع المدمج

# فرض وضع الجدول المدمج
ccusage --compact

# تقرير شهري مدمج
ccusage monthly --compact

خيارات الأوامر

تدعم جميع الأوامر الخيارات التالية:

• -s, --since <date>: التصفية من تاريخ (بتنسيق YYYYMMDD)
• -u, --until <date>: التصفية حتى تاريخ (بتنسيق YYYYMMDD)
• -p, --path <path>: مسار مخصص لدليل بيانات Claude (الافتراضي: ~/.claude)
• -j, --json: إخراج النتائج بتنسيق JSON بدلاً من الجدول
• -h, --help: عرض معلومات المساعدة
• -v, --version: عرض الإصدار

أمثلة على الإخراج

إخراج التقرير اليومي

╭──────────────────────────────────────────╮
│                                          │
│ Claude Code Token Usage Report - Daily  │
│                                          │
╰──────────────────────────────────────────╯
┌──────────────────┬──────────────┬───────────────┬──────────────┬────────────┐
│ التاريخ         │ توكنات الإدخال │ توكنات الإخراج │ إجمالي التوكنات │ التكلفة (دولار أمريكي) │
├──────────────────┼──────────────┼───────────────┼──────────────┼────────────┤
│ 2025-05-30       │ 277          │ 31,456        │ 31,733       │ $17.45     │
│ 2025-05-29       │ 959          │ 39,662        │ 40,621       │ $16.37     │
│ 2025-05-28       │ 155          │ 21,693        │ 21,848       │ $8.33      │
├──────────────────┼──────────────┼───────────────┼──────────────┼────────────┤
│ الإجمالي        │ 11,174       │ 720,366       │ 731,540      │ $336.17    │
└──────────────────┴──────────────┴───────────────┴──────────────┴────────────┘

إخراج تقرير الجلسات

╭───────────────────────────────────────────────╮
│                                               │
│ Claude Code Token Usage Report - By Session  │
│                                               │
╰───────────────────────────────────────────────╯
┌──────────────────────────────┬──────────────┬───────────────┬──────────────┬────────────┬───────────────┐
│ المشروع / الجلسة            │ توكنات الإدخال │ توكنات الإخراج │ إجمالي التوكنات │ التكلفة (دولار أمريكي) │ آخر نشاط      │
├──────────────────────────────┼──────────────┼───────────────┼──────────────┼────────────┼───────────────┤
│ my-project                   │ 2,775        │ 186,645       │ 189,420      │ $98.40     │ 2025-05-26    │
│ └─ session-abc123...         │              │               │              │            │               │
│ another-project              │ 1,063        │ 41,421        │ 42,484       │ $20.08     │ 2025-05-29    │
│ └─ session-def456...         │              │               │              │            │               │
├──────────────────────────────┼──────────────┼───────────────┼──────────────┼────────────┼───────────────┤
│ الإجمالي                    │ 11,174       │ 720,445       │ 731,619      │ $336.38    │               │
└──────────────────────────────┴──────────────┴───────────────┴──────────────┴────────────┴───────────────┘

البنية التقنية

متطلبات التبعيات

• بيئة تشغيل Bun
• ملفات سجل استخدام Claude Code (~/.claude/projects/**/*.jsonl)

هيكل المشروع

ccusage/
├── commands/
│   ├── daily.ts        # أمر التقرير اليومي
│   └── session.ts      # أمر تقرير الجلسات
├── data-loader.ts      # منطق تحميل بيانات JSONL
├── index.ts           # نقطة دخول CLI
├── logger.ts          # إعدادات التسجيل
├── utils.ts           # أدوات مشتركة
└── package.json

التطوير والاختبار

# تشغيل الاختبارات
bun test

# فحص الأنواع
bun run typecheck

# فحص الكود
bun run lint

# تنسيق الكود
bun run format

ميزات التكامل

🔌 تكامل MCP

خادم بروتوكول سياق النموذج (MCP) مدمج للتكامل مع أدوات أخرى

الملخص

ccusage هي أداة سطر أوامر (CLI) قوية وسهلة الاستخدام، مصممة خصيصًا لمستخدمي Claude Code لتحليل وتتبع استخدام التوكنات والتكاليف المرتبطة بها. تصميمها الخفيف، ومجموعة ميزاتها الغنية، وإخراجها الجذاب يجعلها الخيار الأمثل للمطورين الذين يتطلعون إلى تحسين استخدام Claude Code وإدارة التكاليف.