cmux를 처음 켰을 때 사이드바나 파일 트리에 아이콘 자리마다 네모난 빈 칸이 뜬 경험이 있다면, 원인은 대부분 폰트다. cmux는 폰트·테마 설정을 자체적으로 두지 않고 macOS 터미널 Ghostty의 설정 파일을 그대로 읽어오는데, 이 파일에 아이콘 글리프를 담은 Nerd Font가 지정돼 있지 않으면 아이콘이 깨져 보인다. 이 글은 그 원인을 짚고, Nerd Font 설치부터 행간·글자 두께·리거처 같은 가독성 옵션까지 cmux 폰트 설정을 한 번에 정리한다. cmux 자체를 처음 접한다면 cmux 사용법 가이드를 먼저 보고 오면 좋다.
cmux에서 아이콘이 깨져 보이는 이유는
cmux 사이드바의 파일·Git 상태 아이콘이 네모나 물음표로 보이는 이유는 지정된 폰트에 해당 글리프가 없기 때문이다. cmux는 자체 폰트 렌더링 설정이 없고 ~/.config/ghostty/config의 font-family 값을 그대로 상속해 쓰는데, 시스템 기본 폰트나 일반 코딩 폰트에는 파일 아이콘용 특수 문자가 포함돼 있지 않다.
이 특수 문자들은 Nerd Font라는 폰트 패치 세트에만 들어 있다. Nerd Font는 JetBrains Mono, Fira Code 같은 기존 코딩 폰트에 Font Awesome, Devicons 같은 아이콘 글리프를 추가로 이식한 버전이다. 즉 cmux 자체의 버그가 아니라 폰트 설정이 아이콘을 지원하지 않는 상태인 것이고, Nerd Font 계열로 바꾸면 대부분 바로 해결된다.
Nerd Font를 설치하고 cmux에 지정하는 방법
Nerd Font 설치는 Homebrew로 폰트를 받고 Ghostty 설정 파일에 폰트 이름을 지정하는 두 단계다. cmux가 이 설정 파일을 그대로 읽으므로 별도로 cmux 쪽에 설정할 항목은 없다.
# Nerd Font 설치 (JetBrains Mono 예시)
brew install --cask font-jetbrains-mono-nerd-font위 명령은 Homebrew cask로 JetBrains Mono Nerd Font를 시스템 폰트로 설치한다. font-jetbrains-mono-nerd-font 대신 font-fira-code-nerd-font, font-hack-nerd-font 등 다른 Nerd Font 패키지로 바꿔도 된다. 설치가 끝나면 아래처럼 Ghostty 설정 파일에 폰트 이름을 지정한다.
# ~/.config/ghostty/config
font-family = "JetBrainsMono Nerd Font"폰트 이름은 패키지명이 아니라 실제 폰트 패밀리명을 정확히 써야 한다. 이름이 정확한지 확실치 않으면 fc-list | grep -i nerd로 시스템에 설치된 Nerd Font 목록을 확인할 수 있다.
font-family에 적을 값은 콜론(:) 앞이 아니라 콜론 뒤에 쉼표로 나열된 이름들 중 하나다. 위 실행 결과처럼 한 파일이 JetBrainsMono Nerd Font, JetBrainsMono NF 같은 여러 별칭을 동시에 갖고 있을 수 있는데, 이 중 어떤 이름을 써도 상관없다. 설정을 저장한 뒤 cmux를 재시작하면 사이드바 아이콘이 정상적으로 나타난다.
cmux 폰트 설정과 Ghostty 설정이 어떻게 이어지나
cmux는 두 개의 서로 다른 설정 파일을 읽는데, 이 구조를 모르면 “분명히 설정했는데 안 바뀐다”는 상황에 빠지기 쉽다. 폰트·테마·색상 같은 렌더링 관련 설정은 ~/.config/ghostty/config에서 오고, 사이드바·탭·알림 같은 cmux 고유 UI 설정은 ~/.config/cmux/cmux.json에서 따로 관리된다.
그래서 폰트가 안 바뀔 때 가장 먼저 확인할 것은 설정을 엉뚱한 파일에 넣지 않았는지다. cmux.json에 font-family를 적어봤자 적용되지 않는데, cmux는 폰트 관련 키를 아예 읽지 않기 때문이다. 폰트·행간·리거처·대비 옵션은 전부 ~/.config/ghostty/config 한 곳에만 쓰면 된다.
adjust-cell-height로 답답한 줄 간격 넓히기
여러 에이전트의 로그를 하루 종일 들여다보는 도구인 만큼, 기본 행간보다 넓혀야 눈이 덜 피로하다. adjust-cell-height는 글자 한 줄이 차지하는 세로 공간을 퍼센트나 픽셀 단위로 조절하는 옵션이다.
# ~/.config/ghostty/config
adjust-cell-height = 15%
font-size = 15adjust-cell-height = 15%는 기본 셀 높이보다 15% 더 넓게 줄 간격을 벌린다. 값을 양수로 주면 넓어지고 음수로 주면 좁아지며, 15% 대신 2px처럼 절대 픽셀값도 지정할 수 있다. 로그처럼 줄 수가 많은 화면에서는 10~20% 정도만 늘려도 줄 사이가 붙어 보이는 답답함이 확연히 줄어든다.
font-thicken과 minimum-contrast로 흐릿한 글자 선명하게
macOS에서는 일부 폰트가 서브픽셀 렌더링 때문에 얇고 흐리게 보이는 경우가 있다. font-thicken은 글자를 약간 두껍게 렌더링해 이 문제를 보정하고, minimum-contrast는 테마 색상이 배경과 너무 가까워 글자가 묻히는 상황을 방지한다.
# ~/.config/ghostty/config
font-thicken = true
minimum-contrast = 1.1
theme = light:catppuccin-latte,dark:catppuccin-mochafont-thicken = true는 macOS에서 얇게 보이는 글자를 도톰하게 만들어 작은 크기에서도 읽기 쉽게 해준다. minimum-contrast는 배경과 글자색의 최소 명도비를 강제하는 값으로, 1.1 정도만 줘도 어두운 테마에서 흐릿하게 묻히던 텍스트가 또렷해진다. theme 줄처럼 light:/dark: 접두사를 붙이면 시스템이 라이트·다크 모드를 바꿀 때 테마도 자동으로 전환된다.
font-feature로 코드 리거처 끄기
리거처(ligature)는 !=, => 같은 기호 조합을 하나의 합쳐진 글자 모양으로 표시하는 폰트 기능이다. 디자인상으로는 보기 좋지만, 코드와 로그를 자주 읽는 상황에서는 오히려 기호를 잘못 읽게 만드는 원인이 된다.
# ~/.config/ghostty/config
font-feature = -calt, -liga-calt와 -liga는 각각 상황별 대체(contextual alternates)와 표준 리거처 기능을 끄는 지정이다. 이 옵션을 켜두면 !=가 별도 기호로 합쳐지지 않고 느낌표와 등호가 그대로 보여서, 로그를 빠르게 훑을 때 기호를 오독할 위험이 줄어든다. 리거처가 예쁘다고 느껴져도, 여러 에이전트의 명령 출력을 빠르게 스캔해야 하는 cmux 환경에서는 꺼두는 편이 실용적이다.
지금 쓰는 폰트를 유지하면서 아이콘만 추가하려면
애착이 있는 폰트를 Nerd Font로 통째로 바꾸고 싶지 않다면, 아이콘 글리프만 담당하는 폴백 폰트를 뒤에 추가하는 방법이 있다. Ghostty는 font-family를 여러 번 지정하면 그 순서대로 폴백 체인을 만들어서, 앞 폰트에 없는 글리프를 다음 폰트에서 찾아 그린다.
# ~/.config/ghostty/config
# 원래 쓰던 폰트를 그대로 1순위로 유지
font-family = "D2Coding"
# 2순위: D2Coding에 없는 아이콘 글리프만 이 폰트에서 가져온다
font-family = "Symbols Nerd Font Mono"font-family 줄을 하나 더 추가하는 것만으로 폴백 체인이 만들어진다. 한글·영문·숫자는 여전히 D2Coding으로 그려지고, D2Coding에 없는 파일 아이콘·Git 상태 심볼만 두 번째 줄의 Symbols Nerd Font Mono에서 가져와 채워준다. 이 폰트는 Nerd Fonts 프로젝트가 별도로 배포하는 심볼 전용 폰트로, 코드 글자는 하나도 없고 아이콘 글리프만 들어 있어서 원래 폰트의 자간·두께 같은 인상을 건드리지 않는다. brew install --cask font-symbols-only-nerd-font로 설치할 수 있다. 폰트 전체를 갈아타는 게 부담스러웠다면 이 방법이 가장 절충적인 해법이다.
설정 항목별로 무엇이 바뀌는지 한눈에
| 설정 항목 | 효과 | 추천값 |
|---|---|---|
font-family | Nerd Font 지정, 아이콘 깨짐 해결 | "JetBrainsMono Nerd Font" |
adjust-cell-height | 줄 간격(행간) 조절 | 10~20% |
font-thicken | 글자를 두껍게 렌더링 | true |
minimum-contrast | 배경 대비 최소 명도비 보장 | 1.1 |
font-feature | 코드 리거처 켜기/끄기 | -calt, -liga |
표의 다섯 항목만 조정해도 cmux 폰트 설정의 체감 차이는 크다. 전체 옵션 목록과 기본값은 ghostty +show-config --default --docs 명령이나 Ghostty 공식 설정 문서에서 확인할 수 있다. 설정을 바꾼 뒤에는 cmux를 완전히 재시작해야 반영된다는 점도 함께 기억해두면 좋다.
font-family까지 정확히 맞췄는데도 여전히 깨진다면
위 설정을 다 따라 했는데도 아이콘이 안 나온다면, 대부분 세 가지 중 하나다. 폰트 이름 오타, cmux가 완전히 재시작되지 않은 상태, 또는 폰트가 실제로는 설치되지 않은 상태다. 아래 순서로 하나씩 좁혀가면 대부분 여기서 해결된다.
# 1. 폰트가 실제로 시스템에 인식되는지 확인 (없으면 설치가 실패한 것)
fc-list | grep -i "JetBrainsMono Nerd Font"
# 2. 폰트 캐시가 오래된 상태로 남아있으면 강제로 다시 빌드
fc-cache -f
# 3. cmux 관련 프로세스가 완전히 종료됐는지 확인 (창만 닫으면 백그라운드에 남는다)
ps aux | grep -i cmuxfc-list에서 아무것도 안 나온다면 font-family에 적은 이름이 실제 설치된 폰트명과 다르거나, Homebrew 설치가 중간에 실패했다는 뜻이다. 이름은 대소문자와 공백까지 정확히 일치해야 하므로, fc-list 출력에 나온 이름을 그대로 복사해 쓰는 게 가장 안전하다. fc-cache -f는 macOS가 폰트 목록을 캐싱해두는 특성 때문에, 방금 설치한 폰트를 아직 인식하지 못하는 상황에서 강제로 다시 스캔하게 만든다. 마지막으로 macOS 앱은 창을 닫아도 프로세스가 완전히 죽지 않는 경우가 많다. Cmd+Q로 앱 자체를 종료하거나, ps aux | grep -i cmux로 남은 프로세스가 있는지 확인하고 강제로 종료한 뒤 다시 여는 게 확실하다.
FAQ
cmux 아이콘이 계속 네모로 보이는데 왜 그런가요?
~/.config/ghostty/config의 font-family가 Nerd Font로 지정돼 있지 않기 때문이다. brew install --cask font-jetbrains-mono-nerd-font로 설치한 뒤 font-family = "JetBrainsMono Nerd Font"처럼 정확한 폰트 패밀리명을 지정하고 cmux를 재시작하면 해결된다. 이름이 맞는지 확실치 않으면 fc-list | grep -i nerd로 확인한다.
cmux.json에 폰트를 설정해도 왜 반영이 안 되나요?
cmux.json은 사이드바·탭·알림 같은 cmux 고유 UI만 담당하고 폰트·테마 관련 키를 읽지 않기 때문이다. 폰트·행간·리거처·대비 옵션은 전부 ~/.config/ghostty/config에 적어야 한다.
font-thicken을 켜도 글자가 그대로 얇아 보입니다.
설정 반영을 위해 cmux를 완전히 재시작했는지 먼저 확인한다. 그래도 그대로라면 사용 중인 폰트 자체가 얇은 굵기(Light, Thin)로 지정돼 있을 수 있으므로, Regular 이상 굵기의 Nerd Font로 바꿔보는 것을 권한다.
리거처를 끄면 코딩 폰트의 장점이 사라지지 않나요?
리거처는 장식적 기능이라 꺼도 폰트의 다른 특성(고정폭, 숫자와 문자 구분, 아이콘 지원)에는 영향이 없다. !=나 => 같은 기호를 있는 그대로 읽고 싶은 사람에게는 font-feature = -calt, -liga로 끄는 편이 오독을 줄여준다는 실익이 더 크다.
Nerd Font가 아닌 폰트를 계속 쓰고 싶으면 방법이 없나요?
방법이 있다. font-family를 원래 쓰던 폰트로 두고, Symbols Nerd Font Mono를 두 번째 font-family 줄로 추가하면 아이콘만 폴백으로 채워진다. 자세한 설정은 위 “지금 쓰는 폰트를 유지하면서 아이콘만 추가하려면” 절을 참고한다. 폰트 전체를 바꾸는 게 더 간편하다면 원하는 코딩 폰트의 Nerd Font 패치 버전을 그대로 설치해도 된다. 대부분의 인기 코딩 폰트(Fira Code, Hack, JetBrains Mono 등)는 Nerd Font 버전이 이미 배포돼 있다.
워크스페이스(탭)마다 폰트를 다르게 설정할 수 있나요?
안 된다. cmux가 상속하는 ~/.config/ghostty/config는 앱 전역에 적용되는 단일 설정 파일이라, 워크스페이스나 탭 단위로 서로 다른 폰트를 지정하는 기능은 없다. 작업 성격에 따라 폰트를 바꿔가며 쓰고 싶다면, config-file 옵션으로 별도 설정 파일을 만들어두고 필요할 때 통째로 바꿔 끼우는 방법 정도가 현실적인 대안이다.
마무리
cmux를 처음 켰을 때 사이드바 아이콘이 죄다 네모로 깨져 있어서 뭔가 잘못 설치했나 싶었는데, 알고 보니 그냥 폰트 문제였다. Nerd Font로 바꾸고 나니 그제서야 파일 종류별 아이콘과 Git 상태 표시가 눈에 들어왔다. 그 김에 adjust-cell-height와 font-thicken도 같이 만져봤는데, 하루 종일 여러 에이전트의 로그를 들여다보는 입장에서는 이 두 개가 아이콘보다 체감 효과가 더 컸다. 반나절 정도 로그를 읽다 보면 줄 간격 하나 차이가 눈의 피로도를 꽤 좌우한다는 걸 알게 된다. 폰트 설정은 한 번 잡아두면 다시 손댈 일이 거의 없으니, cmux를 새로 설치했다면 아이콘부터 확인하고 이 다섯 가지 옵션을 먼저 정리해두는 걸 권한다.