사용자 정의 명령어
프로젝트 루트 또는 ~/.config/cmux/에 cmux.json 파일을 추가하여 사용자 정의 명령어와 워크스페이스 레이아웃을 정의합니다. 명령어는 명령어 팔레트에 표시됩니다.
파일 위치
cmux는 두 곳에서 설정을 찾습니다:
- 프로젝트별:
./cmux.json— 프로젝트 디렉터리에 위치하며 우선순위를 가집니다 - 전역:
~/.config/cmux/cmux.json— 모든 프로젝트에 적용되며 로컬에서 정의되지 않은 명령어를 보완합니다
로컬 명령어는 동일한 이름의 전역 명령어를 덮어씁니다.
변경 사항은 자동으로 반영됩니다 — 재시작이 필요 없습니다.
스키마
cmux.json 파일에는 commands 배열이 포함됩니다. 각 명령어는 단순한 셸 명령어이거나 완전한 워크스페이스 정의입니다:
cmux.json
{
"commands": [
{
"name": "Start Dev",
"keywords": ["dev", "start"],
"workspace": { ... }
},
{
"name": "Run Tests",
"command": "npm test",
"confirm": true
}
]
}단순 명령어
단순 명령어는 현재 포커스된 터미널에서 셸 명령어를 실행합니다:
cmux.json
{
"commands": [
{
"name": "Run Tests",
"keywords": ["test", "check"],
"command": "npm test",
"confirm": true
}
]
}필드
name— 명령어 팔레트에 표시됩니다 (필수)description— 선택적 설명keywords— 명령어 팔레트용 추가 검색어command— 포커스된 터미널에서 실행할 셸 명령어confirm— 실행 전 확인 대화상자 표시
단순 명령어는 포커스된 터미널의 현재 작업 디렉토리에서 실행됩니다. 프로젝트 상대 경로에 의존하는 명령어의 경우 앞에 cd "$(git rev-parse --show-toplevel)" && 를 붙여 저장소 루트에서 실행하거나 cd /your/path && 로 특정 디렉토리를 지정할 수 있습니다.
워크스페이스 명령어
워크스페이스 명령어는 분할, 터미널, 브라우저 패널의 사용자 정의 레이아웃으로 새 워크스페이스를 만듭니다:
cmux.json
{
"commands": [
{
"name": "Dev Environment",
"keywords": ["dev", "fullstack"],
"restart": "confirm",
"workspace": {
"name": "Dev",
"cwd": ".",
"layout": {
"direction": "horizontal",
"split": 0.5,
"children": [
{
"pane": {
"surfaces": [
{
"type": "terminal",
"name": "Frontend",
"command": "npm run dev",
"focus": true
}
]
}
},
{
"pane": {
"surfaces": [
{
"type": "terminal",
"name": "Backend",
"command": "cargo watch -x run",
"cwd": "./server",
"env": { "RUST_LOG": "debug" }
}
]
}
}
]
}
}
}
]
}워크스페이스 필드
name— 워크스페이스 탭 이름 (기본값은 명령어 이름)cwd— 워크스페이스의 작업 디렉터리color— 워크스페이스 탭 색상layout— 분할과 패널을 정의하는 레이아웃 트리
재시작 동작
동일한 이름의 워크스페이스가 이미 존재할 때 발생하는 동작을 제어합니다:
"ignore"— 기존 워크스페이스로 전환 (기본값)"recreate"— 묻지 않고 닫고 재생성"confirm"— 재생성 전 사용자에게 확인
레이아웃 트리
레이아웃 트리는 재귀적인 분할 노드를 사용하여 패널 배치를 정의합니다:
분할 노드
공간을 두 개의 자식으로 나눕니다:
direction—"horizontal"또는"vertical"split— 0.1에서 0.9 사이의 분할기 위치 (기본값 0.5)children— 정확히 두 개의 자식 노드 (분할 또는 패널)
패널 노드
하나 이상의 서피스(패널 내 탭)를 포함하는 리프 노드.
서피스 정의
패널 내 각 서피스는 터미널 또는 브라우저가 될 수 있습니다:
type—"terminal"또는"browser"name— 사용자 정의 탭 제목command— 생성 시 자동 실행할 셸 명령어 (터미널 전용)cwd— 이 서피스의 작업 디렉터리env— 키-값 쌍으로 된 환경 변수url— 열 URL (브라우저 전용)focus— 생성 후 이 서피스에 포커스
작업 디렉터리 해석
.또는 생략됨 — 워크스페이스 작업 디렉터리./subdir— 워크스페이스 작업 디렉터리 기준 상대 경로~/path— 홈 디렉터리로 확장- 절대 경로 — 있는 그대로 사용
전체 예시
cmux.json
{
"commands": [
{
"name": "Web Dev",
"description": "Docs site with live preview",
"keywords": ["web", "docs", "next", "frontend"],
"restart": "confirm",
"workspace": {
"name": "Web Dev",
"cwd": "./web",
"color": "#3b82f6",
"layout": {
"direction": "horizontal",
"split": 0.5,
"children": [
{
"pane": {
"surfaces": [
{
"type": "terminal",
"name": "Next.js",
"command": "npm run dev",
"focus": true
}
]
}
},
{
"direction": "vertical",
"split": 0.6,
"children": [
{
"pane": {
"surfaces": [
{
"type": "browser",
"name": "Preview",
"url": "http://localhost:3777"
}
]
}
},
{
"pane": {
"surfaces": [
{
"type": "terminal",
"name": "Shell",
"env": { "NODE_ENV": "development" }
}
]
}
}
]
}
]
}
}
},
{
"name": "Debug Log",
"description": "Tail the debug event log from the running dev app",
"keywords": ["log", "debug", "tail", "events"],
"restart": "ignore",
"workspace": {
"name": "Debug Log",
"layout": {
"direction": "horizontal",
"split": 0.5,
"children": [
{
"pane": {
"surfaces": [
{
"type": "terminal",
"name": "Events",
"command": "tail -f /tmp/cmux-debug.log",
"focus": true
}
]
}
},
{
"pane": {
"surfaces": [
{
"type": "terminal",
"name": "Shell"
}
]
}
}
]
}
}
},
{
"name": "Setup",
"description": "Initialize submodules and build dependencies",
"keywords": ["setup", "init", "install"],
"command": "./scripts/setup.sh",
"confirm": true
},
{
"name": "Reload",
"description": "Build and launch the debug app tagged to the current branch",
"keywords": ["reload", "build", "run", "launch"],
"command": "./scripts/reload.sh --tag $(git branch --show-current)"
},
{
"name": "Run Unit Tests",
"keywords": ["test", "unit"],
"command": "./scripts/test-unit.sh",
"confirm": true
}
]
}