# cmux Customization Examples

Use `cmux docs workflows` for the human-readable index or `cmux docs workflows --json` for the machine-readable catalog. This file holds the concrete recipes referenced by that catalog.

Merge only the relevant top-level keys into the file named above each block. Unlabeled JSON targets `cmux.json`. Preserve unrelated sections, then run `cmux reload-config`. Prefer project-local `.cmux/cmux.json` for team workflows and global `~/.config/cmux/cmux.json` for personal preferences.

## Worktree Agents

Plus button opens a worktree layout; right-click offers alternate starters. `workspaceCommand.commandName` must match a `commands[].name`.

```json
{
  "actions": {
    "worktree-agents": {
      "type": "workspaceCommand",
      "title": "Worktree Agents",
      "commandName": "Worktree Agents",
      "icon": { "type": "symbol", "name": "folder.badge.plus" }
    }
  },
  "ui": {
    "newWorkspace": {
      "action": "worktree-agents",
      "contextMenu": [
        { "action": "worktree-agents", "title": "Worktree Agents" },
        { "type": "separator" },
        { "action": "cmux.newTerminal", "title": "New Terminal" },
        { "action": "cmux.newBrowser", "title": "New Browser" }
      ]
    }
  },
  "commands": [{
    "name": "Worktree Agents",
    "description": "Create a worktree and open agents inside it",
    "workspace": {
      "name": "Worktree Agents", "cwd": "../worktrees/my-feature",
      "layout": { "direction": "horizontal", "children": [
        { "pane": { "surfaces": [{ "type": "terminal", "name": "Codex", "command": "codex" }] } },
        { "pane": { "surfaces": [{ "type": "terminal", "name": "Claude", "command": "claude" }] } }
      ]}
    }
  }]
}
```

## Full-Stack Dev

Terminals plus browser preview plus persistent Dock controls.

`.cmux/cmux.json`:

```json
{
  "commands": [{
    "name": "Full-Stack Dev",
    "workspace": {
      "name": "Dev", "cwd": ".",
      "layout": { "direction": "horizontal", "split": 0.55, "children": [
        { "direction": "vertical", "children": [
          { "pane": { "surfaces": [{ "type": "terminal", "name": "Web", "command": "bun dev" }] } },
          { "pane": { "surfaces": [{ "type": "terminal", "name": "Tests", "command": "bun test --watch" }] } }
        ]},
        { "pane": { "surfaces": [{ "type": "browser", "name": "Preview", "url": "http://localhost:3000" }] } }
      ]}
    }
  }]
}
```

`.cmux/dock.json`:

```json
{
  "controls": [
    { "id": "git", "title": "Git", "command": "lazygit", "cwd": ".", "height": 320 },
    { "id": "feed", "title": "Feed", "command": "cmux feed tui --opentui", "height": 260 }
  ]
}
```

## SSH Devbox

Remote shell beside a local preview.

```json
{
  "commands": [{
    "name": "SSH Devbox",
    "keywords": ["ssh", "remote", "devbox"],
    "workspace": {
      "name": "Devbox", "cwd": ".",
      "layout": { "direction": "horizontal", "children": [
        { "pane": { "surfaces": [{ "type": "terminal", "name": "SSH", "command": "ssh devbox" }] } },
        { "pane": { "surfaces": [{ "type": "browser", "name": "Preview", "url": "http://localhost:3000" }] } }
      ]}
    }
  }]
}
```

## Review PR

One command for terminal plus browser PR review. Adjust the URL and command for the user's GitHub workflow.

```json
{
  "commands": [{
    "name": "Review PR",
    "keywords": ["review", "pull request", "pr"],
    "workspace": {
      "name": "PR Review", "cwd": ".",
      "layout": { "direction": "horizontal", "children": [
        { "pane": { "surfaces": [{ "type": "terminal", "name": "GitHub", "command": "gh pr status" }] } },
        { "pane": { "surfaces": [{ "type": "browser", "name": "Pull Request", "url": "https://github.com/owner/repo/pulls" }] } }
      ]}
    }
  }]
}
```

## Docs Workspace

Docs server, markdown viewer, and browser preview. Adjust command, URL, and markdown path for the docs stack.

```json
{
  "commands": [{
    "name": "Docs Workspace",
    "keywords": ["docs", "documentation", "preview"],
    "workspace": {
      "name": "Docs", "cwd": ".",
      "layout": { "direction": "horizontal", "split": 0.45, "children": [
        { "direction": "vertical", "children": [
          { "pane": { "surfaces": [{ "type": "terminal", "name": "Docs Server", "command": "bun run docs:dev" }] } },
          { "pane": { "surfaces": [{ "type": "terminal", "name": "Markdown", "command": "cmux markdown open docs/README.md --direction right --focus false; exec ${SHELL:-/bin/zsh} -l" }] } }
        ]},
        { "pane": { "surfaces": [{ "type": "browser", "name": "Docs Preview", "url": "http://localhost:3000/docs" }] } }
      ]}
    }
  }]
}
```

## Quick Agent Buttons

Agent buttons alongside the default terminal and browser buttons.

```json
{
  "actions": {
    "codex-new-tab": { "type": "agent", "agent": "codex", "title": "Codex", "target": "newTabInCurrentPane", "palette": true },
    "claude-new-tab": { "type": "agent", "agent": "claude", "title": "Claude", "target": "newTabInCurrentPane", "palette": true }
  },
  "ui": {
    "surfaceTabBar": {
      "buttons": [
        "cmux.newTerminal",
        "cmux.newBrowser",
        { "action": "codex-new-tab", "title": "Codex" },
        { "action": "claude-new-tab", "title": "Claude" }
      ]
    }
  }
}
```

### Prompt Snippets

Text actions paste reusable prompts into the focused terminal, preserving newlines and indentation. Add `"submit": true` to send Enter afterwards. The receiving shell or agent controls how pasted newlines behave. Snippets defined in a project-local config go through the same trust prompt as a project `type: "command"`, whether or not they submit; snippets in the global config never prompt.

```json
{
  "actions": {
    "review-prompt": {
      "type": "text",
      "title": "Review Prompt",
      "keywords": ["review", "snippet"],
      "shortcut": "cmd+shift+r",
      "text": "Review the staged diff for:\n  - regressions\n  - missing tests\n  - naming that hides intent"
    },
    "run-tests": {
      "type": "text",
      "title": "Run Tests",
      "text": "npm test -- --watch=false",
      "submit": true
    }
  }
}
```

Both entries appear in Cmd+Shift+P, can be bound to a shortcut, and can be referenced from `ui.surfaceTabBar.buttons` like any other action.

## CI Watch

Long-running monitors belong in Dock controls, not workspace panes.

`.cmux/dock.json`:

```json
{
  "controls": [
    { "id": "gh-runs", "title": "GitHub Runs", "command": "gh run list --limit 10 && exec ${SHELL:-/bin/zsh} -l", "cwd": ".", "height": 260 },
    { "id": "feed", "title": "Feed", "command": "cmux feed tui --opentui", "height": 260 }
  ]
}
```

## Validation checklist

- Parse any changed JSON or JSONC before reporting success.
- Keep `cwd` inside the `workspace` object for workspace commands.
- Confirm `workspaceCommand.commandName` matches a `commands[].name`.
- Use `ui.newWorkspace.contextMenu`, not the `rightClick` alias.
- Keep built-in tab bar buttons only when the user wants them visible.
- Keep secrets out of config. Use shell profiles, env vars, or a secret store.