عن المشروع

claude-print هو غلاف لواجهة السطر البرمجي (command-line wrapper) حول واجهة المستخدم التفاعلية لـ Claude Code. غرضه محدد وصريح: تقوم Anthropic بتوجيه الوضع غير الرأسي (headless mode)، وهو `claude -p` (مسار SDK/pipe)، عبر مجمع رصيد Agent SDK منفصل، بينما يتم احتساب تكلفة واجهة TUI التفاعلية فقط مقابل اشتراك غير محدود. يذكر ملف README أن مسار الفوترة يتم تحديده بواسطة فحص `isatty` داخل ملف `claude` الثنائي؛ حيث يتم وسم مخرجات TTY بأن الجلسة هي `cc_entrypoint=cli` بينما يتم وسم الأنبوب (pipe) بأنها `cc_entrypoint=sdk-cli`. يقوم claude-print بتخصيص PTY، وتشغيل واجهة TUI من خلاله، ويهدف إلى البقاء متوافقاً مع مخرجات `claude -p` مع احتساب التكلفة مقابل الاشتراك. آلية العمل وفقاً لملف README: - يقوم بتشغيل `claude` تحت PTY بحيث تعيد `isatty` القيمة true. - يراقب مربع حوار الثقة بالمشروع الذي يظهر لمرة واحدة ويرسل مفتاح التأكيد تلقائياً. - يحقن المطالبة (prompt) باستخدام تسلسلات هروب bracketed-paste، بحيث تعاملها واجهة TUI كمدخلات مستخدم دون تفسير من قبل shell. - يقوم بتثبيت خطاف (Stop hook) مؤقت لـ Claude Code يكتب إلى FIFO؛ وتتوقف العملية عند تلك القراءة. - يقرأ سجل الجلسة بتنسيق JSONL، ويستخرج دور المساعد، ويصدره بالتنسيق المطلوب. يمكن أن تأتي المدخلات من وسيط موضعي، أو `--input-file`، أو stdin غير TTY؛ وهذه الخيارات مانعة لبعضها البعض. تنسيقات المخرجات هي `text` (الافتراضي)، و `json` (كائن في سطر واحد يحتوي على حقول مثل result و session_id و num_turns و duration_ms و cost_usd و claude_version وكائن usage يحتوي على عدد توكنات المدخلات والمخرجات والذاكرة المخبئية)، و `stream-json` (إعادة تشغيل فورية لأحداث السجل بتنسيق JSONL). تشمل الأعلام (flags) الموثقة `--model` و `--max-turns` و `--allowedTools`/`--disallowedTools` و `--dangerously-skip-permissions` وعدة أدوات للتحكم في المهلة (wall-clock و first-output و stream-json و Stop hook) و `--claude-binary` و `--config` و `--no-inherit-hooks` و `--verbose` و `--check` و `--version` و `--help`. تم توثيق أكواد الخروج للنجاح (0)، وخطأ المساعد (1)، والخطأ الداخلي (2)، وخطأ المدخلات (4)، والمهلة (124)، و SIGINT (130). التكوين اختياري بتنسيق TOML في `$XDG_CONFIG_HOME/claude-print/config.toml` أو `~/.config/claude-print/config.toml` ويمكن تجاوزه باستخدام `--config`. المفاتيح الموثقة هي `model` و `inherit_hooks` و `max_turns` و `timeout_secs` وكلها اختيارية مع وجود تحقق: في حال فقدان الملف يتم الرجوع إلى الإعدادات الافتراضية، ولكن إذا كان التكوين غير قابل للقراءة أو مشوهاً أو خارج النطاق، يخرج البرنامج بالحالة 2 بدلاً من التحذير والاستمرار. يتم التثبيت عبر `sh install.sh` الذي يقوم بتنزيل ملف ثنائي static musl مبني مسبقاً من GitHub Releases، ويشغل `--check` ويقوم اختيارياً بنسخ محول YAML إلى `~/.needle/agents/` لإرسال NEEDLE fleet. كما تم توثيق البناء من المصدر باستخدام Cargo. يتم دعم Linux x86_64 فقط؛ بينما تقع معمارية aarch64/ARM و Windows ConPTY صراحةً خارج النطاق. يوثق ملف README أيضاً سكربتات التحقق من الفوترة التي تفحص أحدث سجل للبحث عن حقل `entrypoint` وخدمة/مؤقت canary يومي. القيود المذكورة: تخصيص PTY لنظام Linux فقط، ويجب أن يكون ملف `claude` الثنائي مثبتاً وموثقاً بالفعل، ومطالبة واحدة لكل استدعاء دون وضع جلسة متعددة الأدوار، وزمن تأخير في التشغيل يتراوح بين 2 إلى 5 ثوانٍ تقريباً مقارنة باستدعاء HTTP مباشر. هناك متطلب تشغيلي بارز وهو ضرورة تعيين `HOME` إلى دليل موجود وقابل للكتابة وغير فارغ؛ حيث لا يقوم البرنامج عمداً بتخمين `/root` أو استشارة قاعدة بيانات passwd، وتفرض الإصدارات الحالية هذا العقد قبل بدء الجلسة و `--check` و `--version`. تغطي ملاحظات استكشاف الأخطاء وإصلاحها فقدان `/dev/ptmx` وعدم تفعيل Stop hooks وحالات السباق في السجلات.