Fullscreen 렌더링 — 깜빡임 없는 터미널 UI
/tui fullscreen으로 Claude Code의 렌더링 방식을 전환할 수 있습니다. 기본 모드와 다른 경로의 UI로, 깜빡임 제거·긴 대화 메모리 일정·마우스 지원을 제공합니다.
Fullscreen 렌더링은 옵트인 연구 프리뷰 기능이며 Claude Code v2.1.89 이상에서 동작합니다. 동작은 피드백에 따라 변경될 수 있습니다.
뭐가 달라지나
Claude Code는 기본적으로 터미널의 scrollback buffer에 대화를 쌓아 올립니다. Fullscreen 모드는 대신 alt-screen buffer(vim·htop이 쓰는 방식)에 그립니다.
| 기본 모드 | Fullscreen 모드 |
|---|---|
| 출력이 스트리밍되며 입력창이 밀려 올라감 | 입력창이 화면 하단 고정 |
| 재렌더링 시 깜빡임 | 깜빡임 제거 |
| 긴 대화 = 메모리 증가 | visible 메시지만 렌더 → 메모리 일정 |
| 터미널이 마우스 처리 | Claude Code가 마우스 이벤트 캡처 |
특히 VS Code 통합 터미널·tmux·iTerm2에서 렌더링 처리량이 병목이라 효과가 큽니다. 작업 중 스크롤 위치가 갑자기 상단으로 튀거나, 도구 출력이 스트리밍될 때 화면이 깜빡인다면 이 모드가 해결합니다.
여기서 "fullscreen"은 Claude Code가 터미널의 그리기 표면 전체를 점유한다는 뜻(vim과 동일). 터미널 창 크기 최대화와는 무관합니다. 어떤 크기에서도 동작합니다.
전환 방법
대화 중 전환
/tui fullscreen
tui 설정이 저장되고 CLI가 대화 유지한 채 relaunch합니다. 세션 중간에 전환해도 컨텍스트가 손실되지 않습니다.
현재 렌더러 확인:
/tui
원상 복귀:
/tui default
환경변수 방식 (v2.1.110 이전)
CLAUDE_CODE_NO_FLICKER=1 claude
tui 설정과 환경변수는 동등합니다. /tui 명령을 실행하면 relaunch 과정에서 CLAUDE_CODE_NO_FLICKER가 제거되고 tui 설정이 우선 적용됩니다.
마우스 사용
Fullscreen 모드는 마우스 이벤트를 Claude Code 내부에서 처리합니다.
| 동작 | 결과 |
|---|---|
| 프롬프트 입력 클릭 | 커서 위치 지정 |
| 축약된 도구 결과 클릭 | 펼치기/접기 (재클릭으로 토글). 펼칠 게 있는 메시지만 클릭 가능 |
| URL 클릭 | 브라우저에서 열기 (일반 단일 클릭) |
| 파일 경로 클릭 | 기본 애플리케이션에서 열기 |
| 클릭·드래그 | 텍스트 선택 (대화 어디서든) |
| 더블클릭 | 단어 선택 (iTerm2와 동일한 단어 경계 — 파일 경로는 하나로 선택) |
| 트리플클릭 | 줄 선택 |
| 마우스 휠 | 스크롤 |
이 터미널들에서는 Cmd-클릭을 유지합니다. Claude Code가 터미널의 링크 핸들러에게 위임해 링크 중복 오픈을 피합니다.
자동 클립보드 복사
마우스로 선택하면 선택 해제 시점에 자동으로 클립보드 복사. /config에서 Copy on select를 끄면 수동 전환됩니다.
수동 복사 단축키:
| 단축키 | 조건 |
|---|---|
Ctrl+Shift+C | 기본 |
Cmd+C | kitty·WezTerm·Ghostty·iTerm2 (kitty 키보드 프로토콜 지원 터미널) |
선택이 활성화된 상태에서 Ctrl+C는 취소가 아닌 복사로 동작합니다.
키보드로 선택 확장
선택이 활성화된 상태에서:
| 단축키 | 동작 |
|---|---|
Shift+↑ | 위로 선택 확장 (상단에서는 뷰포트도 스크롤) |
Shift+↓ | 아래로 선택 확장 |
Shift+← / Shift+→ | 한 열씩 확장 |
Shift+Home | 줄 시작까지 확장 |
Shift+End | 줄 끝까지 확장 |
스크롤·네비게이션
Fullscreen 모드는 스크롤도 Claude Code 내부가 처리합니다.
기본 단축키
| 단축키 | 동작 |
|---|---|
PgUp / PgDn | 반화면 스크롤 |
Ctrl+Home | 대화 시작으로 점프 |
Ctrl+End | 최신 메시지로 점프 + auto-follow 재개 |
| 마우스 휠 | 몇 줄씩 |
MacBook 키보드 매핑
PgUp·PgDn·Home·End 전용 키가 없는 MacBook에서는 Fn과 조합:
| MacBook | 대응 |
|---|---|
Fn+↑ | PgUp |
Fn+↓ | PgDn |
Fn+← | Home |
Fn+→ | End |
Ctrl+Fn+→ | 최하단 점프 |
어색하면 마우스 휠로 끝까지 스크롤해도 auto-follow 재개되며, scroll:bottom 액션을 다른 키에 재바인딩할 수도 있습니다 (키바인딩 참조).
Auto-follow
위로 스크롤하면 auto-follow 일시중지 — 새 출력이 나와도 시야가 바닥으로 끌려가지 않습니다. 재개:
Ctrl+End키- 마우스 휠로 바닥까지 스크롤
완전히 끄고 싶으면 /config → Auto-scroll을 off. 권한 프롬프트·응답 필요 다이얼로그는 이 설정과 무관하게 시야에 나타납니다.
마우스 휠 설정
마우스 휠 스크롤은 터미널이 Claude Code에 마우스 이벤트를 전달해야 작동합니다. iTerm2는 프로필 설정이라, 휠이 PgUp/PgDn만 동작하면:
Settings → Profiles → Terminal → Enable mouse reporting 체크.
클릭-펼치기·텍스트 선택도 같은 설정이 필요합니다.
휠 속도 조정
일부 터미널은 휠 이벤트 배율이 없어 느립니다 (VS Code 통합 터미널 등).
export CLAUDE_CODE_SCROLL_SPEED=3
- 값 1 (기본) ~ 20
- 3 = vim 기본값
Transcript 모드 — Ctrl+O
Ctrl+O 로 normal 프롬프트와 transcript 모드 간 토글. Transcript 모드는 less 스타일 네비게이션·검색을 지원합니다.
| 키 | 동작 |
|---|---|
/ | 검색 모드 (Enter로 확정, Esc로 취소) |
n / N | 다음/이전 매치 (검색 바 닫힌 뒤에도 동작) |
j / k 또는 ↑ / ↓ | 한 줄 스크롤 |
g / G 또는 Home / End | 상단/하단 점프 |
Ctrl+u / Ctrl+d | 반페이지 스크롤 |
Ctrl+b / Ctrl+f 또는 Space / b | 한 페이지 스크롤 |
Ctrl+O·Esc·q | 종료 후 프롬프트 복귀 |
터미널 native 검색과의 연결
터미널의 Cmd+f 또는 tmux 검색은 대화가 alt-screen buffer에 있어서 안 보입니다. 네이티브 도구로 전달하려면 transcript 모드 진입 후:
| 키 | 동작 |
|---|---|
[ | 전체 대화를 터미널 native scrollback에 씀 (도구 출력 전부 펼쳐서). 이후 Cmd+f·tmux copy mode·기타 네이티브 도구가 검색·선택 가능. Transcript 모드 종료(Esc·q) 시까지 유지 |
v | 임시 파일로 저장 후 $VISUAL or $EDITOR에서 열기 |
Ctrl+O를 다시 누르면 초기화돼 새로 시작합니다.
포커스 뷰 — /focus
/focus
조용한 뷰로 전환 — 마지막 프롬프트 1개, 한 줄 도구 호출 요약(diffstats 포함), 최종 응답만 표시. 나머지는 가려집니다.
- 설정이 세션 간 유지됨
/focus재실행으로 off- Fullscreen 렌더링 전용 (기본 모드에서는 동작 안 함)
회고할 때·복잡한 세션 요약만 확인할 때 유용합니다.
tmux 호환성
Fullscreen 렌더링은 tmux 안에서도 동작합니다 (두 가지 주의점만 있습니다).
1. tmux 마우스 모드 필수
휠 스크롤이 Claude Code로 전달되려면 tmux 마우스 모드가 켜져 있어야 합니다. ~/.tmux.conf에:
set -g mouse on
뒤 설정 재로드. 없으면 휠이 tmux로 가서 Claude Code가 못 받습니다 (키보드 PgUp/PgDn은 양쪽 다 동작). Claude Code가 tmux 감지 시 시작 시 1회 힌트를 출력합니다.
2. iTerm2 tmux integration mode 비호환
tmux -CC # ❌ Fullscreen 불가
이 모드는 iTerm2가 각 tmux 창을 native split으로 렌더해 alt-screen buffer·마우스 추적이 정상 동작하지 않습니다. 휠이 안 돌거나 더블클릭이 터미널 상태를 망가뜨릴 수 있습니다.
일반 tmux (tmux 그냥 실행, -CC 없이)는 iTerm2 안에서도 정상 작동합니다.
네이티브 텍스트 선택 유지
SSH·tmux 사용자는 마우스 캡처가 가장 큰 마찰점입니다. Claude Code가 마우스 이벤트를 캡처하면 터미널의 native copy-on-select이 멈춥니다. 드래그로 만든 선택이 Claude Code 안에만 존재해서 tmux copy mode·Kitty hints 등 네이티브 도구가 못 봅니다.
Claude Code는 클립보드 쓰기를 시도합니다:
- tmux 안: tmux paste buffer로 씀
- SSH 너머: OSC 52 이스케이프 시퀀스 (일부 터미널이 차단)
각 복사 후 어느 경로를 썼는지 토스트로 알림.
마우스만 끄는 방법
CLAUDE_CODE_NO_FLICKER=1 CLAUDE_CODE_DISABLE_MOUSE=1 claude
깜빡임 없는 렌더링·메모리 일정은 유지하면서 마우스 캡처만 off. 터미널이 native로 선택 처리.
잃는 것: 클릭 커서 위치, 클릭 도구 펼치기, URL 클릭, 휠 스크롤. 키보드 스크롤(PgUp·PgDn·Ctrl+Home·Ctrl+End)은 그대로.
키바인딩 커스터마이즈
Scroll 컨텍스트의 모든 액션이 재바인딩 가능합니다. ~/.claude/keybindings.json에서 편집.
주요 Scroll 액션 (공식 참조):
| 액션 | 기본 키 | 설명 |
|---|---|---|
scroll:lineUp | (unbound) | 한 줄 위로. 마우스 휠이 이 액션 발동 |
scroll:lineDown | (unbound) | 한 줄 아래로 |
scroll:pageUp | PageUp | 반 화면 위로 |
scroll:pageDown | PageDown | 반 화면 아래로 |
scroll:top | Ctrl+Home | 대화 시작 |
scroll:bottom | Ctrl+End | 최신 + auto-follow 재개 |
scroll:halfPageUp / halfPageDown | (unbound) | vi 스타일 바인드용 |
scroll:fullPageUp / fullPageDown | (unbound) | 전 화면 스크롤 |
selection:copy | Ctrl+Shift+C / Cmd+C | 선택 복사 |
selection:extendLeft/Right/Up/Down | Shift+←/→/↑/↓ | 선택 확장 |
selection:extendLineStart/End | Shift+Home/End | 줄 경계까지 확장 |
예시 — vim 사용자가 G 로 최하단 점프 바인딩:
{
"bindings": [
{
"context": "Scroll",
"bindings": {
"shift+g": "scroll:bottom"
}
}
]
}
언제 쓰면 좋나
- VS Code 통합 터미널·tmux·iTerm2에서 깜빡임 경험
- 매우 긴 대화 세션 (메모리 이슈)
- 마우스 기반 복사 작업 빈도 높음
/focus로 깔끔한 뷰 원함
흔하지 않은 터미널·특이 설정에서 렌더링 이슈 가능. 문제 발견 시:
/feedback안에서 제보- claude-code GitHub 이슈 오픈
- 터미널 이름·버전 포함
원상 복귀
/tui default
환경변수로 켰다면 CLAUDE_CODE_NO_FLICKER·CLAUDE_CODE_DISABLE_MOUSE 제거.
관련 문서
- 슬래시 커맨드 —
/tui·/focus커맨드 - 공식 Fullscreen 문서 — 최신·영문
- 공식 Keybindings 참조 — 전체 액션 목록
/config설정 — Auto-scroll·Copy on select 토글
Fullscreen 렌더링은 Claude Code 터미널 UX의 패러다임 전환 옵션입니다. 기본 모드가 익숙하면 그대로 써도 되고, 깜빡임·긴 대화·마우스 활용이 필요하면 전환하면 됩니다. /tui fullscreen 한 번 쳐보고 /tui default로 돌아갈 수 있으니 부담 없이 시도할 수 있습니다.