cmux-workspace

Scopes cmux CLI automation to the caller workspace, panes, surfaces, and socket.

4.0k|282|Updated Dec 2, 2024
One-click install
npx skills add https://github.com/basicmachines-co/basic-memory --skill cmux-workspace-basicmachines-co
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: cmux-workspace
Source: https://github.com/basicmachines-co/basic-memory/tree/main/.agents/skills/cmux-workspace
Command: npx skills add https://github.com/basicmachines-co/basic-memory --skill cmux-workspace-basicmachines-co

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? When an AI agent runs inside a cmux terminal, it can accidentally act on the wrong workspace, steal the user's focus, or disrupt the layout the user is looking at. This Skill anchors every cmux command to the workspace and surface that invoked the agent, so automation stays non-disruptive and auditable. ## Core Features & Use Cases - Caller-scoped automation: Resolves the current workspace and surface via CMUX_WORKSPACE_ID, CMUX_SURFACE_ID, and cmux identify, then targets all mutations with explicit --workspace and --surface flags. - Non-disruptive layout building: Creates panes and surfaces additively with new-pane and new-surface, passing --focus false and avoiding focus-changing verbs like select-workspace or focus-pane. - Sidebar status and logging: Attaches status, progress bars, and log entries to the current workspace so the sidebar reflects the running task. - Use Case: While running a dev server, ask the agent to open a browser preview in a right-side helper pane and post build progress to the sidebar, all without moving your cursor or switching your active tab. ## Quick Start Ask the agent to identify the current cmux workspace and open a browser preview of localhost:3000 in a right-side pane without changing focus.

Frequently Asked Questions about cmux-workspace

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I target the current cmux workspace from an agent?▼

Read the CMUX_WORKSPACE_ID and CMUX_SURFACE_ID environment variables, or run cmux identify --json as a fallback. Then pass explicit --workspace and --surface flags on every mutating command so the automation is auditable.

How to open a browser pane in cmux without stealing focus?▼

Use cmux new-pane --workspace "$CMUX_WORKSPACE_ID" --type browser --direction right --url <url> to build the layout additively. Pass --focus false on creation and move verbs so the user's attention stays where it is.

Can cmux commands affect other workspaces or windows?▼

They can, but this Skill forbids it unless the user explicitly names another target. Never send keystrokes, close surfaces, or change focus in a workspace the user did not specify.

Why does drag-surface-to-split fail with Surface not found?▼

drag-surface-to-split routes through V1 and resolves the workspace via UI focus, so it fails when the caller workspace is not visually focused. Build layout additively with new-pane instead, and never recover by calling focus-pane.

How do I show build progress in the cmux sidebar?▼

Use cmux set-status, cmux set-progress, and cmux log with an explicit --workspace flag to attach status, progress, and log entries to the current workspace. Query the result with cmux sidebar-state --json.