API-Referenz

icc bietet sowohl ein CLI-Werkzeug als auch einen Unix-Socket für programmatische Steuerung. Jeder Befehl ist über beide Schnittstellen verfügbar.

Socket

Build	Pfad
Release	`/tmp/icc.sock`
Debug	`/tmp/icc-debug.sock`
Getaggter Debug-Build	`/tmp/icc-debug-<tag>.sock`

Überschreiben mit der Umgebungsvariable ICC_SOCKET_PATH. Senden Sie eine JSON-Anfrage pro Aufruf, mit Zeilenumbruch am Ende:

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

JSON-Socket-Anfragen müssen method und params verwenden. Legacy-v1-JSON-Payloads wie {"command":"..."} werden nicht unterstützt.

Zugriffsmodi

Modus	Beschreibung	Aktivierung
Off	Socket deaktiviert	Einstellungs-UI oder ICC_SOCKET_MODE=off
icc processes only	Nur Prozesse, die in icc-Terminals gestartet wurden, können sich verbinden.	Standardmodus in der Einstellungs-UI
allowAll	Jeden lokalen Prozess verbinden lassen (keine Herkunftsprüfung).	Nur per Umgebungsvariable: ICC_SOCKET_MODE=allowAll

Auf gemeinsam genutzten Rechnern verwenden Sie Aus oder Nur icc-Prozesse.

CLI-Optionen

Flag	Beschreibung
`--socket PATH`	Benutzerdefinierter Socket-Pfad
`--json`	Ausgabe im JSON-Format
`--window ID`	Ein bestimmtes Fenster ansprechen
`--workspace ID`	Einen bestimmten Workspace ansprechen
`--surface ID`	Eine bestimmte Oberfläche ansprechen
`--id-format refs\|uuids\|both`	ID-Format in der JSON-Ausgabe steuern

Workspace-Befehle

list-workspaces

Alle geöffneten Workspaces auflisten.

CLI

icc list-workspaces
icc list-workspaces --json

Socket

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

new-workspace

Einen neuen Workspace erstellen.

CLI

icc new-workspace

Socket

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

select-workspace

Zu einem bestimmten Workspace wechseln.

CLI

icc select-workspace --workspace <id>

Socket

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

current-workspace

Den aktuell aktiven Workspace abrufen.

CLI

icc current-workspace
icc current-workspace --json

Socket

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

close-workspace

Einen Workspace schließen.

CLI

icc close-workspace --workspace <id>

Socket

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

Split-Befehle

new-split

Einen neuen geteilten Bereich erstellen. Richtungen: left, right, up, down.

CLI

icc new-split right
icc new-split down

Socket

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

list-surfaces

Alle Oberflächen im aktuellen Workspace auflisten.

CLI

icc list-surfaces
icc list-surfaces --json

Socket

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

focus-surface

Eine bestimmte Oberfläche fokussieren.

CLI

icc focus-surface --surface <id>

Socket

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

Eingabebefehle

send

Texteingabe an das fokussierte Terminal senden.

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

Einen Tastendruck senden. Tasten: 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

Text an eine bestimmte Oberfläche senden.

CLI

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

Socket

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

send-key-surface

Einen Tastendruck an eine bestimmte Oberfläche senden.

CLI

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

Socket

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

Benachrichtigungsbefehle

notify

Eine Benachrichtigung senden.

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

Alle Benachrichtigungen auflisten.

CLI

icc list-notifications
icc list-notifications --json

Socket

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

clear-notifications

Alle Benachrichtigungen löschen.

CLI

icc clear-notifications

Socket

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

Seitenleisten-Metadaten-Befehle

Setzen Sie Status-Pills, Fortschrittsbalken und Log-Einträge in der Seitenleiste für jeden Workspace. Nützlich für Build-Skripte, CI-Integrationen und KI-Coding-Agenten, die den Status auf einen Blick anzeigen möchten.

set-status

Eine Seitenleisten-Status-Pill setzen. Verwenden Sie einen eindeutigen Schlüssel, damit verschiedene Werkzeuge ihre eigenen Einträge verwalten können.

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

Einen Seitenleisten-Status-Eintrag per Schlüssel entfernen.

CLI

icc clear-status build

Socket

clear_status build --tab=<workspace-uuid>

list-status

Alle Seitenleisten-Status-Einträge für einen Workspace auflisten.

CLI

icc list-status

Socket

list_status --tab=<workspace-uuid>

set-progress

Einen Fortschrittsbalken in der Seitenleiste setzen (0.0 bis 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

Den Seitenleisten-Fortschrittsbalken löschen.

CLI

icc clear-progress

Socket

clear_progress --tab=<workspace-uuid>

log

Einen Log-Eintrag zur Seitenleiste hinzufügen. Stufen: 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

Alle Seitenleisten-Log-Einträge löschen.

CLI

icc clear-log

Socket

clear_log --tab=<workspace-uuid>

list-log

Seitenleisten-Log-Einträge auflisten.

CLI

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

Socket

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

sidebar-state

Alle Seitenleisten-Metadaten ausgeben (cwd, Git-Branch, Ports, Status, Fortschritt, Logs).

CLI

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

Socket

sidebar_state --tab=<workspace-uuid>

Hilfsbefehle

ping

Prüfen, ob icc läuft und reagiert.

CLI

icc ping

Socket

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

capabilities

Verfügbare Socket-Methoden und aktuellen Zugriffsmodus auflisten.

CLI

icc capabilities
icc capabilities --json

Socket

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

identify

Fokussierten Fenster-/Workspace-/Bereichs-/Oberflächen-Kontext anzeigen.

CLI

icc identify
icc identify --json

Socket

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

Umgebungsvariablen

Variable	Beschreibung
`ICC_SOCKET_PATH`	Den von CLI und Integrationen verwendeten Socket-Pfad überschreiben
`ICC_SOCKET_ENABLE`	Socket aktivieren/deaktivieren erzwingen (1/0, true/false, on/off)
`ICC_SOCKET_MODE`	Zugriffsmodus überschreiben (iccOnly, allowAll, off). Akzeptiert auch icc-only/icc_only und allow-all/allow_all
`ICC_WORKSPACE_ID`	Automatisch gesetzt: Aktuelle Workspace-ID
`ICC_SURFACE_ID`	Automatisch gesetzt: Aktuelle Oberflächen-ID
`TERM_PROGRAM`	Gesetzt auf ghostty
`TERM`	Gesetzt auf xterm-ghostty

Legacy-Werte für ICC_SOCKET_MODE full und notifications werden aus Kompatibilitätsgründen weiterhin akzeptiert.

icc erkennen

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"

Beispiele

Python-Client

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-Skript

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"}}'

Build-Skript mit Benachrichtigung

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