Référence API

icc fournit à la fois un outil CLI et un socket Unix pour le contrôle programmatique. Chaque commande est disponible via les deux interfaces.

Socket

Build	Chemin
Release	`/tmp/icc.sock`
Debug	`/tmp/icc-debug.sock`
Build debug tagué	`/tmp/icc-debug-<tag>.sock`

Remplacez avec la variable d'environnement ICC_SOCKET_PATH. Envoyez une requête JSON terminée par un retour à la ligne par appel :

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

Les requêtes JSON du socket doivent utiliser method et params. Les anciens payloads JSON v1 comme {"command":"..."} ne sont pas supportés.

Modes d'accès

Mode	Description	Comment activer
Off	Socket désactivé	Interface Réglages ou ICC_SOCKET_MODE=off
icc processes only	Seuls les processus démarrés dans les terminaux icc peuvent se connecter.	Mode par défaut dans l'interface Réglages
allowAll	Autoriser tout processus local à se connecter (pas de vérification d'ascendance).	Remplacement par variable d'environnement uniquement : ICC_SOCKET_MODE=allowAll

Sur les machines partagées, utilisez Désactivé ou Processus icc uniquement.

Options du CLI

Option	Description
`--socket PATH`	Chemin de socket personnalisé
`--json`	Sortie au format JSON
`--window ID`	Cibler une fenêtre spécifique
`--workspace ID`	Cibler un espace de travail spécifique
`--surface ID`	Cibler une surface spécifique
`--id-format refs\|uuids\|both`	Format d'identifiant de contrôle dans la sortie JSON

Commandes d'espace de travail

list-workspaces

Lister tous les espaces de travail ouverts.

CLI

icc list-workspaces
icc list-workspaces --json

Socket

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

new-workspace

Créer un nouvel espace de travail.

CLI

icc new-workspace

Socket

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

select-workspace

Basculer vers un espace de travail spécifique.

CLI

icc select-workspace --workspace <id>

Socket

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

current-workspace

Obtenir l'espace de travail actuellement actif.

CLI

icc current-workspace
icc current-workspace --json

Socket

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

close-workspace

Fermer un espace de travail.

CLI

icc close-workspace --workspace <id>

Socket

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

Commandes de division

new-split

Créer un nouveau panneau divisé. Directions : 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

Lister toutes les surfaces dans l'espace de travail actuel.

CLI

icc list-surfaces
icc list-surfaces --json

Socket

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

focus-surface

Mettre le focus sur une surface spécifique.

CLI

icc focus-surface --surface <id>

Socket

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

Commandes de saisie

send

Envoyer du texte au terminal actif.

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

Envoyer une touche. Touches : 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

Envoyer du texte à une surface spécifique.

CLI

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

Socket

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

send-key-surface

Envoyer une touche à une surface spécifique.

CLI

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

Socket

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

Commandes de notification

notify

Envoyer une notification.

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

Lister toutes les notifications.

CLI

icc list-notifications
icc list-notifications --json

Socket

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

clear-notifications

Effacer toutes les notifications.

CLI

icc clear-notifications

Socket

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

Commandes de métadonnées de la barre latérale

Définir des pastilles de statut, barres de progression et entrées de journal dans la barre latérale pour n'importe quel espace de travail. Utile pour les scripts de build, intégrations CI et agents de code IA qui souhaitent afficher l'état en un coup d'œil.

set-status

Définir une pastille de statut dans la barre latérale. Utilisez une clé unique pour que différents outils puissent gérer leurs propres entrées.

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

Supprimer une entrée de statut de la barre latérale par clé.

CLI

icc clear-status build

Socket

clear_status build --tab=<workspace-uuid>

list-status

Lister toutes les entrées de statut de la barre latérale pour un espace de travail.

CLI

icc list-status

Socket

list_status --tab=<workspace-uuid>

set-progress

Définir une barre de progression dans la barre latérale (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

Effacer la barre de progression de la barre latérale.

CLI

icc clear-progress

Socket

clear_progress --tab=<workspace-uuid>

log

Ajouter une entrée de journal à la barre latérale. Niveaux : 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

Effacer toutes les entrées de journal de la barre latérale.

CLI

icc clear-log

Socket

clear_log --tab=<workspace-uuid>

list-log

Lister les entrées de journal de la barre latérale.

CLI

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

Socket

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

sidebar-state

Afficher toutes les métadonnées de la barre latérale (cwd, branche git, ports, statut, progression, journaux).

CLI

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

Socket

sidebar_state --tab=<workspace-uuid>

Commandes utilitaires

ping

Vérifier si icc fonctionne et répond.

CLI

icc ping

Socket

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

capabilities

Lister les méthodes socket disponibles et le mode d'accès actuel.

CLI

icc capabilities
icc capabilities --json

Socket

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

identify

Afficher le contexte fenêtre/espace de travail/panneau/surface actif.

CLI

icc identify
icc identify --json

Socket

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

Variables d'environnement

Variable	Description
`ICC_SOCKET_PATH`	Remplacer le chemin du socket utilisé par le CLI et les intégrations
`ICC_SOCKET_ENABLE`	Forcer l'activation/désactivation du socket (1/0, true/false, on/off)
`ICC_SOCKET_MODE`	Remplacer le mode d'accès (iccOnly, allowAll, off). Accepte aussi icc-only/icc_only et allow-all/allow_all
`ICC_WORKSPACE_ID`	Auto-défini : ID de l'espace de travail actuel
`ICC_SURFACE_ID`	Auto-défini : ID de la surface actuelle
`TERM_PROGRAM`	Défini à ghostty
`TERM`	Défini à xterm-ghostty

Les anciennes valeurs ICC_SOCKET_MODE full et notifications sont toujours acceptées pour compatibilité.

Détecter 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"

Exemples

Client 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"
))

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

Script de build avec notification

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