Cmux Socket Policy
- 2.5k installs
- 25.6k repo stars
- Updated August 5, 2026
- manaflow-ai/cmux
cmux-socket-policy is a cmux agent skill that defines WebSocket and CLI threading and macOS focus rules for developers adding socket commands that must not block the UI or steal app focus.
About
cmux-socket-policy is a manaflow-ai/cmux agent skill that governs socket and CLI command threading and macOS focus behavior for the cmux agent terminal. Telemetry hot paths such as report_*, ports_kick, status, progress, and log metadata must parse and dedupe off the main thread, scheduling UI mutations only via DispatchQueue.main.async, while AppKit and Ghostty UI commands may run on the main actor with explicit justification. Socket and CLI commands must not activate the app or raise windows unless they are explicit focus-intent commands like window.focus, workspace.select, surface.focus, pane.focus, or browser focus equivalents. New commands default to off-main handling. Reach for cmux-socket-policy when adding socket commands, telemetry automation, or CLI features that could block the main thread or interrupt a developer's active focus context.
- WebSocket auth on connect
- Reconnection and backoff rules
- Message schema enforcement
- Rate limit and shutdown policy
Cmux Socket Policy by the numbers
- 2,508 all-time installs (skills.sh)
- +300 installs in the week ending Aug 5, 2026 (Skillselion tracking)
- Ranked #216 of 4,347 Backend & APIs skills by installs in the Skillselion catalog
- Data as of Aug 5, 2026 (Skillselion catalog sync)
npx skills add https://github.com/manaflow-ai/cmux --skill cmux-socket-policyAdd your badge
Show developers this skill is listed on Skillselion. Paste this into your README.
| Installs | 2.5k |
|---|---|
| repo stars | ★ 25.6k |
| Last updated | August 5, 2026 |
| Repository | manaflow-ai/cmux ↗ |
How do you add cmux socket commands without stealing focus?
Implement cmux WebSocket connection rules: auth, reconnection, rate limits, message schemas, and graceful shutdown handling.
Who is it for?
cmux contributors adding WebSocket or CLI commands, telemetry automation, or agent-driven terminal control that must avoid main-thread blocking and macOS focus theft.
Skip if: Skip cmux-socket-policy when editing cmux backend Postgres routes, Ghostty xcframework builds, or frontend-only UI with no socket or CLI command surface.
When should I use this skill?
User adds or changes cmux socket commands, CLI automation, telemetry report_* handlers, or focus/select/open/send-key behavior.
What you get
Off-main telemetry command handlers, focus-intent command allowlist, threading justification comments, and preserved user focus for non-focus socket operations.
- off-main telemetry handler
- focus-intent command classification
- threading justification comments
By the numbers
- Documents 2 policy areas: threading policy and macOS focus policy
- Lists 8+ explicit focus-intent command families including window.focus and workspace.select
- Includes threading-and-focus.md reference for command execution rules
Files
cmux Socket Policy
Threading policy
- Do not use
DispatchQueue.main.syncfor high-frequency socket telemetry commands such asreport_*,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.asynconly 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.
Detailed reference
- Read references/threading-and-focus.md when adding a command, changing command execution context, or deciding whether focus changes are allowed.
interface:
display_name: "cmux Socket Policy"
short_description: "Keep cmux socket commands off hot main-thread paths and focus-safe."
default_prompt: "Use this skill when adding or changing cmux socket or CLI commands, telemetry handlers, focus/select/open/close/send-key behavior, or automation that could activate the app or steal focus."
Socket Threading and Focus
Socket commands are a control plane. They often run because an agent, script, or background tool is reporting state, not because a user asked the app to become active.
Telemetry hot paths
High-frequency telemetry commands include:
report_*ports_kick- status updates
- progress updates
- log metadata updates
These should avoid synchronous main-thread work. Parse and validate arguments off-main, dedupe/coalesce before crossing to UI state, and schedule only the smallest required mutation.
DispatchQueue.main.sync is especially risky because it can block the socket handling path behind UI work and can deadlock if the command path is already main-adjacent.
Commands allowed on main actor
Commands that directly manipulate AppKit or Ghostty UI state may need main actor execution:
- focus
- select
- open/close UI surfaces
- send key/input
- list/current queries requiring an exact synchronous UI snapshot
The command should document why main-thread execution is necessary. Do not cargo-cult main actor isolation onto telemetry commands.
Focus preservation
Most socket commands should not change the user's macOS focus. A background agent may be running in one workspace while the user is actively using another app or cmux workspace.
Non-focus commands should apply model/data changes without:
- activating the app
- raising a window
- selecting another workspace
- focusing a pane
- focusing a surface
If a command needs focus behavior, name and document it as focus-intent.
Explicit focus-intent commands
Only explicit focus-intent commands may mutate in-app focus/selection. Examples:
window.focusworkspace.selectworkspace.nextworkspace.previousworkspace.lastsurface.focuspane.focuspane.last- browser focus commands
- v1 focus equivalents
When adding a new command, decide whether it is focus-intent as part of the API contract, not as an implementation accident.
Related skills
Lark Openapi ExplorerInstantly explore, test, and generate calls against the full Lark (Feishu) OpenAPI surface without leaving their agent workflow.493k
Lark EventConsume real-time events from Lark/Feishu as structured NDJSON streams inside AI agent workflows.387k16kLark Openapi ExplorerWhen an existing Lark/Feishu skill or CLI command cannot fulfill a specific requirement and they need to discover and invoke the exact native OpenAPI endpoint.386k16k
Just ScrapeQuickly search, crawl, extract structured JSON, or monitor web pages without writing custom scraping code.245k41Lark AppsQuery the current visibility and permission scope of a Lark (Feishu) app without writing HTTP client code.235k16k
Design An InterfaceGenerate multiple radically different interface or API designs in parallel before committing to one.188k198kHow it compares
Use cmux-socket-policy over generic WebSocket guides when cmux-specific telemetry threading and macOS focus-intent allowlists must be enforced for agent automation.
FAQ
Which cmux socket commands must run off the main thread?
cmux-socket-policy requires off-main handling for high-frequency telemetry commands such as report_*, ports_kick, status, progress, and log metadata, parsing and deduping off-main and using DispatchQueue.main.async only for minimal UI updates.
Which cmux commands may change app focus?
cmux-socket-policy allowlists explicit focus-intent commands including window.focus, workspace.select/next/previous/last, surface.focus, pane.focus/last, browser focus commands, and v1 focus equivalents; all other socket and CLI commands must preserve current focus.
What is required when adding a new cmux socket command?
cmux-socket-policy defaults new socket commands to off-main handling and requires an explicit code-comment reason when main-thread or main-actor execution is necessary for direct AppKit or Ghostty UI manipulation.