Referencia de API

icc proporciona tanto una herramienta CLI como un socket Unix para control programático. Cada comando está disponible a través de ambas interfaces.

Socket

Build	Ruta
Release	`/tmp/icc.sock`
Debug	`/tmp/icc-debug.sock`
Build de debug etiquetado	`/tmp/icc-debug-<tag>.sock`

Sobrescriba con la variable de entorno ICC_SOCKET_PATH. Envíe una solicitud JSON terminada en salto de línea por llamada:

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

Las solicitudes JSON del socket deben usar method y params. Los payloads JSON legacy v1 como {"command":"..."} no son compatibles.

Modos de acceso

Modo	Descripción	Cómo habilitar
Off	Socket desactivado	UI de configuración o ICC_SOCKET_MODE=off
icc processes only	Solo los procesos iniciados dentro de terminales de icc pueden conectarse.	Modo predeterminado en la UI de configuración
allowAll	Permitir que cualquier proceso local se conecte (sin verificación de origen).	Solo por variable de entorno: ICC_SOCKET_MODE=allowAll

En máquinas compartidas, use Desactivado o Solo procesos de icc.

Opciones de CLI

Flag	Descripción
`--socket PATH`	Ruta de socket personalizada
`--json`	Salida en formato JSON
`--window ID`	Dirigirse a una ventana específica
`--workspace ID`	Dirigirse a un workspace específico
`--surface ID`	Dirigirse a una superficie específica
`--id-format refs\|uuids\|both`	Controlar el formato de identificador en la salida JSON

Comandos de workspace

list-workspaces

Listar todos los workspaces abiertos.

CLI

icc list-workspaces
icc list-workspaces --json

Socket

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

new-workspace

Crear un nuevo workspace.

CLI

icc new-workspace

Socket

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

select-workspace

Cambiar a un workspace específico.

CLI

icc select-workspace --workspace <id>

Socket

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

current-workspace

Obtener el workspace actualmente activo.

CLI

icc current-workspace
icc current-workspace --json

Socket

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

close-workspace

Cerrar un workspace.

CLI

icc close-workspace --workspace <id>

Socket

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

Comandos de división

new-split

Crear un nuevo panel dividido. Direcciones: 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

Listar todas las superficies en el workspace actual.

CLI

icc list-surfaces
icc list-surfaces --json

Socket

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

focus-surface

Enfocar una superficie específica.

CLI

icc focus-surface --surface <id>

Socket

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

Comandos de entrada

send

Enviar texto al terminal enfocado.

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

Enviar una pulsación de tecla. Teclas: 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

Enviar texto a una superficie específica.

CLI

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

Socket

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

send-key-surface

Enviar una pulsación de tecla a una superficie específica.

CLI

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

Socket

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

Comandos de notificación

notify

Enviar una notificación.

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

Listar todas las notificaciones.

CLI

icc list-notifications
icc list-notifications --json

Socket

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

clear-notifications

Borrar todas las notificaciones.

CLI

icc clear-notifications

Socket

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

Comandos de metadatos de la barra lateral

Establezca indicadores de estado, barras de progreso y entradas de registro en la barra lateral para cualquier workspace. Útil para scripts de compilación, integraciones de CI y agentes de programación con IA que quieran mostrar el estado de un vistazo.

set-status

Establecer un indicador de estado en la barra lateral. Use una clave única para que diferentes herramientas puedan gestionar sus propias entradas.

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

Eliminar una entrada de estado de la barra lateral por clave.

CLI

icc clear-status build

Socket

clear_status build --tab=<workspace-uuid>

list-status

Listar todas las entradas de estado de la barra lateral para un workspace.

CLI

icc list-status

Socket

list_status --tab=<workspace-uuid>

set-progress

Establecer una barra de progreso en la barra lateral (0.0 a 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

Borrar la barra de progreso de la barra lateral.

CLI

icc clear-progress

Socket

clear_progress --tab=<workspace-uuid>

log

Añadir una entrada de registro a la barra lateral. Niveles: 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

Borrar todas las entradas de registro de la barra lateral.

CLI

icc clear-log

Socket

clear_log --tab=<workspace-uuid>

list-log

Listar las entradas de registro de la barra lateral.

CLI

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

Socket

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

sidebar-state

Volcar todos los metadatos de la barra lateral (cwd, rama de git, puertos, estado, progreso, registros).

CLI

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

Socket

sidebar_state --tab=<workspace-uuid>

Comandos de utilidad

ping

Verificar si icc está ejecutándose y responde.

CLI

icc ping

Socket

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

capabilities

Listar los métodos de socket disponibles y el modo de acceso actual.

CLI

icc capabilities
icc capabilities --json

Socket

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

identify

Mostrar el contexto de ventana/workspace/panel/superficie enfocados.

CLI

icc identify
icc identify --json

Socket

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

Variables de entorno

Variable	Descripción
`ICC_SOCKET_PATH`	Sobrescribir la ruta del socket utilizada por la CLI e integraciones
`ICC_SOCKET_ENABLE`	Forzar la activación/desactivación del socket (1/0, true/false, on/off)
`ICC_SOCKET_MODE`	Sobrescribir el modo de acceso (iccOnly, allowAll, off). También acepta icc-only/icc_only y allow-all/allow_all
`ICC_WORKSPACE_ID`	Establecido automáticamente: ID del workspace actual
`ICC_SURFACE_ID`	Establecido automáticamente: ID de la superficie actual
`TERM_PROGRAM`	Establecido en ghostty
`TERM`	Establecido en xterm-ghostty

Los valores legacy de ICC_SOCKET_MODE full y notifications siguen siendo aceptados por compatibilidad.

Detectar 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"

Ejemplos

Cliente 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 de 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 compilación con notificación

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