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"의 의미

여기서 "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와 동일한 단어 경계 — 파일 경로는 하나로 선택)
트리플클릭	줄 선택
마우스 휠	스크롤

VS Code 통합 터미널·xterm.js 기반 터미널

이 터미널들에서는 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)은 그대로.

스크린리더 모드

VoiceOver·NVDA 같은 스크린리더를 쓴다면 스크린리더 모드가 별도로 있습니다. Fullscreen과는 반대 방향의 기능으로, 터미널 UI를 평평한 선형 텍스트로 대체합니다.

Fullscreen과의 관계

스크린리더 모드가 켜져 있으면 tui 설정은 무시되고 항상 일반 스크롤 텍스트로 렌더됩니다. 즉 /tui fullscreen을 켜 둬도 스크린리더 모드가 우선합니다. (백그라운드 세션에 attach한 경우는 예외로 alt-screen에 그려집니다.)

켜는 법

세 가지 방법이 있고, 위쪽이 우선합니다.

범위	방법
이번 세션만	claude --ax-screen-reader
이 셸에서 시작하는 세션	export CLAUDE_AX_SCREEN_READER=1 (PowerShell은 $env:CLAUDE_AX_SCREEN_READER = "1")
이 머신의 모든 세션	사용자 설정 파일에 "axScreenReader": true

켜지면 시작 시 어느 방법으로 켜졌는지 확인 줄이 출력됩니다 — [Screen Reader Mode: on via flag] / on via env / on via settings. 끌 때는 켠 방법을 되돌리면 되고, CLAUDE_AX_SCREEN_READER=0은 설정이 true여도 off를 유지합니다. SSH로 쓴다면 Claude Code가 실제로 도는 원격 머신에 설정해야 합니다.

버전

스크린리더 모드는 v2.1.181 이상 필요 — 그 이전 버전은 --ax-screen-reader 플래그를 모릅니다. 켠 방법을 이름으로 알려주는 확인 줄 형식은 v2.1.206부터고, 그 전에는 [Accessible screen reader mode: on]으로 나옵니다. 체인지로그에는 v2.1.208 항목으로 정식 안내됐습니다.

뭐가 달라지나

• 인터페이스 chrome의 박스 문자 없음, 색으로만 구분하는 표시 없음
• 변하지 않은 내용을 다시 그리지 않음 — 스피너도 정적 텍스트로
• 응답 속 표가 격자 대신 Header: value 문장으로 읽힘 (v2.1.198 이상)
• 출력이 터미널 scrollback에 그대로 쌓여 스크린리더 리뷰 명령·터미널 검색으로 되짚기 가능

각 메시지는 스크린리더가 읽을 라벨로 시작합니다 — you:(내 메시지), claude:(응답), tool:(도구 활동), tool error:, error:, Permission Required:(대기 중인 권한 프롬프트), Cost:(종료 시 비용 요약). 라벨은 검색도 되므로 scrollback에서 구간 점프에 쓸 수 있습니다.

턴 경계에는 OSC 133 셸 통합 마커를 내보내서, 터미널의 이전 프롬프트로 점프 기능이 동작합니다 (iTerm2 Cmd+Shift+Up, VS Code 터미널 Ctrl+Up·macOS는 Cmd+Up). Windows Terminal은 기본 키가 없어 scrollToMark 액션을 직접 바인딩해야 하고, macOS Terminal·WezTerm은 이 경로가 안 되므로 you: 라벨 검색으로 대체합니다.

메뉴·프롬프트 응답

화살표 키로 고르던 메뉴(권한 프롬프트 포함)가 번호 목록으로 바뀝니다. 각 선택지가 번호 줄로 읽히고 유효 범위를 알려주는 Enter selection 프롬프트가 따라옵니다. 원하는 번호를 입력하고 Enter. 취소 가능한 메뉴는 Escape, 예/아니오는 y/n(또는 yes/no) 입력입니다.

또 주의가 필요한 시점에 터미널 벨이 울립니다 — 응답 완료·권한 프롬프트 등장·5초 넘게 돈 도구의 완료. 벨은 터미널 쪽 설정으로 끕니다.

스크린리더가 아닌 경우

• CLAUDE_CODE_ACCESSIBILITY=1 — 화면 확대기용. 네이티브 터미널 커서를 계속 보이게 유지해 macOS Zoom 같은 확대기가 커서를 추적할 수 있게 합니다
• prefersReducedMotion 설정 — 스피너·시머 등 애니메이션만 줄이거나 끕니다
• theme 설정 — 색각 보정 테마 dark-daltonized·light-daltonized 포함

알려진 한계

• 스크린리더가 실행 중이어도 자동으로 켜지지 않습니다 (수동 옵트인)
• Shift+Tab 순환 외의 방법으로 바뀐 권한 모드는 안내되지 않습니다 (순환 시 안내는 v2.1.210 이상)
• 비용은 턴마다가 아니라 종료 시 요약에서만 읽힙니다
• -p 비대화형 모드는 원래 평문이라 이 모드의 영향을 받지 않습니다

키바인딩 커스터마이즈

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로 돌아갈 수 있으니 부담 없이 시도할 수 있습니다.