Ghostty 사용 가이드

Ghostty 사용 가이드 (macOS)

버전: 1.3.0 기준
**설정 파일: ~/.config/ghostty/config설정 열기: Cmd+, 또는 직접 편집
**설정 반영: 저장 시 자동 반영 (재시작 불필요)

1. 기본 단축키 (macOS)

윈도우 / 탭

분할 (Split)

스크롤 / 검색

복사 / 붙여넣기

폰트 크기

기타

2. SSH 접속 (Tailscale 원격 환경)

기본 SSH 접속

# Ghostty 열고 바로 입력
ssh user@100.x.x.x

# 또는 Tailscale 호스트명으로
ssh user@windows-pc

SSH 설정 파일로 간편 접속

~/.ssh/config 파일에 추가:

Host win-dev
    HostName 100.x.x.x
    User okesh
    Port 2222
    # WSL2 SSH 포트가 다르면 맞춰서 변경

이후:

ssh win-dev

SSH + tmux 워크플로

# 접속 후 tmux 세션에 바로 붙기
ssh win-dev -t "tmux a -t dev || tmux new -s dev"

이 명령을 Ghostty 키바인딩으로 등록 가능:

# ~/.config/ghostty/config
keybind = cmd+shift+s=new_window:ssh win-dev -t "tmux a -t dev || tmux new -s dev"

Cmd+Shift+S 누르면 SSH 접속 + tmux 세션 자동 연결.

SSH 접속 시 terminfo 경고 해결

원격 서버에서 xterm-ghostty terminfo를 못 찾을 수 있음:

# 방법 1: Ghostty 설정에서 TERM 변경
# ~/.config/ghostty/config
term = xterm-256color

# 방법 2: SSH 설정에서만 변경
# ~/.ssh/config
Host win-dev
    SetEnv TERM=xterm-256color

3. Quick Terminal (드롭다운 터미널)

iTerm2의 핫키 윈도우를 대체하는 기능. 어디서든 단축키로 터미널을 불러올 수 있음.

설정

# ~/.config/ghostty/config
keybind = global:ctrl+grave_accent=toggle_quick_terminal
quick-terminal-position = top
quick-terminal-animation-duration = 0.15

• ctrl+grave_accent = Ctrl+` (백틱 키)
• global: 접두사가 있어야 Ghostty가 포커스 없어도 동작
• macOS 시스템 설정 → 개인정보 보호 및 보안 → 손쉬운 사용에서 Ghostty 허용 필요

Quick Terminal 위치 옵션

quick-terminal-position = top      # 위에서 내려옴 (기본)
quick-terminal-position = bottom   # 아래에서 올라옴
quick-terminal-position = left     # 왼쪽에서 나옴
quick-terminal-position = right    # 오른쪽에서 나옴
quick-terminal-position = center   # 화면 중앙

4. 알림 (Notifications)

명령 완료 알림 (v1.3.0+)

긴 명령이 끝나면 macOS 알림을 보냄:

# ~/.config/ghostty/config

# 5초 이상 걸린 명령이 끝나면 알림
notify-on-command-finish = 5s

# 포커스가 없을 때만 알림
# notify-on-command-finish = unfocused

Claude Code 알림 (tmux 안에서)

tmux가 OSC 알림 시퀀스를 가로채기 때문에 별도 설정 필요:

# ~/.tmux.conf에 추가
set -g allow-passthrough on

5. 설정 파일 주요 옵션

현재 설정 (참고)

# 폰트
font-family = MesloLGS Nerd Font
font-size = 13

# 테마
theme = catppuccin-mocha

# 창
window-padding-x = 10
window-padding-y = 8
window-padding-balance = true
macos-titlebar-style = tabs

# 투명도
background-opacity = 0.93
macos-window-shadow = true

# 커서
cursor-style = bar
cursor-style-blink = true

# 스크롤
scrollback-limit = 50000

# macOS
macos-option-as-alt = true

# Shift+Enter (tmux 안에서도 동작)
keybind = shift+enter=text:\x1b\r

# Quick Terminal
keybind = global:ctrl+grave_accent=toggle_quick_terminal
quick-terminal-position = top
quick-terminal-animation-duration = 0.15

자주 쓰는 설정 옵션

키바인딩 커스텀

# 기본 형식: keybind = 키조합=액션

# 글로벌 키바인딩 (Ghostty가 포커스 없어도 동작)
keybind = global:cmd+grave_accent=toggle_quick_terminal

# 액션 체이닝 (v1.3.0+)
keybind = cmd+shift+f=chain:toggle_fullscreen,toggle_window_decorations

# SSH 바로 접속 윈도우
keybind = cmd+shift+s=new_window:ssh win-dev

# 스크롤백을 에디터에서 열기
keybind = cmd+shift+e=write_scrollback_file:open

6. 테마 관리

설치된 테마 확인

ls ~/.config/ghostty/themes/
# 또는 Ghostty 내장 테마
ls /Applications/Ghostty.app/Contents/Resources/ghostty/themes/

테마 변경

# ~/.config/ghostty/config
theme = catppuccin-mocha

저장하면 바로 적용.

라이트/다크 자동 전환

theme = light:catppuccin-latte,dark:catppuccin-mocha

macOS 다크모드 전환 시 자동으로 테마가 바뀜.

7. Shell Integration

Ghostty는 셸 통합 기능을 자동으로 설정함 (bash, zsh, fish 지원). 이를 통해:

• 프롬프트에서 클릭으로 커서 이동 (v1.3.0+)
• 명령 완료 알림
• 새 탭/분할에서 현재 디렉토리 유지

별도 설정 없이 자동 동작. 문제가 있으면:

# 셸 통합 상태 확인
echo $GHOSTTY_SHELL_INTEGRATION

8. 문제 해결

9. 참고 링크

• 공식 문서: https://ghostty.org/docs
• 설정 레퍼런스: https://ghostty.org/docs/config/reference
• 키바인딩 액션 목록: https://ghostty.org/docs/config/keybind/reference
• 릴리스 노트 (1.3.0): https://ghostty.org/docs/install/release-notes/1-3-0
• GitHub: https://github.com/ghostty-org/ghostty