API Reference

imux provides both a compatibility CLI tool and a Unix socket for programmatic control. Every command is available through both interfaces.

Socket

Build	Path
Release	`/tmp/icc.sock`
Debug	`/tmp/icc-debug.sock`
Tagged debug build	`/tmp/icc-debug-<tag>.sock`

Override with the ICC_SOCKET_PATH environment variable. Send one newline-terminated JSON request per call:

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

JSON socket requests must use method and params. Legacy v1 JSON payloads such as {"command":"..."} are not supported.

Access modes

Mode	Description	How to enable
Off	Socket disabled	Settings UI or ICC_SOCKET_MODE=off
icc processes only	Only processes spawned inside imux terminals can connect.	Default mode in Settings UI
allowAll	Allow any local process to connect (no ancestry check).	Environment override only: ICC_SOCKET_MODE=allowAll

On shared machines, use Off or imux-managed processes only.

CLI options

Flag	Description
`--socket PATH`	Custom socket path
`--json`	Output in JSON format
`--window ID`	Target a specific window
`--workspace ID`	Target a specific workspace
`--surface ID`	Target a specific surface
`--id-format refs\|uuids\|both`	Control identifier format in JSON output

Workspace commands

list-workspaces

List all open workspaces.

CLI

icc list-workspaces
icc list-workspaces --json

Socket

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

new-workspace

Create a new workspace.

CLI

icc new-workspace

Socket

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

select-workspace

Switch to a specific workspace.

CLI

icc select-workspace --workspace <id>

Socket

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

current-workspace

Get the currently active workspace.

CLI

icc current-workspace
icc current-workspace --json

Socket

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

close-workspace

Close a workspace.

CLI

icc close-workspace --workspace <id>

Socket

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

Split commands

new-split

Create a new split pane. 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

List all surfaces in the current workspace.

CLI

icc list-surfaces
icc list-surfaces --json

Socket

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

focus-surface

Focus a specific surface.

CLI

icc focus-surface --surface <id>

Socket

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

Input commands

send

Send text input to the focused terminal.

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

Send a key press. Keys: 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

Send text to a specific 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

Send a key press to a specific surface.

CLI

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

Socket

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

Notification commands

notify

Send a 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

List all notifications.

CLI

icc list-notifications
icc list-notifications --json

Socket

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

clear-notifications

Clear all notifications.

CLI

icc clear-notifications

Socket

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

Sidebar metadata commands

Set status pills, progress bars, and log entries in the sidebar for any workspace. Useful for build scripts, CI integrations, and AI coding agents that want to surface state at a glance.

set-status

Set a sidebar status pill. Use a unique key so different tools can manage their own entries.

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

Remove a sidebar status entry by key.

CLI

icc clear-status build

Socket

clear_status build --tab=<workspace-uuid>

list-status

List all sidebar status entries for a workspace.

CLI

icc list-status

Socket

list_status --tab=<workspace-uuid>

set-progress

Set a progress bar in the sidebar (0.0 to 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

Clear the sidebar progress bar.

CLI

icc clear-progress

Socket

clear_progress --tab=<workspace-uuid>

log

Append a log entry to the sidebar. Levels: 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

Clear all sidebar log entries.

CLI

icc clear-log

Socket

clear_log --tab=<workspace-uuid>

list-log

List sidebar log entries.

CLI

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

Socket

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

sidebar-state

Dump all sidebar metadata (cwd, git branch, ports, status, progress, logs).

CLI

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

Socket

sidebar_state --tab=<workspace-uuid>

Utility commands

ping

Check if imux is running and responsive.

CLI

icc ping

Socket

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

capabilities

List available socket methods and current access mode.

CLI

icc capabilities
icc capabilities --json

Socket

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

identify

Show focused window/workspace/pane/surface context.

CLI

icc identify
icc identify --json

Socket

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

Environment variables

Variable	Description
`ICC_SOCKET_PATH`	Override the socket path used by CLI and integrations
`ICC_SOCKET_ENABLE`	Force-enable/disable socket (1/0, true/false, on/off)
`ICC_SOCKET_MODE`	Override access mode (iccOnly, allowAll, off). Also accepts icc-only/icc_only and allow-all/allow_all
`ICC_WORKSPACE_ID`	Auto-set: current workspace ID
`ICC_SURFACE_ID`	Auto-set: current surface ID
`TERM_PROGRAM`	Set to ghostty
`TERM`	Set to xterm-ghostty

Legacy ICC_SOCKET_MODE values full and notifications are still accepted for compatibility.

Detecting imux

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"

Examples

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 script

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 script with 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