UX 개발 / Ghostty

Ghostty로 Claude Code와 tmux 사용하기: 입문부터 문제 해결까지

GhosttyClaude CodetmuxmacOSCLI터미널

네이티브 터미널의 분할 화면과 다시 연결되는 세션 카드를 표현한 일러스트

Ghostty에서 Claude Code와 CLI 도구를 쓴다면 터미널·셸·tmux의 역할부터 구분해 보자. macOS 기본 조작, 최소 설정, 세션 복귀 실습, 한글 입력·SSH 문제 해결과 iTerm2·Warp 비교를 함께 안내한다.

이 글은 macOS 사용자를 기준으로 한다. 공식 문서와 공개 이슈를 2026-10-26에 확인했고, 설치된 Ghostty 1.3.1에서 기본 단축키와 예제 설정 문법을 검사했다. 모든 OS·키보드 조합에서 입력 문제를 재현하거나 터미널별 성능을 측정한 후기는 아니다.

1. Ghostty는 어떤 프로그램인가

Ghostty 공식 웹사이트의 Ghostty는 명령줄 프로그램을 화면에 표시하고 키보드 입력을 전달하는 터미널 에뮬레이터다. macOS·Linux의 네이티브 UI와 빠른 렌더링을 지향하며 탭, 화면 분할, 테마 등을 제공한다. 개발자도 모든 성능 항목에서 가장 빠르다고 주장하지 않는다. (공식 소개)

도구담당하는 일대신하지 않는 것
Ghostty창·탭·글자·키 입력을 제공AI 모델이나 프로젝트의 실행 환경
셸입력한 명령을 해석하고 프로그램 실행터미널 창 자체
tmux세션·윈도·패널을 관리하고 연결을 분리·복구머신 재부팅 뒤 프로세스 복구
Claude Code코드 조사·수정 등 AI CLI 작업터미널이나 tmux 서버

일반적인 구조는 Ghostty → 셸 → tmux → 셸 → Claude Code다. tmux 없이 Ghostty에서 Claude Code만 실행해도 된다. Ghostty를 바꿨다고 Claude의 모델 성능이나 사용 한도가 늘지는 않는다.

2. iTerm2·Warp·기본 터미널과 비교하기

프로그램선택하기 좋은 이유살펴볼 점
Ghostty네이티브 조작감, 탭·분할, 작은 텍스트 설정으로 CLI에 집중세션 유지에는 tmux 같은 별도 도구 사용. 설정은 주로 파일로 편집
iTerm2세밀한 프로필·자동화와 tmux의 네이티브 창·탭 통합기존 프로필·워크플로가 잘 맞으면 굳이 바꿀 필요 없음
Warp Terminal터미널과 AI 에이전트 작업 기능을 한 제품에서 사용기능별 요금·데이터 전송 설정, 기존 셸·플러그인 호환성 확인
macOS 터미널추가 설치 없이 기본 CLI·SSH·tmux 사용Ghostty의 네이티브 분할·현대적 터미널 기능이 필요한지 판단

Ghostty의 장점은 이미 선택한 CLI 도구를 편하게 담는 작업 화면이라는 점이다. Warp 자체의 AI 흐름이 필요하다면 Warp의 장점이 더 클 수 있다. Warp를 단순히 ‘tmux 미지원’이나 ‘항상 모든 명령 전송’으로 설명하지 말자. 현재 호환성 문서와 개인정보 설정을 기능·요금제별로 확인해야 한다.

특히 iTerm2는 tmux -CC로 tmux 윈도를 네이티브 창·탭처럼 다루는 통합을 제공한다. 일반 tmux를 Ghostty 안에서 실행하는 것과 구분하자. (iTerm2 tmux 통합)

tmux 윈도를 네이티브 UI로 다루고 연결이 끊겨도 서버에 남는 작업에 다시 붙는 iTerm2 공식 설명

iTerm2 공개 공식 문서 캡처. 비교에서 중요한 차이는 단순 화면 분할보다 tmux의 네이티브 UI 통합이다. (출처, 2026-10-26 캡처)

3. 설치하고 현재 상태 확인하기

Ghostty 공식 다운로드에서 macOS .dmg를 받아 응용 프로그램 폴더로 옮긴다. Homebrew가 준비되어 있다면 아래 방식도 가능하다. 이미 설치한 도구는 중복 설치하지 않는다.

brew install --cask ghostty
brew install tmux

Claude Code가 없다면 공식 빠른 시작을 따라 설치·로그인을 완료한다. Homebrew 설치를 선택했다면:

brew install --cask claude-code

Ghostty를 열고 확인한다.

ghostty --version
tmux -V
claude --version
pwd

pwd는 현재 폴더를 보여 준다. ghostty 명령만 못 찾는다면 앱의 CLI 경로인 /Applications/Ghostty.app/Contents/MacOS/ghostty를 사용할 수 있다. 셸·PATH 문제와 앱 설치 실패는 구분한다. Homebrew로 설치한 Claude Code는 해당 설치 방식의 업데이트 명령으로 관리한다.

4. 먼저 익힐 Ghostty 기본 조작

아래는 macOS용 Ghostty 1.3.1의 기본 바인딩이다. 사용자가 바꾼 값이나 다른 OS에는 그대로 적용되지 않을 수 있다. Cmd는 Command, Option은 ⌥다.

할 일단축키
새 창 / 새 탭Cmd+N / Cmd+T
오른쪽 분할 / 아래쪽 분할Cmd+D / Cmd+Shift+D
이전·다음 분할로 이동Cmd+[ / Cmd+]
방향을 지정해 분할 이동Cmd+Option+Arrow
글자 확대 / 축소Cmd++ / Cmd+-
검색Cmd+F
명령 팔레트Cmd+Shift+P
설정 열기 / 다시 읽기Cmd+, / Cmd+Shift+,

직접 기본값을 확인하려면 ghostty +list-keybinds --default를 사용한다. 명령 팔레트에서도 동작과 단축키를 찾을 수 있다. Ghostty 설정에서는 macOS의 Command를 super로 표기한다. (키 바인딩 안내)

5. 설정은 네 줄부터 시작하기

처음부터 테마·폰트·셸 플러그인을 한꺼번에 바꾸지 말고 Cmd+,로 실제 설정 파일을 연다. 현재 문서의 파일명은 config.ghostty이며, 이전 config 파일도 지원한다.

  • 공통 경로: ~/.config/ghostty/config.ghostty
  • macOS 경로: ~/Library/Application Support/com.mitchellh.ghostty/config.ghostty
  • $XDG_CONFIG_HOME을 지정했다면 공통 경로의 기준이 달라진다. 여러 파일이 있으면 뒤에 로드된 macOS 쪽 설정이 우선할 수 있다.

Ghostty 공식 문서가 config.ghostty와 XDG·macOS 설정 경로의 로딩 순서를 설명하는 화면

Ghostty 공개 설정 문서 캡처. 파일을 여러 곳에 만들기보다 현재 사용 중인 파일부터 확인한다. (출처, 2026-10-26 캡처)

기존 파일을 덮어쓰지 말고 다음 값만 추가하거나 수정한다.

font-size = 14
window-padding-x = 8
window-padding-y = 8
mouse-hide-while-typing = true

저장한 뒤 Cmd+Shift+,로 다시 읽는다. 옵션에 따라 새 터미널을 열어야 적용될 수도 있다. 문법은 ghostty +validate-config로 검사하고, 자세한 값은 옵션 참고 문서에서 확인한다. Option 기반 단축키가 필요할 때만 macos-option-as-alt = left를 검토한다. Option으로 입력하던 특수 문자의 동작도 바뀌므로 필수 설정으로 넣지 않는다.

6. Claude Code를 먼저 단독 실행해 보기

실제 작업할 프로젝트 폴더로 이동한 뒤 실행한다. 아래 경로는 자신의 프로젝트로 바꾼다.

cd /path/to/your/project
claude

첫 요청은 ‘이 프로젝트의 폴더 구조와 실행 방법을 설명해 주세요. 아직 파일은 수정하지 마세요’처럼 범위를 작게 잡는다. 터미널 앱의 편리함과 에이전트의 파일·명령 실행 권한은 별개다. 로그인과 권한 확인은 Claude Code 자체 안내를 따른다.

  • Enter는 전송, Ctrl+J 또는 \ 다음 Enter는 줄바꿈에 사용할 수 있다.
  • 현재 공식 문서는 Ghostty의 Shift+Enter를 별도 설정 없이 지원한다고 안내한다. tmux 안에서는 다음 절의 설정이 추가로 필요할 수 있다.
  • /theme으로 Claude 화면 테마를 맞출 수 있다. Ghostty 테마와 Claude의 표시 테마는 서로 다른 설정이다.

Claude Code 터미널 안내를 기준으로 하며, Ghostty 사용자 모두에게 /terminal-setup을 먼저 실행하라고 권하지 않는다.

7. tmux 분리·복귀를 직접 연습하기

tmux의 세션은 작업 묶음, 윈도는 그 안의 화면, 패널은 분할 영역이다. 처음에는 Ghostty 탭 하나 안에서 tmux가 분할을 담당하도록 두면 키가 덜 헷갈린다. 이미 tmux 안이라면 새 Ghostty 탭에서 실습해 중첩을 피한다.

mkdir -p ~/Projects/ghostty-lab
cd ~/Projects/ghostty-lab
tmux new-session -A -s ghostty-lab

-A는 같은 이름의 세션이 있으면 연결하고 없으면 만든다. 새 세션 안에서:

printf 'shell pid: %s\n' "$$"
sleep 300

PID를 기록한다. sleep이 실행되는 동안 Ctrl+B를 누르고 놓은 뒤 D를 누른다. 이것이 detach다. tmux 밖으로 나왔어도 서버와 명령은 남는다. 같은 맥의 새 Ghostty 탭에서 복귀한다.

tmux ls
tmux attach-session -t ghostty-lab

실행 중이던 sleep이 보이면 Ctrl+C로 실습 명령만 중단하고, 앞의 printf를 다시 실행해 같은 셸 PID인지 비교한다. 실제 프로젝트에서도 같은 방식으로 이름 붙인 세션 안에서 claude나 개발 서버를 실행한다. (tmux 공식 입문)

할 일tmux 기본 키: Ctrl+B를 먼저 누르고 놓기
세션에서 분리d
새 윈도 / 윈도 목록c / w
좌우 분할 / 위아래 분할% / "
패널 이동 / 현재 패널 확대방향키 / z
복사 모드 / 복사 모드 종료[ / q
tmux 복사 버퍼 붙여넣기]

Ghostty의 Cmd+D와 tmux의 Ctrl+B → %는 서로 다른 계층의 분할이다. Ghostty 창 복원도 tmux 프로세스 유지와 다르다. tmux가 실행되는 머신이 잠자기·재부팅·종료되면 작업의 지속 실행을 보장하지 않는다. 원격 작업을 유지하려면 SSH 접속 후 작업을 실행할 원격 머신에서 tmux를 시작한다. 맥 미니 원격 작업 안내도 함께 참고하자.

8. tmux 안에서 줄바꿈·알림이 다르게 동작한다면

현재 Claude Code 문서는 아래 설정을 안내한다. ~/.tmux.conf가 있다면 백업하고 해당 항목을 병합한다. 파일 전체를 다른 예제로 덮어쓰지 않는다.

set -g allow-passthrough on
set -g focus-events on
set -s extended-keys on
set -as terminal-features 'xterm*:extkeys'
tmux source-file ~/.tmux.conf

다시 detach·attach하고 Claude Code도 재시작한다. 확장 키는 Shift+Enter 구분에, passthrough는 지원되는 알림·진행 표시 전달에 관여한다. 지원하지 않는 옵션 오류가 나면 tmux -V와 설치 경로부터 확인하고 최신 지원 버전으로 업데이트한다. 알림의 최종 표시는 Ghostty와 macOS의 권한·설정에도 달려 있다.

Claude Code 공식 문서의 tmux 설정 네 줄과 다시 연결·재시작 안내

공개 공식 문서의 tmux 설정 부분 캡처. ‘외부 터미널에서는 되는데 tmux 안에서 안 되는’ 입력·표시 문제를 구분한다. (출처, 2026-10-26 캡처)

9. 스크롤·복사·이미지는 각각 구분하기

일반 셸 출력에서는 Ghostty의 선택·Cmd+C·Cmd+V가 출발점이다. tmux의 이전 출력은 Ctrl+B → [ 복사 모드로 탐색한다. tmux 복사 버퍼와 macOS 클립보드는 같은 저장소가 아니다. 시스템 클립보드 연동이 필요하면 tmux 공식 클립보드 안내를 따라 별도로 설정한다.

원한다면 ~/.tmux.conf에 아래를 병합해 마우스와 vi 방식 복사를 사용할 수 있다.

set -g mouse on
setw -g mode-keys vi

다시 설정을 읽은 뒤 복사 모드에서 Space로 선택을 시작하고 Enter로 tmux 버퍼에 복사한다. Ctrl+B → ]로 그 버퍼를 붙인다. 전체 화면 TUI에서는 앱 자체 스크롤과 tmux 복사 모드가 별개임을 기억한다.

또한 로컬 이미지 클립보드가 SSH 너머 Claude Code로 자동 전달되는 것은 아니다. 이미지 파일을 원격 환경에 보내는 단계는 SSH·tmux의 이미지 전달 안내에서 따로 다룬다.

10. 한글 입력·SSH·화면 문제 점검하기

증상먼저 비교할 것
한영 전환 직후 첫 글자 조합이 깨짐같은 입력기로 일반 셸, Claude 단독, tmux 안 Claude를 차례로 비교
조합 중인 글자·후보창 위치가 어긋남Ghostty 문제인지 CLI의 커서 위치 보고 문제인지 다른 터미널에서도 비교
Shift+Enter가 전송됨tmux 밖에서 먼저 시험하고 확장 키 설정·버전 확인
SSH에서 unknown terminal 오류원격 호스트의 xterm-ghostty terminfo 유무 확인
깜빡임·스크롤 점프Ghostty·tmux·Claude 버전, 창 크기, TUI 렌더링 모드를 나눠 비교

실제로 한글 입력 보고가 있다. Ghostty의 첫 글자 조합 보고는 1.3.1을 포함하지만, 저장소의 접수 정책 때문에 자동 종료된 사례다. 이를 유지관리자가 확인한 결함이나 수정 완료로 단정하지 않는다. Claude Code의 IME 위치 보고는 중복으로 종료되었다. Closed만 보고 해결됐다고 판단할 수 없다. 해당 증상을 직접 비교한 뒤 버전·입력기·최소 설정을 기록한다.

SSH의 terminfo 문제는 Ghostty 공식 안내를 따른다. 원격 서버에 tic가 있다면 해당 호스트에 항목을 설치할 수 있다. user@server는 실제 접속 대상으로 바꾼다.

infocmp -x xterm-ghostty | ssh user@server -- tic -x -

설치 권한이 없다면 한 번의 연결에만 TERM=xterm-256color ssh user@server를 사용하는 대안을 검토한다. 일부 기능은 줄어들 수 있다. 모든 셸의 TERM을 전역으로 덮어쓰지는 않는다. 또한 ghostty +ssh는 확인 시점 공식 문서상 1.4.0 예정 기능으로 1.3.x에는 없다. 문서의 tip 기능을 설치된 안정판 기능으로 혼동하지 말자. (SSH 기능 문서)

11. 일상적인 작업 배치 추천

처음에는 프로젝트별 tmux 세션 하나, 작업 창 두세 개로 시작한다. 하나는 Claude Code, 하나는 셸·버전 관리 확인, 필요하면 하나는 개발 서버다. 여러 에이전트가 같은 파일을 동시에 수정하게 만드는 것은 터미널 분할만으로 해결되지 않으므로 작업 범위도 나눈다.

짧은 로컬 명령만 사용한다면 Ghostty 탭만으로 충분하다. 세션 복귀가 필요하면 tmux를 더하고, iTerm2의 프로필과 -CC 통합이 이미 편하다면 그대로 유지해도 된다. Ghostty는 익숙한 CLI 도구의 화면·입력 환경을 개선하는 선택지이며, 좋은 작업 습관까지 자동으로 만들어 주는 도구는 아니다.

Related