Skip to main content

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+Ckitty·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:pageUpPageUp반 화면 위로
scroll:pageDownPageDown반 화면 아래로
scroll:topCtrl+Home대화 시작
scroll:bottomCtrl+End최신 + auto-follow 재개
scroll:halfPageUp / halfPageDown(unbound)vi 스타일 바인드용
scroll:fullPageUp / fullPageDown(unbound)전 화면 스크롤
selection:copyCtrl+Shift+C / Cmd+C선택 복사
selection:extendLeft/Right/Up/DownShift+←/→/↑/↓선택 확장
selection:extendLineStart/EndShift+Home/End줄 경계까지 확장

예시 — vim 사용자가 G 로 최하단 점프 바인딩:

{
  "bindings": [
    {
      "context": "Scroll",
      "bindings": {
        "shift+g": "scroll:bottom"
      }
    }
  ]
}

언제 쓰면 좋나​

  • VS Code 통합 터미널·tmux·iTerm2에서 깜빡임 경험
  • 매우 긴 대화 세션 (메모리 이슈)
  • 마우스 기반 복사 작업 빈도 높음
  • /focus로 깔끔한 뷰 원함
연구 프리뷰 상태

흔하지 않은 터미널·특이 설정에서 렌더링 이슈 가능. 문제 발견 시:

원상 복귀​

/tui default

환경변수로 켰다면 CLAUDE_CODE_NO_FLICKER·CLAUDE_CODE_DISABLE_MOUSE 제거.

관련 문서​

Fullscreen 렌더링은 Claude Code 터미널 UX의 패러다임 전환 옵션입니다. 기본 모드가 익숙하면 그대로 써도 되고, 깜빡임·긴 대화·마우스 활용이 필요하면 전환하면 됩니다. /tui fullscreen 한 번 쳐보고 /tui default로 돌아갈 수 있으니 부담 없이 시도할 수 있습니다.

Last updated on