# Cmux Socket Policy

Socket command threading and focus policy for cmux CLI/socket work.

- Repository: https://github.com/manaflow-ai/cmux (28635 stars)
- Category: Engineering
- License: see repository
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add manaflow-ai/cmux --skill cmux-socket-policy -g -a claude-code -y`
Codex: `npx skills add manaflow-ai/cmux --skill cmux-socket-policy -g -a codex -y`
Cursor: `npx skills add manaflow-ai/cmux --skill cmux-socket-policy -g -a cursor -y`
Gemini CLI: `npx skills add manaflow-ai/cmux --skill cmux-socket-policy -g -a gemini-cli -y`

## Description

Socket command threading and focus policy for cmux CLI/socket work. Use when adding or changing socket commands, CLI commands, telemetry commands, focus/select/open/close/send-key behavior, or automation that could steal app focus.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# cmux Socket Policy

## Threading policy

- Do not use `DispatchQueue.main.sync` for high-frequency socket telemetry commands such as `report_*`, `ports_kick`, status/progress updates, or log metadata updates.
- For telemetry hot paths, parse and validate arguments off-main.
- Dedupe and coalesce off-main first.
- Schedule minimal UI/model mutation with `DispatchQueue.main.async` only when needed.
- Commands that directly manipulate AppKit/Ghostty UI state are allowed to run on the main actor.
- If adding a new socket command, default to off-main handling and require an explicit reason in code comments when main-thread execution is necessary.

## Focus policy

- Socket/CLI commands must not steal macOS app focus.
- Do not activate the app or raise windows unless the command has explicit focus intent.
- Only explicit focus-intent commands may mutate in-app focus/selection.
- Explicit focus-intent commands include `window.focus`, `workspace.select/next/previous/last`, `surface.focus`, `pane.focus/last`, browser focus commands, and v1 focus equivalents.
- All non-focus commands should preserve the current user focus context while still applying data/model changes.
- Open commands (`vm`/`cloud` shell, tui, open, new, base, workspace new/open, agent; `surface open`/`new-terminal`; `cmux open`; `cmux ssh`) focus only when run interactively and stay in the background when run by an agent or script (`defaultFocusForUserOpen`); `--focus` opts in, `--no-focus` opts out. Their socket methods default `focus` to false, and a pane opened without focus is marked unread.

## Remote relay authorization

Every v2 method is a potential `cmux ssh` relay payload. `RemoteRelayCommandPolicy` denies by default; allowlisting a method needs the security analysis and policy tests in [remote relay authorization](references/remote-relay-authorization.md).

## Detailed references

The rest: https://github.com/manaflow-ai/cmux/blob/HEAD/skills/cmux-socket-policy/SKILL.md