Referência da API

O icc oferece uma ferramenta CLI e um socket Unix para controle programático. Cada comando está disponível através de ambas as interfaces.

Socket

Build	Caminho
Release	`/tmp/icc.sock`
Debug	`/tmp/icc-debug.sock`
Build de debug com tag	`/tmp/icc-debug-<tag>.sock`

Substitua com a variável de ambiente ICC_SOCKET_PATH. Envie uma requisição JSON terminada em nova linha por chamada:

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

Requisições JSON via socket devem usar method e params. Payloads JSON legados v1 como {"command":"..."} não são suportados.

Modos de acesso

Modo	Descrição	Como ativar
Off	Socket desativado	Interface de Configurações ou ICC_SOCKET_MODE=off
icc processes only	Apenas processos iniciados dentro dos terminais do icc podem se conectar.	Modo padrão na interface de Configurações
allowAll	Permitir qualquer processo local se conectar (sem verificação de ancestralidade).	Apenas por variável de ambiente: ICC_SOCKET_MODE=allowAll

Em máquinas compartilhadas, use Desligado ou apenas processos icc.

Opções da CLI

Flag	Descrição
`--socket PATH`	Caminho de socket personalizado
`--json`	Saída em formato JSON
`--window ID`	Direcionar uma janela específica
`--workspace ID`	Direcionar um workspace específico
`--surface ID`	Direcionar uma superfície específica
`--id-format refs\|uuids\|both`	Controlar formato de identificador na saída JSON

Comandos de workspace

list-workspaces

Listar todos os workspaces abertos.

CLI

icc list-workspaces
icc list-workspaces --json

Socket

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

new-workspace

Criar um novo workspace.

CLI

icc new-workspace

Socket

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

select-workspace

Alternar para um workspace específico.

CLI

icc select-workspace --workspace <id>

Socket

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

current-workspace

Obter o workspace atualmente ativo.

CLI

icc current-workspace
icc current-workspace --json

Socket

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

close-workspace

Fechar um workspace.

CLI

icc close-workspace --workspace <id>

Socket

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

Comandos de divisão

new-split

Criar um novo painel dividido. Direções: 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 as superfícies no workspace atual.

CLI

icc list-surfaces
icc list-surfaces --json

Socket

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

focus-surface

Focar uma superfície 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 para o terminal focado.

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 uma 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 para uma superfície 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 uma tecla para uma superfície 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 notificação

notify

Enviar uma notificação.

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 as notificações.

CLI

icc list-notifications
icc list-notifications --json

Socket

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

clear-notifications

Limpar todas as notificações.

CLI

icc clear-notifications

Socket

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

Comandos de metadados da barra lateral

Definir indicadores de status, barras de progresso e entradas de log na barra lateral para qualquer workspace. Útil para scripts de build, integrações de CI e agentes de código com IA que querem exibir estado rapidamente.

set-status

Definir um indicador de status na barra lateral. Use uma chave única para que diferentes ferramentas possam gerenciar suas próprias 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

Remover uma entrada de status da barra lateral por chave.

CLI

icc clear-status build

Socket

clear_status build --tab=<workspace-uuid>

list-status

Listar todas as entradas de status da barra lateral para um workspace.

CLI

icc list-status

Socket

list_status --tab=<workspace-uuid>

set-progress

Definir uma barra de progresso na 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

Limpar a barra de progresso da barra lateral.

CLI

icc clear-progress

Socket

clear_progress --tab=<workspace-uuid>

log

Adicionar uma entrada de log à barra lateral. Níveis: 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

Limpar todas as entradas de log da barra lateral.

CLI

icc clear-log

Socket

clear_log --tab=<workspace-uuid>

list-log

Listar entradas de log da barra lateral.

CLI

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

Socket

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

sidebar-state

Exportar todos os metadados da barra lateral (cwd, branch git, portas, status, progresso, logs).

CLI

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

Socket

sidebar_state --tab=<workspace-uuid>

Comandos utilitários

ping

Verificar se o icc está rodando e respondendo.

CLI

icc ping

Socket

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

capabilities

Listar métodos de socket disponíveis e modo de acesso atual.

CLI

icc capabilities
icc capabilities --json

Socket

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

identify

Mostrar contexto da janela/workspace/painel/superfície focados.

CLI

icc identify
icc identify --json

Socket

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

Variáveis de ambiente

Variável	Descrição
`ICC_SOCKET_PATH`	Substituir o caminho do socket usado pela CLI e integrações
`ICC_SOCKET_ENABLE`	Forçar ativação/desativação do socket (1/0, true/false, on/off)
`ICC_SOCKET_MODE`	Substituir modo de acesso (iccOnly, allowAll, off). Também aceita icc-only/icc_only e allow-all/allow_all
`ICC_WORKSPACE_ID`	Definido automaticamente: ID do workspace atual
`ICC_SURFACE_ID`	Definido automaticamente: ID da superfície atual
`TERM_PROGRAM`	Definido como ghostty
`TERM`	Definido como xterm-ghostty

Valores legados de ICC_SOCKET_MODE full e notifications ainda são aceitos para compatibilidade.

Detectando o 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"

Exemplos

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 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 com notificação

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