Cmux Browser

cmux Browser Automation

cmux browser 명령어 그룹을 통해 브라우저 자동화를 수행한다. 모든 명령어는 Bash 도구로 실행한다.

Surface 개념

cmux 브라우저는 surface 단위로 브라우저 인스턴스를 관리한다. open으로 새 surface를 생성하고, 이후 surface:N으로 대상을 지정한다.

cmux browser open https://example.com           # surface 생성
cmux browser surface:2 click "#btn"             # surface:2 대상 조작

워크스페이스 — 사용자가 보는 곳에서 열기

브라우저는 반드시 사용자가 현재 보고 있는 워크스페이스에서 열어야 한다. Claude가 실행되는 pane(caller.workspace_ref)과 사용자가 보는 focused 워크스페이스(focused.workspace_ref)가 다를 수 있다. --workspace를 생략하면 Claude 쪽 워크스페이스에서 열려 사용자 화면에 나타나지 않는다.

# 항상 이 패턴으로 열 것
FOCUSED_WS=$(cmux identify | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['focused']['workspace_ref'])")
cmux browser open https://example.com --workspace "$FOCUSED_WS"

단축 one-liner:

cmux browser open https://example.com --workspace "$(cmux identify | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['focused']['workspace_ref'])")"

기본 워크플로우

1. 페이지 열기 및 대기

FOCUSED_WS=$(cmux identify | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['focused']['workspace_ref'])")
cmux browser open https://example.com --workspace "$FOCUSED_WS"
cmux browser surface:2 wait --load-state complete --timeout-ms 15000
cmux browser surface:2 snapshot --interactive --compact

2. 폼 입력 및 제출

cmux browser surface:2 fill "#email" --text "user@example.com"
cmux browser surface:2 fill "#password" --text "$PASSWORD"
cmux browser surface:2 click "button[type='submit']" --snapshot-after
cmux browser surface:2 wait --text "Welcome"

3. 디버깅

cmux browser surface:2 console list
cmux browser surface:2 errors list
cmux browser surface:2 screenshot --out /tmp/debug.png

4. 세션 저장/복원

cmux browser surface:2 state save /tmp/session.json
cmux browser surface:2 state load /tmp/session.json

핵심 원칙

• CSS 선택자 우선: snapshot의 [ref=eN] 참조는 해당 snapshot 시점에만 유효하고 이후 변경될 수 있다. CSS 선택자(textarea[name='q'], button[type='submit'] 등)를 우선 사용한다
• --snapshot-after: 클릭, 스크롤 등 상태 변경 액션 후 사용하여 결과를 확인한다
• wait: 페이지 로드, 요소 출현, URL 변경 등 비동기 상태를 기다린다. --timeout-ms를 항상 지정한다
• snapshot: 현재 DOM 구조를 텍스트로 확인한다. --interactive --compact로 조작 가능한 요소만 간결히 본다
• screenshot: 시각적 확인이 필요할 때 사용한다. Read 도구로 캡처된 PNG를 확인할 수 있다
• type vs fill: type은 기존 값에 추가, fill은 기존 값을 대체한다

실전 팁

surface ID 파싱

open 명령의 출력에서 surface ID를 추출하여 이후 명령에 사용한다:

OK surface=surface:73 pane=pane:22 placement=reuse

→ 이후 cmux browser surface:73 ...으로 조작

요소를 찾을 수 없을 때

1. snapshot --interactive --compact로 현재 페이지 요소 확인
2. CSS 선택자로 재시도 (ref 대신)
3. wait --selector "..." 로 요소 출현 대기 후 재시도

스크린샷 확인

cmux browser surface:N screenshot --out /tmp/page.png

Read 도구로 /tmp/page.png를 읽으면 시각적으로 페이지를 확인할 수 있다.

검색 자동화 패턴

FOCUSED_WS=$(cmux identify | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['focused']['workspace_ref'])")
cmux browser open https://www.google.com --workspace "$FOCUSED_WS"
cmux browser surface:N wait --load-state complete --timeout-ms 15000
cmux browser surface:N fill "textarea[name='q']" --text "검색어"
cmux browser surface:N press Enter
cmux browser surface:N wait --load-state complete --timeout-ms 15000
cmux browser surface:N snapshot --interactive --compact

고급 기능 (cmux 0.64.14 기준)

기본 탐색/조작 외에 다음 명령군도 제공된다. 상세는 레퍼런스 참조:

• 자동화 토글: status / enable / disable
• 프로필 관리: profiles list|add|rename|delete|clear
• 브라우저 가져오기: import --from chrome ... — Chrome 등의 프로필·쿠키·로그인 세션을 cmux로 가져와 로그인된 상태로 시작 (로그인 자동화 우회)
• 환경 에뮬레이션: viewport (모바일 뷰 테스트), geo , offline
• 요청 제어/녹화: network route/requests (요청 차단·모킹), trace start|stop, screencast start|stop
• 기타: identify(surface 식별), snapshot --cursor, wait --timeout

> 새 명령 사용 전 cmux browser (인자 없이)로 현재 설치된 CLI의 시그니처를 한 번 확인하면 버전 차이로 인한 오류를 막을 수 있다.

브라우저 GUI 신기능 (v0.64.13)

자동화 스킬과 직접적인 CLI 추가는 아니지만, 수동 디버깅 중 알아두면 좋은 기능.

• Browser Focus Mode (⌥⌘↩ 진입, Esc 두 번으로 종료). 활성 시 단축키가 cmux 앱 메뉴보다 웹페이지로 먼저 전달된다. 툴바 버튼·View 메뉴·command palette·페이지 컨텍스트 메뉴에서도 토글 가능.
• 마우스 사이드 버튼(button 3/4)으로 브라우저 뒤로/앞으로 — 복원된 세션 히스토리도 따라온다.

전체 API 참조

전체 명령어, 파라미터, 예제는 [references/apireference.md](references/apireference.md) 참조.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: junho85
• Source: junho85/cmux-browser-skill
• License: MIT

Install and usage instructions live in the source repository linked above.