مرجع الواجهة البرمجية

يوفر icc أداة سطر أوامر ومقبس Unix للتحكم البرمجي. كل أمر متاح عبر كلتا الواجهتين.

المقبس

البناء	المسار
الإصدار	`/tmp/icc.sock`
التصحيح	`/tmp/icc-debug.sock`
بناء تصحيح موسوم	`/tmp/icc-debug-<tag>.sock`

تجاوز بمتغير البيئة ICC_SOCKET_PATH. أرسل طلب JSON واحد منتهي بسطر جديد لكل استدعاء:

{"id":"req-1","method":"workspace.list","params":{}}
// Response:
{"id":"req-1","ok":true,"result":{"workspaces":[...]}}

طلبات مقبس JSON يجب أن تستخدم method وparams. حمولات JSON القديمة بنسخة v1 مثل {"command":"..."} غير مدعومة.

أوضاع الوصول

الوضع	الوصف	كيفية التفعيل
Off	المقبس معطل	واجهة الإعدادات أو ICC_SOCKET_MODE=off
icc processes only	فقط العمليات التي بدأت داخل طرفيات icc يمكنها الاتصال.	الوضع الافتراضي في واجهة الإعدادات
allowAll	السماح لأي عملية محلية بالاتصال (بدون فحص السلالة).	تجاوز عبر متغير البيئة فقط: ICC_SOCKET_MODE=allowAll

على الأجهزة المشتركة، استخدم وضع معطل أو عمليات icc فقط.

خيارات واجهة الأوامر

العلم	الوصف
`--socket PATH`	مسار مقبس مخصص
`--json`	الإخراج بتنسيق JSON
`--window ID`	استهداف نافذة محددة
`--workspace ID`	استهداف مساحة عمل محددة
`--surface ID`	استهداف سطح محدد
`--id-format refs\|uuids\|both`	التحكم بتنسيق المعرف في إخراج JSON

أوامر مساحة العمل

list-workspaces

عرض جميع مساحات العمل المفتوحة.

CLI

icc list-workspaces
icc list-workspaces --json

Socket

{"id":"ws-list","method":"workspace.list","params":{}}

new-workspace

إنشاء مساحة عمل جديدة.

CLI

icc new-workspace

Socket

{"id":"ws-new","method":"workspace.create","params":{}}

select-workspace

التبديل إلى مساحة عمل محددة.

CLI

icc select-workspace --workspace <id>

Socket

{"id":"ws-select","method":"workspace.select","params":{"workspace_id":"<id>"}}

current-workspace

الحصول على مساحة العمل النشطة حالياً.

CLI

icc current-workspace
icc current-workspace --json

Socket

{"id":"ws-current","method":"workspace.current","params":{}}

close-workspace

إغلاق مساحة عمل.

CLI

icc close-workspace --workspace <id>

Socket

{"id":"ws-close","method":"workspace.close","params":{"workspace_id":"<id>"}}

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

new-split

إنشاء لوح مقسم جديد. الاتجاهات: يسار، يمين، أعلى، أسفل.

CLI

icc new-split right
icc new-split down

Socket

{"id":"split-new","method":"surface.split","params":{"direction":"right"}}

list-surfaces

عرض جميع الأسطح في مساحة العمل الحالية.

CLI

icc list-surfaces
icc list-surfaces --json

Socket

{"id":"surface-list","method":"surface.list","params":{}}

focus-surface

التركيز على سطح محدد.

CLI

icc focus-surface --surface <id>

Socket

{"id":"surface-focus","method":"surface.focus","params":{"surface_id":"<id>"}}

أوامر الإدخال

send

إرسال نص إلى الطرفية المركزة.

CLI

icc send "echo hello"
icc send "ls -la\n"

Socket

{"id":"send-text","method":"surface.send_text","params":{"text":"echo hello\n"}}

send-key

إرسال ضغطة مفتاح. المفاتيح: enter, tab, escape, backspace, delete, up, down, left, right.

CLI

icc send-key enter

Socket

{"id":"send-key","method":"surface.send_key","params":{"key":"enter"}}

send-surface

إرسال نص إلى سطح محدد.

CLI

icc send-surface --surface <id> "command"

Socket

{"id":"send-surface","method":"surface.send_text","params":{"surface_id":"<id>","text":"command"}}

send-key-surface

إرسال ضغطة مفتاح إلى سطح محدد.

CLI

icc send-key-surface --surface <id> enter

Socket

{"id":"send-key-surface","method":"surface.send_key","params":{"surface_id":"<id>","key":"enter"}}

أوامر الإشعارات

notify

إرسال إشعار.

CLI

icc notify --title "Title" --body "Body"
icc notify --title "T" --subtitle "S" --body "B"

Socket

{"id":"notify","method":"notification.create","params":{"title":"Title","subtitle":"S","body":"Body"}}

list-notifications

عرض جميع الإشعارات.

CLI

icc list-notifications
icc list-notifications --json

Socket

{"id":"notif-list","method":"notification.list","params":{}}

clear-notifications

مسح جميع الإشعارات.

CLI

icc clear-notifications

Socket

{"id":"notif-clear","method":"notification.clear","params":{}}

أوامر بيانات الشريط الجانبي الوصفية

تعيين مؤشرات الحالة وأشرطة التقدم وإدخالات السجل في الشريط الجانبي لأي مساحة عمل. مفيد لنصوص البناء وتكاملات CI ووكلاء البرمجة بالذكاء الاصطناعي التي تريد إظهار الحالة بنظرة سريعة.

set-status

تعيين مؤشر حالة في الشريط الجانبي. استخدم مفتاحاً فريداً حتى تتمكن الأدوات المختلفة من إدارة إدخالاتها الخاصة.

CLI

icc set-status build "compiling" --icon hammer --color "#ff9500"
icc set-status deploy "v1.2.3" --workspace workspace:2

Socket

set_status build compiling --icon=hammer --color=#ff9500 --tab=<workspace-uuid>

clear-status

إزالة إدخال حالة من الشريط الجانبي بالمفتاح.

CLI

icc clear-status build

Socket

clear_status build --tab=<workspace-uuid>

list-status

عرض جميع إدخالات حالة الشريط الجانبي لمساحة عمل.

CLI

icc list-status

Socket

list_status --tab=<workspace-uuid>

set-progress

تعيين شريط تقدم في الشريط الجانبي (0.0 إلى 1.0).

CLI

icc set-progress 0.5 --label "Building..."
icc set-progress 1.0 --label "Done"

Socket

set_progress 0.5 --label=Building... --tab=<workspace-uuid>

clear-progress

مسح شريط تقدم الشريط الجانبي.

CLI

icc clear-progress

Socket

clear_progress --tab=<workspace-uuid>

log

إضافة إدخال سجل إلى الشريط الجانبي. المستويات: info, progress, success, warning, error.

CLI

icc log "Build started"
icc log --level error --source build "Compilation failed"
icc log --level success -- "All 42 tests passed"

Socket

log --level=error --source=build --tab=<workspace-uuid> -- Compilation failed

clear-log

مسح جميع إدخالات سجل الشريط الجانبي.

CLI

icc clear-log

Socket

clear_log --tab=<workspace-uuid>

list-log

عرض إدخالات سجل الشريط الجانبي.

CLI

icc list-log
icc list-log --limit 5

Socket

list_log --limit=5 --tab=<workspace-uuid>

sidebar-state

تفريغ جميع بيانات الشريط الجانبي الوصفية (cwd، فرع git، المنافذ، الحالة، التقدم، السجلات).

CLI

icc sidebar-state
icc sidebar-state --workspace workspace:2

Socket

sidebar_state --tab=<workspace-uuid>

أوامر الأدوات المساعدة

ping

التحقق مما إذا كان icc يعمل ويستجيب.

CLI

icc ping

Socket

{"id":"ping","method":"system.ping","params":{}}
// Response: {"id":"ping","ok":true,"result":{"pong":true}}

capabilities

عرض طرق المقبس المتاحة ووضع الوصول الحالي.

CLI

icc capabilities
icc capabilities --json

Socket

{"id":"caps","method":"system.capabilities","params":{}}

identify

عرض سياق النافذة/مساحة العمل/اللوح/السطح المركز.

CLI

icc identify
icc identify --json

Socket

{"id":"identify","method":"system.identify","params":{}}

متغيرات البيئة

المتغير	الوصف
`ICC_SOCKET_PATH`	تجاوز مسار المقبس المستخدم بواسطة واجهة الأوامر والتكاملات
`ICC_SOCKET_ENABLE`	تفعيل/تعطيل المقبس قسرياً (1/0, true/false, on/off)
`ICC_SOCKET_MODE`	تجاوز وضع الوصول (iccOnly, allowAll, off). يقبل أيضاً icc-only/icc_only وallow-all/allow_all
`ICC_WORKSPACE_ID`	يُعين تلقائياً: معرف مساحة العمل الحالية
`ICC_SURFACE_ID`	يُعين تلقائياً: معرف السطح الحالي
`TERM_PROGRAM`	مُعين إلى ghostty
`TERM`	مُعين إلى xterm-ghostty

قيم ICC_SOCKET_MODE القديمة full وnotifications لا تزال مقبولة للتوافق.

كشف icc

bash

# Prefer explicit socket path if set
SOCK="${ICC_SOCKET_PATH:-/tmp/icc.sock}"
[ -S "$SOCK" ] && echo "Socket available"

# Check for the CLI
command -v icc &>/dev/null && echo "icc available"

# In icc-managed terminals these are auto-set
[ -n "${ICC_WORKSPACE_ID:-}" ] && [ -n "${ICC_SURFACE_ID:-}" ] && echo "Inside icc surface"

# Distinguish from regular Ghostty
[ "$TERM_PROGRAM" = "ghostty" ] && [ -n "${ICC_WORKSPACE_ID:-}" ] && echo "In icc"

أمثلة

عميل Python

python

import json
import os
import socket

SOCKET_PATH = os.environ.get("ICC_SOCKET_PATH", "/tmp/icc.sock")

def rpc(method, params=None, req_id=1):
    payload = {"id": req_id, "method": method, "params": params or {}}
    with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as sock:
        sock.connect(SOCKET_PATH)
        sock.sendall(json.dumps(payload).encode("utf-8") + b"\n")
        return json.loads(sock.recv(65536).decode("utf-8"))

# List workspaces
print(rpc("workspace.list", req_id="ws"))

# Send notification
print(rpc(
    "notification.create",
    {"title": "Hello", "body": "From Python!"},
    req_id="notify"
))

نص Shell

bash

#!/bin/bash
SOCK="${ICC_SOCKET_PATH:-/tmp/icc.sock}"

icc_cmd() {
    printf "%s\n" "$1" | nc -U "$SOCK"
}

icc_cmd '{"id":"ws","method":"workspace.list","params":{}}'
icc_cmd '{"id":"notify","method":"notification.create","params":{"title":"Done","body":"Task complete"}}'

نص بناء مع إشعار

bash

#!/bin/bash
npm run build
if [ $? -eq 0 ]; then
    icc notify --title "✓ Build Success" --body "Ready to deploy"
else
    icc notify --title "✗ Build Failed" --body "Check the logs"
fi