catalan-adobe/cmux-setup

cmux-setup

Manage cmux workspace visual configuration. Currently handles automatic workspace coloring based on directory-pattern rules.

Prerequisites

• Node 22+ (JSON parsing, file I/O)
• cmux CLI (only needed for apply, not config management)

Standalone Installation

1. Copy SKILL.md to ~/.claude/commands/cmux-setup.md
2. Copy scripts/cmux-setup.js to ~/.local/bin/cmux-setup.js and chmod +x it
3. The fallback search will find it via the find command in Script Location

Script Location

if [[ -n "${CLAUDE_SKILL_DIR:-}" ]]; then
  CMUX_SETUP="${CLAUDE_SKILL_DIR}/scripts/cmux-setup.js"
else
  CMUX_SETUP="$(find ~/.claude -path "*/cmux-setup/scripts/cmux-setup.js" \
    -type f 2>/dev/null | head -1)"
fi
if [[ -z "$CMUX_SETUP" || ! -f "$CMUX_SETUP" ]]; then
  echo "Error: cmux-setup.js not found." >&2
fi

Store in CMUX_SETUP and use for all commands below.

Commands

node "$CMUX_SETUP" apply [dir]                          # Apply matching rule to workspace (default: cwd)
node "$CMUX_SETUP" list                                 # List all configured rules
node "$CMUX_SETUP" add --pattern <glob> --color <hex> --icon <sf.symbol> --label <text>
node "$CMUX_SETUP" remove --pattern <glob>              # Remove rule by pattern
node "$CMUX_SETUP" match [dir]                          # Show which rule matches a directory
node "$CMUX_SETUP" install-hook                         # Install zsh chpwd hook in ~/.zshrc
node "$CMUX_SETUP" uninstall-hook                       # Remove zsh chpwd hook from ~/.zshrc

Mode 1: Persistent Setup

Use when the user wants colors applied automatically on every directory change.

1. Ask which directories they want to color and what color/icon/label to use for each. If they say "this project" or "here", use the current working directory.
2. For each rule, run add with --pattern, --color, --icon, --label.
3. Run install-hook to register the zsh chpwd hook.
4. Run apply (no args) to color the current workspace immediately.
5. Tell the user to source ~/.zshrc (or open a new terminal) so the hook takes effect in the current session.

Mode 2: On-Demand

Use when the user wants to color the current workspace once without persisting any config.

With existing config: Run apply and the best matching rule is used.

Ad-hoc (no config): Call cmux directly — no script needed:

cmux set-status project "Label" --color "#HEX" --icon "icon.name"

This is ephemeral — the color is gone when the workspace closes or a new rule overwrites it.

Rule Management

Handle these conversational requests:

| Request | Action | |---------|--------| | "Add a rule for ~/work" | Ask for color, icon, label; run add | | "Show my rules" | Run list | | "Remove the ~/work rule" | Run remove --pattern ~/work | | "What matches here?" | Run match (no args = cwd) | | "What would match ~/repos/foo?" | Run match ~/repos/foo |

When adding a rule, ask for all four fields (--pattern, --color, --icon, --label) in one prompt if not already provided. Don't ask one at a time.

Config Format

Location: ~/.config/cmux-setup/rules.json

• Patterns use ~ (expanded to $HOME at match time)
• Trailing /* is a recursive prefix match — ~/work/* matches any path under ~/work/
• Bare paths without /* are exact matches
• Most specific rule wins (longest matching pattern)

Example:

{
  "rules": [
    {
      "pattern": "~/repos/ai/*",
      "color": "#7B2FBE",
      "icon": "brain",
      "label": "AI"
    },
    {
      "pattern": "~/work/*",
      "color": "#0066CC",
      "icon": "briefcase",
      "label": "Work"
    }
  ]
}

Relationship to cmux-demo

cmux-setup uses the status_key from config (default: "project") in sidebar metadata. cmux-demo uses demo-specific keys. They coexist without conflict.