cmux에서 Claude Code를 사용하며 겪은 경험: NODE_OPTIONS, Cmd+클릭, 워크스페이스 템플릿 설정

8월 중순부터 터미널을 cmux로 바꾸고 Claude Code를 사용하고 있습니다. 하나의 창에 프로젝트별 워크스페이스를 배치하고, 각각에서 Claude Code와 브라우저를 나란히 사용하는 방식입니다. 오늘 기준으로, 한 개의 창에 터미널 16개와 브라우저 3개가 열려 있습니다 (cmux 0.64.25).

편의성에 대한 이야기는 다른 글에 맡기고, 여기서는 실제로 부딪혔던 점 세 가지를 적겠습니다.

• cmux가 포함하는 NODE_OPTIONS 때문에 node 자체가 실행되지 않음 - Cmd+클릭으로 파일을 열 때 원하는 위치에서 열리지 않음 - 프로젝트별 워크스페이스를 cmux.json에 템플릿으로 작성하기

1. cmux가 포함하는 NODE_OPTIONS 때문에 node가 실행되지 않음

cmux 터미널에서는 셸의 환경 변수에 cmux용 값들이 여러 개 들어 있습니다. env | grep CMUX로 보면 CMUX_로 시작하는 변수들이 나열되고, NODE_OPTIONS에도 cmux의 preload 파일이 지정되어 있습니다.

평소에는 문제가 되지 않습니다. 그런데 이 preload 파일이 사라지면 node 자체가 실행되지 않게 됩니다. 언제 사라지는지는 정확히 알 수 없지만, 열어둔 터미널에서는 환경 변수가 시작했을 때 그대로 남아 있기 때문에, 가리키는 파일이 없어지면 발생합니다. npx wrangler도, 직접 만든 변환 스크립트도, node를 사용하는 모든 것이 멈춥니다.

해결책은 node를 호출할 때만 NODE_OPTIONS를 제외하는 것입니다.

# 한 번만 할 경우
NODE_OPTIONS= node scripts/md2note.mjs articles/026.md out/

wrangler처럼 매번 호출해야 하는 것은 함수로 만듭니다. 여기서 zsh의 함정이 있었습니다.

# NG: zsh는 변수에 담긴 명령어를 단어 분리하지 않습니다. "env -u NODE_OPTIONS npx wrangler"라는 이름의 명령어를 찾다가 실패합니다.
W="env -u NODE_OPTIONS npx wrangler"
$W d1 list
...

bash처럼 생각하고 변수에 넣으면 작동하지 않습니다. zsh에서는 함수로 만드는 것이 자연스럽습니다. 여러 Cloudflare 계정을 사용해야 할 경우, -u CLOUDFLARE_API_TOKEN 등도 같은 함수 안에서 제외하면 환경 변수의 토큰과 OAuth 로그인이 섞이는 사고를 막을 수 있습니다.

프로젝트 절차서(Claude Code에 읽히는 CLAUDE.md)에도 NODE_OPTIONS=를 붙여 호출하는 형태로 작성해 두었습니다. AI가 절차대로 명령어를 입력하더라도 여기서 멈추지 않도록 하기 위함입니다.

2. Cmd+클릭으로 파일을 열 때 원하는 위치에서 열리지 않음

cmux에서는 터미널에 출력된 파일 경로를 Cmd+클릭하여 열 수 있습니다. Claude Code가

という別の設定です。

상대 경로를 열 수 없음

또 하나는 상대 경로가 열리지 않는다는 것입니다.

Claude Code가 engagement/follow-plan.md
처럼 상대 경로로 작성하면, cmux는 터미널의 현재 디렉터리(current directory)를 기준으로 경로를 구성합니다. Claude Code를 ~/Dev에서 실행하고 실제 파일이 ~/Dev/note-articles/engagement/에 있다면, 존재하지 않는 경로가 되어 열 수 없습니다.

이에 대해 Claude Code에게 학습시켰습니다. Claude Code의 기억(메모리)에 “답변으로 파일을 표시할 때는 /Users/...로 시작하는 전체 경로(full path)로 작성하라”고 한 줄 남겨두었습니다. 기억은 다음 대화에도 로드되므로, 매번 말할 필요가 없습니다.

3. 프로젝트별 워크스페이스를 cmux.json에 기본값으로 설정하기

가장 효과적이었던 것이 이것입니다. 프로젝트별로 “Claude Code를 배치할 페인”과 “해당 프로젝트의 관리 화면을 연 브라우저 페인”을 좌우로 나란히 놓은 형태를 cmux.json의 actions에 작성해 둡니다.

{
"actions": {
"project-a": {
...

이렇게 작성해 두면, 새로운 워크스페이스를 만드는 “+” 버튼 메뉴에 나타납니다. 선택하면 프로젝트 디렉터리에서 Claude Code가 실행되고, 옆에 관리 화면이 열린 상태가 됩니다. 현재 사용하고 있는 레이아웃을 “Save Workspace as Layout”으로 저장하면 여기에 작성되므로, 처음에는 손으로 작성할 필요가 없습니다.

사용 방법은 다음과 같습니다.

Claude Code + 관리 화면: 실제 화면을 보면서 수정하는 프로젝트. Claude Code가 수정한 결과를 옆 브라우저에서 바로 확인할 수 있습니다.
터미널 + 빈 브라우저: 조사나 여러 프로젝트에 걸친 작업을 위한 용도.
Claude Code (에이전트 팀) + 관리 화면: cmux의 claude-teams
(Claude Code의 에이전트 팀을 cmux 페인에 띄우는 실행 방법)으로 구동해 두면, Claude Code가 이름이 지정된 서브 에이전트를 생성할 때마다 각각 분할 페인에 열립니다. 동시에 조사하는 모습을 볼 수 있습니다.

워크스페이스별로 색상도 지정할 수 있으므로, 실제 관리 화면을 열어둔 것만 색상을 변경해 두면 실수로 실무 환경을 건드리는 사고를 줄일 수 있습니다.

요약

• cmux는 NODE_OPTIONS에 preload를 넣는다. 이것이 오래되면 node가 실행되지 않는다. node를 호출할 때는 NODE_OPTIONS= 또는 env -u NODE_OPTIONS, zsh에서는 함수로 만든다. Cmd+클릭의 열기 위치는 openSupportedFilesInCmux・openMarkdownInCmuxViewer・preferredEditor로 결정된다. 읽을 거라면 cmux 내부, 쓸 거라면 외부 에디터-
• 상대 경로는 터미널의 현재 디렉터리 기준이므로 열리지 않는 경우가 있다. Claude Code의 기억에 “전체 경로로 작성하라”고 넣어둔다.
• 프로젝트별로 “Claude Code + 관리 화면” 워크스페이스를 cmux.json의 actions에 작성해 두면, 한 번의 조작으로 작업 환경이 갖춰진다.

토론 (Discussion)