# cmux-workspace

Keeps an agent's actions inside the cmux workspace and terminal that started it, so automation does not disturb whatever the user is looking at.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 6900 installs · ★ 28491
- Author: manaflow-ai
- License: GPL-3.0 · policy=link-only · description only; the file stays with the author
- Source: https://github.com/manaflow-ai/cmux/tree/HEAD/skills/cmux-workspace/SKILL.md
- Updated: 2026-10-25
- HTML: https://affpapa.org/en/nevibecode/skills/cmux-workspace

## What it does

The skill lays out cmux's structure for the agent: window, workspace, pane, surface. Unless the user names another target, every action stays in the caller's workspace rather than the one on screen. Anchors come from `CMUX_WORKSPACE_ID` and `CMUX_SURFACE_ID`; when those are absent, the agent falls back to `cmux identify --json` and says it is using the focused context.

Layout is built in one pass with panes that already carry the right surface, and `--command` starts the first command at spawn instead of a later `send`. Verbs that move focus or switch workspaces count as user-facing clicks, so the skill never calls them on a guess. Auxiliary output — a preview app, logs, a throwaway shell — goes into a single pane beside the caller's terminal; asking again adds a tab there instead of another split.

One rough edge is documented: `drag-surface-to-split` resolves the workspace through UI focus, so it returns `ERROR: Surface not found` when the caller's workspace is not the focused one. Recovering by focusing is off the table — report the failure and stop. Socket access may be disabled or limited to processes cmux spawned; `cmux capabilities --json` and `cmux ping` help diagnose that.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add manaflow-ai/cmux --skill cmux-workspace -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/cmux-workspace/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/cmux-workspace/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add manaflow-ai/cmux --skill cmux-workspace -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/cmux-workspace/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add manaflow-ai/cmux --skill cmux-workspace -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/cmux-workspace/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install manaflow-ai/cmux cmux-workspace
```

2. **Manually: put the files in place**
- File: `.github/skills/cmux-workspace/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add manaflow-ai/cmux --skill cmux-workspace -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/manaflow-ai/cmux --path skills/cmux-workspace
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/cmux-workspace/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add manaflow-ai/cmux --skill cmux-workspace -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/manaflow-ai/cmux/tree/HEAD/skills/cmux-workspace/SKILL.md

## When to use it
- run a build in the workspace that launched the agent, not the visible one
- open an app preview in a side pane without stealing focus
- pass a note to another agent without typing into its terminal
- show task status and progress in the current workspace sidebar
- move a surface into a pane without changing focus

## Example prompts
- Run `npm run dev` in the terminal of the current cmux workspace
- Open the preview at `http://127.0.0.1:8765` in the right-hand pane, leave focus alone
- Message the cmux-remote-status agent that the fix is on main

## Similar
- [setup-matt-pocock-skills](https://affpapa.org/en/nevibecode/skills/setup-matt-pocock-skills.md) — skill · 1052851 installs
- [ask-matt](https://affpapa.org/en/nevibecode/skills/ask-matt.md) — skill · 766587 installs
- [to-tickets](https://affpapa.org/en/nevibecode/skills/to-tickets.md) — skill · 711230 installs
- [writing-plans](https://affpapa.org/en/nevibecode/skills/writing-plans.md) — skill · 282859 installs
- [caveman-review](https://affpapa.org/en/nevibecode/skills/caveman-review.md) — skill · 411800 installs
- [caveman-compress](https://affpapa.org/en/nevibecode/skills/caveman-compress.md) — skill · 411500 installs

## Other versions with the same name
- [cmux-workspace · manaflow-ai](https://affpapa.org/en/nevibecode/skills/manaflow-ai-cmux-workspace.md) — 755 installs

From the same set: [manaflow-ai/cmux](https://affpapa.org/en/nevibecode/by/manaflow-ai/cmux.md) — 24 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md