{"id":50374998,"url":"https://github.com/tomtomjskim/cmux-setup","last_synced_at":"2026-05-30T09:02:25.656Z","repository":{"id":357257253,"uuid":"1236164263","full_name":"tomtomjskim/cmux-setup","owner":"tomtomjskim","description":"macOS helper for cmux — one command (cmx \u003cproject\u003e) spawns a workspace with claude/codex + terminals + browser in one of 3 preset layouts","archived":false,"fork":false,"pushed_at":"2026-05-12T02:27:20.000Z","size":106,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-12T03:26:13.416Z","etag":null,"topics":["bash","claude-code","cmux","codex","developer-tools","macos","productivity","terminal","workspace"],"latest_commit_sha":null,"homepage":"https://cmux.com","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tomtomjskim.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-12T02:18:29.000Z","updated_at":"2026-05-12T02:27:23.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/tomtomjskim/cmux-setup","commit_stats":null,"previous_names":["tomtomjskim/cmux-setup"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/tomtomjskim/cmux-setup","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomtomjskim%2Fcmux-setup","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomtomjskim%2Fcmux-setup/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomtomjskim%2Fcmux-setup/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomtomjskim%2Fcmux-setup/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tomtomjskim","download_url":"https://codeload.github.com/tomtomjskim/cmux-setup/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomtomjskim%2Fcmux-setup/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33686018,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-30T02:00:06.278Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bash","claude-code","cmux","codex","developer-tools","macos","productivity","terminal","workspace"],"created_at":"2026-05-30T09:02:24.793Z","updated_at":"2026-05-30T09:02:25.643Z","avatar_url":"https://github.com/tomtomjskim.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# cmux-setup\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\".github/assets/social-preview.png\" alt=\"cmux-setup — macOS helper for cmux\" width=\"100%\"\u003e\n\u003c/p\u003e\n\n[![smoke](https://github.com/tomtomjskim/cmux-setup/actions/workflows/smoke.yml/badge.svg)](https://github.com/tomtomjskim/cmux-setup/actions/workflows/smoke.yml)\n[![macOS](https://img.shields.io/badge/macOS-Apple%20Silicon%20%7C%20Intel-black?logo=apple)](https://www.apple.com/macos)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n\n[cmux](https://cmux.com) 워크스페이스 + 패널 레이아웃을 한 명령으로 자동 세팅하는 macOS 도구 모음.\n\n```bash\ncmx ~/work/myapp 80\n```\n\n→ cmux 가 새 워크스페이스를 띄우고, 3단 패널(claude/codex | 터미널 3개 | 브라우저) 을 자동 구성합니다.\n\n\u003e **English**: A macOS helper that wraps the [cmux](https://cmux.com) GUI app. Type `cmx \u003cproject-path\u003e` to spawn a cmux workspace with one of three preset panel layouts (3-column / simple / 4-split). Read [docs/usage.md](docs/usage.md) for details.\n\n## 레이아웃 미리보기\n\n```text\ndefault (3단)                                    simple                     4split\n┌──────────┬──────────┬──────────┐                ┌──────────┬──────────┐    ┌──────────┬──────────┐\n│ claude   │   t1     │          │                │  shell   │ browser  │    │          │  test    │\n├──────────┤   t2     │ browser  │                │ (DEV_CMD)│          │    │   dev    ├──────────┤\n│ codex    │   t3     │          │                └──────────┴──────────┘    │          │  claude  │\n└──────────┴──────────┴──────────┘                                           ├──────────┴──────────┤\n                                                                             │       browser       │\n                                                                             └─────────────────────┘\n```\n\n## 빠른 시작\n\n```bash\n# 0) cmux.app 설치 (미설치 시)\nbrew install --cask manaflow/cmux/cmux       # 또는 https://cmux.com 에서 DMG\nopen -a cmux                                  # 한 번 실행해 /usr/local/bin/cmux 등록\n\n# 1) 리포 클론 (경로는 자유)\nREPO_DIR=\"$HOME/dev/cmux-setup\"\ngit clone https://github.com/tomtomjskim/cmux-setup.git \"$REPO_DIR\"\n\n# 2) 부트스트랩 — 의존성 점검 + ~/.zshrc 에 cmux-setup 블록 추가 (idempotent)\n\"$REPO_DIR/install.sh\"\n\n# 3) 새 셸 열기 (또는 source ~/.zshrc)\n\n# 4) 사용\ncmx ~/work/myapp 80\n```\n\n\u003e **uninstall**: `\"$REPO_DIR/install.sh\" uninstall` 로 ~/.zshrc 통합 제거 (백업 자동 생성).\n\n## 무엇이 들어 있나\n\n| 파일 | 역할 |\n|---|---|\n| `bin/cmux-setup.sh` | 메인. 디렉토리 + 포트(또는 URL) 받아 cmux 워크스페이스 자동 구성 |\n| `bin/set-cursor-default.sh` | 코드 파일을 Xcode 대신 Cursor 로 열도록 macOS LaunchServices 갱신 |\n| `bin/check-default-apps.sh` | 기본 앱 매핑 진단 + 브라우저 원복 |\n| `shell/aliases.zsh` | 글로벌 `cmx` alias + 보조 alias (커밋됨) |\n| `shell/aliases.local.zsh.example` | 머신/회사별 단축 alias 템플릿 (실제 파일은 gitignore) |\n| `templates/cmux.conf.example` | 프로젝트별 영구 설정 템플릿 |\n| `install.sh` | 부트스트랩 (idempotent) + `uninstall` 모드 |\n| `tests/smoke.sh` | 단위 + mock cmux 통합 테스트 |\n\n## 사용법 한눈에\n\n```bash\ncmx                          # 현재 디렉토리, 기본 3단 레이아웃, port 80\ncmx ~/work/myapp 8081        # 두 번째 인자가 숫자 → http://localhost:8081\ncmx ~/work/myapp http://app.local        # URL 인자\ncmx ~/work/myapp 80 --v-simple           # 터미널 | 브라우저 단순 레이아웃\ncmx ~/work/myapp 80 --v-4split           # dev/test/claude/브라우저 4분할\nCMX_DEBUG=1 cmx ~/work/myapp             # 디버그 모드\n```\n\n자세한 내용은 [docs/usage.md](docs/usage.md).\n\n## 레이아웃\n\n3종 프리셋. [docs/layouts.md](docs/layouts.md) 에 다이어그램·코드 흐름 정리.\n\n- `--v-default` (기본): 왼쪽 `claude`/`codex` | 중간 `t1`/`t2`/`t3` | 오른쪽 브라우저\n- `--v-simple`: 터미널 | 브라우저\n- `--v-4split`: dev / test / claude / 브라우저 4분할\n\n## 프로젝트별 영구 설정 — `.cmux.conf`\n\n프로젝트 디렉토리에 `.cmux.conf` 파일을 두면 자동 로드. **`source` 가 아니라 화이트리스트 KEY=VALUE 파서**로 읽으므로 임의 코드 실행 위험 없음. 허용 키: `PORT`, `BROWSER_URL`, `DEV_CMD`, `TEST_CMD`, `CLAUDE_CMD`, `CODEX_CMD`, `LAYOUT`. 자세한 예시는 [templates/cmux.conf.example](templates/cmux.conf.example).\n\n```bash\n# \u003cproject\u003e/.cmux.conf\nPORT=8080\nBROWSER_URL=http://app.local\nDEV_CMD=\"npm run dev\"\nTEST_CMD=\"phpunit --watch\"\nCLAUDE_CMD=\"claude\"\nCODEX_CMD=\"codex\"\nLAYOUT=\"simple\"\n```\n\n우선순위: **명령행 인자 \u003e `.cmux.conf` \u003e 스크립트 기본값**.\n\n## 단축 alias\n\n`shell/aliases.zsh` 에 `cmx` 글로벌 alias 가 있고, 자주 쓰는 프로젝트는 `aliases.local.zsh` 에 두면 됩니다 (gitignore 되어 외부 노출 없음).\n\n```bash\ncp \"$CMUX_SETUP_DIR/shell/aliases.local.zsh.example\" \\\n   \"$CMUX_SETUP_DIR/shell/aliases.local.zsh\"\n# 주석 풀고 본인 프로젝트 경로/포트로 수정\n```\n\n## macOS 단축키 충돌\n\ncmux 의 `⌃ 1-9` (surface 점프) 가 macOS Mission Control 과 충돌합니다. 해결책은 [docs/shortcuts.md](docs/shortcuts.md).\n\n## 코드 파일이 Xcode 로 열릴 때\n\n[docs/default-apps.md](docs/default-apps.md) — `set-cursor-default.sh` 사용법, 부작용, 원복.\n\n## 트러블슈팅\n\n[docs/troubleshooting.md](docs/troubleshooting.md) — `ref 추출 실패`, `Workspace index not found`, 비율, 디버그 모드 등.\n\n## 다른 PC 에서도 똑같이 — AI 에이전트 프롬프트\n\n[docs/setup-prompt.md](docs/setup-prompt.md) 에 Claude Code / Cursor 에 그대로 복사해서 줄 수 있는 프롬프트를 박아두었습니다.\n\n## PM 운영 패턴 참조\n\n다중 세션 (코드 작업 + PM 세션) 운영 시 [docs/pm-operation-guide.md](docs/pm-operation-guide.md) 참조. 실 다중 트랙 closure 경험 정리.\n\n## 의존성\n\n- macOS (Apple Silicon / Intel 모두 OK)\n- [cmux.app](https://cmux.com) — Spotlight 에서 한 번 실행되어 있어야 함\n- (선택) `duti` — `set-cursor-default.sh` 만 사용. 첫 실행 시 동의 후 `brew install duti`\n\n## 기여\n\n[CONTRIBUTING.md](CONTRIBUTING.md) 참고. PR 보내기 전 `tests/smoke.sh` 통과 필수.\n\n## 라이선스\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftomtomjskim%2Fcmux-setup","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftomtomjskim%2Fcmux-setup","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftomtomjskim%2Fcmux-setup/lists"}