New: 98,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Agent skill

cmux Workspace Scoping

by basicmachines-co in basicmachines-co/basic-memory

Keeps agent actions scoped to the cmux workspace and terminal that invoked it, and lays out pane and surface commands that avoid disrupting the user's own focus.

AGPL-3.0Auto-check passedProductivity & Automation

Install cmux Workspace Scoping

skills CLI
$ npx skills add basicmachines-co/basic-memory --skill cmux-workspace -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install basicmachines-co/basic-memory cmux-workspace --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/basicmachines-co/basic-memory.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.agents/skills/cmux-workspace .claude/skills/cmux-workspace && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
cmux-workspace
GitHub stars
4.1k
Used in
2 other repos
Token cost
~1.7k tokens
SKILL.md length
681 words
Files
3 (incl. references)
Skills in repo
49
Repo updated
First seen
Licence
AGPL-3.0

At a glance

Keeps agent actions scoped to the cmux workspace and terminal that invoked it, and lays out pane and surface commands that avoid disrupting the user's own focus.

  • Opening a terminal or browser pane without disturbing the user's current focus
  • SKILL.md covers Default rule, Non-disruptive automation, Right-side helper pane and Caller terminal, plus 6 more sections
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md
  • Running an automation scoped to the workspace that invoked the agent

What it does

The skill defines cmux's vocabulary (window, workspace, pane, surface, panel) and sets a default rule: scope actions to the caller's own workspace unless the user explicitly asks for another one, since an agent can be running in a workspace the user isn't currently looking at. It reads CMUX_WORKSPACE_ID, CMUX_SURFACE_ID and CMUX_SOCKET_PATH from the environment, falling back to cmux identify when they are missing and saying explicitly that the currently focused context is being used.

Layout and focus are treated as separate concerns: commands that change focus, like select-workspace or focus-pane, are described as user-affecting actions akin to clicks and are never called speculatively. The agent is told to build a layout additively in one shot with commands that create a pane already populated with the right surface, pass a focus-preserving flag wherever a verb supports it, and reuse one right-side helper pane for auxiliary output such as preview apps or logs rather than spawning new panes freely.

When your agent uses it

  • Opening a terminal or browser pane without disturbing the user's current focus
  • Running an automation scoped to the workspace that invoked the agent
  • Reusing a helper pane for preview output instead of creating new panes

Example prompts

  • “Open a browser pane showing localhost:8765 next to my terminal without changing my focus.”
  • “Identify which cmux workspace and surface I'm currently running in.”
  • “Reuse the helper pane to show the dev server logs.”

Requirements

  • The cmux CLI with CMUX_WORKSPACE_ID and related environment variables set

What it can do on your machine

Read from SKILL.md and the folder at commit cb7407f. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md (its code samples are bash).

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    Links to these hosts (documentation or services it may open):

    • github.com

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

cmux Workspace Scoping loads about 1.7k tokens when it runs, and up to ~2.5k if it reads all its reference files. Until then it costs about 50 tokens; SKILL.md has 681 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~50
When it runs · the whole SKILL.md, loaded when a task matches
~1.7k
With references · SKILL.md plus every file in references/, read only if the agent opens them
~2.5k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from basicmachines-co/basic-memory at commit cb7407f, republished under its AGPL-3.0 licence (© basicmachines-co). 681 words, ~1,665 tokens.

Download SKILL.mdSave it as .claude/skills/cmux-workspace/SKILL.md (or your agent's skills folder). This skill also uses 2 other files; get the full folder from GitHub.
name
cmux-workspace
description
Work inside the current cmux workspace and terminal. Use for cmux workspace, current workspace, caller surface, panes, surfaces, socket targeting, and non-interfering cmux automation.

cmux Workspace

Scope work to the cmux workspace that invoked the agent.

  • Window: a macOS cmux window.
  • Workspace: a sidebar entry. The UI calls it a tab; CLI/socket APIs call it a workspace.
  • Pane: a split region inside a workspace.
  • Surface: a tab inside a pane, terminal or browser.
  • Panel: internal content type inside a surface. Prefer CLI surface commands over panel internals.

Default rule

Scope actions to the current caller workspace unless the user explicitly asks for another workspace, another window, or global state. Do not assume the visually focused workspace is the right target: an agent can run in one workspace while the user looks at another.

bash
printf 'workspace=%s\nsurface=%s\nsocket=%s\n' \
  "${CMUX_WORKSPACE_ID:-}" "${CMUX_SURFACE_ID:-}" "${CMUX_SOCKET_PATH:-}"
cmux identify --json

CMUX_WORKSPACE_ID is the default workspace anchor and CMUX_SURFACE_ID the default caller terminal anchor. If they are missing, fall back to cmux identify --json and say explicitly that you are using the currently focused context.

Non-disruptive automation

Treat layout and focus as separate concerns. select-workspace, focus-pane, focus-panel, and focus-changing tab-action verbs are user-affecting actions, like clicks. Never call them speculatively, even inside the caller's own workspace, since the user may be looking elsewhere.

Build layout additively in one shot, using commands that create a pane already populated with the right surface:

bash
cmux new-pane --workspace "${CMUX_WORKSPACE_ID}" --type browser --direction right --url "http://127.0.0.1:8765"
cmux new-pane --workspace "${CMUX_WORKSPACE_ID}" --type terminal --direction down

Avoid create-then-move-then-focus chains. Pass --focus false wherever the verb supports it (move-surface --focus false preserves the user's attention; more commands may grow the flag, see https://github.com/manaflow-ai/cmux/issues/1418 and https://github.com/manaflow-ai/cmux/issues/2820). If a layout command rejects a valid surface: or pane: ref, report the bug and stop rather than working around it by focusing.

Right-side helper pane

For auxiliary output (preview apps, TUIs, logs, one-off shells, browser checks), reuse one helper pane to the right of the caller terminal. Inspect first with cmux identify --json, cmux list-panes, and cmux list-pane-surfaces, then:

  • Helper pane exists: add a surface to it.
    bash
    cmux new-surface --workspace "${CMUX_WORKSPACE_ID:-}" --pane pane:<helper> --type terminal --focus false
  • No helper pane: create exactly one.
    bash
    cmux new-pane --workspace "${CMUX_WORKSPACE_ID:-}" --type terminal --direction right --focus false
  • Multiple obvious stale helper panes from this same automation, and the user asked to tidy: keep one and clean up duplicates. Never close a pane you cannot confidently identify as stale helper output.

Send commands to the new or reused surface by explicit surface ref. Repeated "open it" requests create tabs inside the existing right helper pane, not more splits.

Caller terminal

The surface that invoked the agent is the safest anchor for relative operations.

bash
cmux send "npm test\n"                                    # focused terminal in caller workspace
cmux send --surface "${CMUX_SURFACE_ID:-}" "git status\n"  # exact caller surface
cmux send-key --surface "${CMUX_SURFACE_ID:-}" enter

Do not send keystrokes, close surfaces, or change focus in another workspace unless the user named that target.

Show full SKILL.md (287 more words)Show less

Moving surfaces

bash
cmux move-surface --surface "${CMUX_SURFACE_ID}" --before surface:3   # also --after, --index
cmux move-surface --surface surface:240 --pane pane:172 --focus false
cmux drag-surface-to-split --surface surface:240 down

Known papercut: drag-surface-to-split routes through V1 and resolves the workspace via UI focus, so it fails with ERROR: Surface not found when the caller's workspace is not the visually focused one (https://github.com/manaflow-ai/cmux/issues/1901, related https://github.com/manaflow-ai/cmux/issues/3189). Until that lands, build layout additively. Never call focus-pane or focus-panel to recover from a failed move; report the failure and stop.

Sidebar state

Attach status, progress, and logs to the current workspace so the sidebar reflects this task.

bash
cmux set-status build "running" --workspace "${CMUX_WORKSPACE_ID:-}" --color "#ff9500"
cmux set-progress 0.4 --label "Building" --workspace "${CMUX_WORKSPACE_ID:-}"
cmux log --workspace "${CMUX_WORKSPACE_ID:-}" --level info -- "Started build"
cmux sidebar-state --workspace "${CMUX_WORKSPACE_ID:-}" --json

Contributor reloads

For cmux app/runtime changes in a cmux source checkout, use a tagged reload from the active worktree. It creates an isolated app name, bundle ID, debug socket, and DerivedData path. Never build or launch untagged cmux DEV.

bash
./scripts/reload.sh --tag <short-tag>
CMUX_SOCKET_PATH=/tmp/cmux-debug-<short-tag>.sock cmux identify --json

Socket access

Use the socket path cmux provided before any default: SOCK="${CMUX_SOCKET_PATH:-/tmp/cmux.sock}". Socket access can be off, restricted to cmux-spawned processes, or open to all local processes. If a command cannot connect, inspect cmux capabilities --json and cmux ping before changing settings.

Rules

  • Work in the caller workspace by default; prefer explicit --workspace and --surface flags for mutating actions even when env vars are set, so automation is auditable.
  • Never call focus-pane, focus-panel, select-workspace, or focus-changing tab-action verbs unless the user explicitly asked.
  • Pass --focus false on move-surface and any creation verb that supports it.
  • Build layout additively with new-pane --type ... --url ..., not create-then-move-then-focus.
  • If a CLI command rejects a valid surface or pane ref, report it. Do not work around by focusing.
  • Do not close, focus, move, or send input to another workspace unless the user names that target.
  • Use short refs in chat and examples; UUIDs only for logs, persistence, or debugging.

References

© basicmachines-co, AGPL-3.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 2 other files (references) in .agents/skills/cmux-workspace of basicmachines-co/basic-memory.

  • SKILL.md
  • agents/openai.yaml
  • references/commands.md

Open the folder on GitHubat commit cb7407f

Used in 2 other repositories

We found 2 copies of this SKILL.md (exact, near-identical or edited) in other folders, from 2 other GitHub owners. This page covers the copy in basicmachines-co/basic-memory, which our catalogue first saw on October 7, 2026.

Compare with similar skills

cmux Workspace Scoping next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

cmux Workspace Scoping compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
cmux Workspace Scoping this skillbasicmachines-co/basic-memory4.1k2 repos~1.7kAutomated safety check: PassAGPL-3.0
Skyvern Browser AutomationSkyvern-AI/skyvern23k1 repos~2.9kAutomated safety check: PassAGPL-3.0
N8n CLIn8n-io/n8n207k—~3kAutomated safety check: PassCustom licence
CUAWright Web Task Automationmicrosoft/CUAWright6k—~2kAutomated safety check: NotesMIT
Skyvern Browser AutomationSkyvern-AI/skyvern23k—~1.9kAutomated safety check: PassAGPL-3.0
Piece Builderactivepieces/activepieces25k—~3.1kAutomated safety check: NotesCustom licence

Similar skills

  • Skyvern Browser Automation

    Skyvern-AI/skyvern

    Picks the right Skyvern CLI command for a web task, from quick yes/no checks to reusable multi-page workflows, instead of falling back to plain page fetching.

    23k GitHub starsUsed in 1 repo~2.9k tokens
    Productivity & AutomationAuto-check passed

  • N8n CLI

    n8n-io/n8n

    Official

    Use the n8n CLI to manage workflows, credentials, executions, and more on an n8n instance.

    207k GitHub stars~3k tokensUpdated today
    Productivity & AutomationAuto-check passed

  • CUAWright Web Task Automation

    microsoft/CUAWright

    Official

    Solves web tasks by driving a local Playwright browser one bash command at a time, saving a reusable script, screenshots and an action log for each run.

    6k GitHub stars~2k tokensUpdated 2 days ago
    Productivity & AutomationAuto-check: notes

  • Skyvern Browser Automation

    Skyvern-AI/skyvern

    Automates websites with Skyvern's AI browser agent to fill forms, extract data, download files, log in and run multi-step workflows through SDKs, REST, MCP or a CLI.

    23k GitHub stars~1.9k tokensUpdated today
    Productivity & AutomationAuto-check passed

  • Piece Builder

    activepieces/activepieces

    Build and edit Activepieces pieces (integrations) — creating new pieces, adding actions or triggers, or fixing bugs in existing ones.

    25k GitHub stars~3.1k tokensUpdated today
    Productivity & AutomationAuto-check: notes

  • N8n Docs Assistant

    n8n-io/n8n

    Official

    Answers n8n product, setup, credential, node, hosting, API, and usage questions from current n8n docs.

    207k GitHub stars~550 tokensUpdated today
    Productivity & AutomationAuto-check passed

More from basicmachines-co/basic-memory

All 49 skills in this repo

  • cmux Settings Editor

    basicmachines-co/basic-memory

    Views, sets, unsets and validates cmux settings in ~/.config/cmux/cmux.json with a helper script that checks keys against the schema.

    4.1k GitHub starsUsed in 1 repo~1.3k tokens
    Auto-check passed

  • cmux Window and Pane Control

    basicmachines-co/basic-memory

    End-user control of cmux topology and routing (windows, workspaces, panes/surfaces, focus, moves, reorder, identify, trigger flash). Use when automation needs…

    4.1k GitHub starsUsed in 2 repos~842 tokens
    Auto-check passed

  • Cmux Markdown Viewer Panel

    basicmachines-co/basic-memory

    Opens markdown files in a formatted cmux panel beside the terminal that re-renders on every change, handy for plans and task lists.

    4.1k GitHub starsUsed in 2 repos~527 tokens
    Auto-check passed

  • Basic Memory Repo Images

    basicmachines-co/basic-memory

    Produces PR, changelog and two-week retro images for the Basic Memory repository from evidence in PR bodies, saved to fixed paths under docs/assets/infographics.

    4.1k GitHub stars~2.7k tokensUpdated today
    Auto-check passed

  • Logfire Instrumentation

    basicmachines-co/basic-memory

    Adds Pydantic Logfire tracing, logging and metrics to Python, JavaScript or TypeScript and Rust projects, with the correct setup order and library extras.

    4.1k GitHub stars~2.3k tokensUpdated today
    Auto-check passed

  • Basic Memory Onboarding

    basicmachines-co/basic-memory

    Guides a newcomer to Basic Memory through designing a personal knowledge system, then teaches its use and sets up their assistant to load it each session.

    4.1k GitHub stars~3.4k tokensUpdated today
    Auto-check passed

Categories

Questions about cmux Workspace Scoping

What does cmux Workspace Scoping do?

Keeps agent actions scoped to the cmux workspace and terminal that invoked it, and lays out pane and surface commands that avoid disrupting the user's own focus. The skill defines cmux's vocabulary (window, workspace, pane, surface, panel) and sets a default rule: scope actions to the caller's own workspace unless the user explicitly asks for another one, since an agent can be running in a workspace the user isn't currently looking at. It reads CMUX_WORKSPACE_ID, CMUX_SURFACE_ID and CMUX_SOCKET_PATH from the environment, falling back to cmux identify when they are missing and saying explicitly that the currently focused context is being used.

When should I use cmux Workspace Scoping?

cmux Workspace Scoping fits situations like: opening a terminal or browser pane without disturbing the user's current focus; running an automation scoped to the workspace that invoked the agent; reusing a helper pane for preview output instead of creating new panes.

How do I install cmux Workspace Scoping in Claude Code?

Run `npx skills add basicmachines-co/basic-memory --skill cmux-workspace -a claude-code`. Or copy the skill folder (.agents/skills/cmux-workspace in basicmachines-co/basic-memory) into .claude/skills/cmux-workspace in your project. Claude Code loads it when a task matches its description.

How do I install cmux Workspace Scoping in Codex?

Run `npx skills add basicmachines-co/basic-memory --skill cmux-workspace -a codex`. Or copy the skill folder (.agents/skills/cmux-workspace in basicmachines-co/basic-memory) into .agents/skills/cmux-workspace in your project. Codex loads it when a task matches its description.

Can I use cmux Workspace Scoping in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add basicmachines-co/basic-memory --skill cmux-workspace -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/cmux-workspace, .gemini/skills/cmux-workspace, .github/skills/cmux-workspace and .opencode/skills/cmux-workspace in your project.

What does cmux Workspace Scoping need to run?

SKILL.md names no scripts, command-line tools or credentials: cmux Workspace Scoping is instructions for the agent only. Our summary lists: The cmux CLI with CMUX_WORKSPACE_ID and related environment variables set.

Does cmux Workspace Scoping access the network?

SKILL.md names 1 domain. As links in the text: github.com. This is read from the text; nothing was executed.

Is cmux Workspace Scoping safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does cmux Workspace Scoping use?

cmux Workspace Scoping is published under the AGPL-3.0 licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does cmux Workspace Scoping use?

About 1.7k tokens (SKILL.md is roughly 6.7k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 875 tokens, read only when the agent opens those files.

What are the alternatives to cmux Workspace Scoping?

Skills that share tags, products or a category with cmux Workspace Scoping: Skyvern Browser Automation (Skyvern-AI/skyvern, 23k stars), N8n CLI (n8n-io/n8n, 207k stars), CUAWright Web Task Automation (microsoft/CUAWright, 6k stars) and Skyvern Browser Automation (Skyvern-AI/skyvern, 23k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains cmux Workspace Scoping?

basicmachines-co (a GitHub organization) maintains it in basicmachines-co/basic-memory, which has 4,115 GitHub stars. The repository holds 49 skills in this directory. The repository was last updated on October 7, 2026.

Source: basicmachines-co/basic-memory on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.