Claude Code Mod를 데스크톱 버전에서 열었을 때 발견한 5가지 차이점

Claude Code의 Mods는 터미널과 데스크톱 앱(Code 탭) 양쪽 모두에 그려집니다. 같은 코드가 그대로 작동할 것이라고 생각하고 터미널에서 만든 Mod를 데스크톱에서 열어보니, 작동은 하지만 모양이 완전히 망가졌습니다.

발견한 순서대로 5가지를 적겠습니다.

확인한 버전: Claude Code 2.1.286~2.1.288 (2026년 10월 · Windows).

1. 시작 시 열려야 할 패널이 보이지 않음

session.start에서 $.ui.open(...)을 호출해도, 데스크톱에서는 패널이 나타나지 않는 경우가 있습니다. 타입 정의의 ui.open에는 다음과 같은 규칙이 있습니다.

• 사람의 조작(명령어 · 전송한 프롬프트 · 버튼)에 의해 뒤에 오는 open은 너비와 관계없이 배치됨
• 뒤에 오지 않는 open(session.start · 시계 등)은 144桁부터 시작함. 사람이 한 번 연 패널은 110桁부터.
  좁으면 isPlaced: false로 대기하게 되며,
  시작(起動)의 open은 배치되지 않을 수 있다는 점을 고려하여, 첫 번째 프롬프트 전송 시에 다시 열도록 했습니다.

let opened = false
on('prompt.submit', async ($, e, next) => {
const kind = e.origin?.kind
...

참고로, 데스크톱(앱 2.19675)은 ui.open의 rows · columns를 받는 것만으로 패널 크기를 사용하지 않았습니다. 크기는 사람이 조작한 너비로 결정된다는 전제하에 그렸습니다.

2. 16진수 색상이 밝은 테마에서 읽기 어려움

터미널에서는 color: '#7FD1A6'와 같이 지정할 수 있습니다. 하지만 데스크톱에서는 고정된 색상이 밝은 테마에서 떠 보이거나 읽을 수 없게 됩니다. 테마의 색상 이름으로 전달하면 명암 어느 쪽에서도 올바르게 표시됩니다.

const THEMED = { '#7fd1a6': 'success', '#f2837f': 'diffRemovedWord', '#d9b26a': 'warning' }
function themeProps(props) {
const out = { ...props }
...

3. 배너 오른쪽이 비어있는 채로 구획이 떨어짐

데스크톱의 글자는 등폭이 아니라 가늘기 때문에, e.props.bodyColumns의 자릿수보다 많은 글자가 들어갑니다. 자릿수대로 배치하면 오른쪽에 빈 공간이 남는데도 불구하고 다음 구획을 내려버립니다. 저는 데스크톱에서는 1.5배로 계산했습니다.

const raw = e.props?.bodyColumns ?? e.viewport?.columns ?? 100
const cols = e.surface === 'terminal' ? raw : Math.round(raw * 1.5)

들어가지 않을 때는, 중간에서 자르는 것보다 우선순위가 낮은 구획부터 통째로 떨어뜨리는 것이 더 깔끔했습니다.

4. 버튼의 모양은 바꿀 수 없음 · 그림 위는 누를 수 없음

데스크톱의 Button은 이미 만들어진 모양이라 색상, 형태, 크기 모두 지정할 수 없습니다. 패널에 HTML도 넣을 수 없습니다.

'Svg로 화면 전체를 그리고 그 위에 Client를 겹쳐 눌린 위치를 파악하는' 방식도 시도해봤지만, 그림 위에 겹친 Client의 클릭은 작동하지 않았습니다. 안정적인 방법은 다음과 같습니다.

• 모양은 Svg의 그림 -
  눌러야 하는 것은, 그림 위나 아래에 나열된 미리 만들어진 Button (plain: true와 dimColor: true로 눈에 띄지게 할 수 있음)

plain: false라고 쓰면 데스크톱에서는 그려지지 않으므로, true이거나 생략만 합니다.

5. 좁은 패널에서 단문(段組)이 무너짐

데스크톱의 일반적인 열림 방식은 **대화 옆의 좁은 패널(약 58桁 · 440px)**입니다. 넓은 화면에서 공들여 만든 단문 배치는 여기서 차트가 가느다란 기둥으로 줄어들고, 축 글자가 겹치며, 범례가 잘렸습니다.

'좁은 패널에서 글자가 겹치거나 잘리지 않게 하는 것'을 합격선으로 삼아,

• 옆에 나열된 그림이 60桁 미만일 경우, 세로로 쌓는 형태로 전환하기
• 들어가지 않는 범례는 뒤쪽부터 떨어뜨리기

이렇게 했습니다. 만들기 전에, 좁은 창에서 한 번 열어보는 것이 가장 빠른 방법입니다.

면(Surface) 판별부터 고치는 것이 좋다

다섯 가지 모두 분기점은 e.surface

(
'terminal'

또는 'desktop'

)입니다. $.ui.resolve(e) 표는 모든 부품 이름으로 채워져 있어서, t.Svg의 유무만으로는 구별할 수 없습니다. Svg는 데스크톱에서, Raster는 터미널에서만 사용할 수 있는 면에 따라 쓸 수 있는 부품도 다릅니다.

요약

Discussion