클로드 코드 tmux 스크롤 안 될 때: 원인 세 가지와 확인 순서

tmux 안에서 AI 도구 화면이 휠로 올라가지 않는다면 원인은 하나가 아닙니다. 이 글에서 다루는 원인은 tmux 마우스 모드, Codex CLI(코덱스 CLI)의 대체 화면, Claude Code(클로드 코드)의 전체 화면 렌더링 세 가지입니다. 어느 쪽인지부터 가려야 합니다.

위로 올라가려고 마우스 휠을 굴렸는데 대화는 움직이지 않습니다. 대신 입력창에서 이전에 보낸 프롬프트가 하나씩 바뀌기도 합니다. Esc를 눌러도 화면은 올라가지 않고 다른 오버레이가 열리거나 Failed to branch before the selected prompt 오류가 뜰 수도 있습니다.

이 글은 2026년 9월 기준이며 Claude Code 2.1.246과 Codex CLI 0.151.0에서 확인했습니다. tmux 마우스 설정부터 살펴보고 두 도구의 렌더링 설정을 각각 고치겠습니다. 전체 화면을 유지하는 방법과 지금 열린 세션의 기록을 보는 방법도 함께 알아보겠습니다.

대체 화면 (alternate screen)

전체 화면 프로그램이 잠시 쓰는 별도 화면입니다. 이 화면의 내용은 평소 터미널 스크롤백에 쌓이지 않습니다.

왜 안 올라가나: 터미널에는 화면이 두 개다

터미널에는 평소 명령어를 입력하는 주 화면과 전체 화면 프로그램이 쓰는 대체 화면이 있습니다. 주 화면에는 지나간 출력이 차곡차곡 남습니다. 이 기록이 위로 올려 볼 수 있는 스크롤백입니다.

대체 화면에는 같은 방식의 스크롤백이 쌓이지 않습니다. 프로그램을 닫으면 대체 화면은 사라지고 원래 주 화면이 돌아옵니다. vim이나 less를 닫았을 때 실행 전 화면으로 돌아오는 것과 같은 구조입니다. 휠이 고장 난 것이 아니라 올라가서 볼 기록이 평소 화면에 남지 않은 상태입니다.

어느 원인인지부터 가립니다

tmux 스크롤 안됨이라는 증상만 보고 대체 화면부터 끄면 빗나갈 수 있습니다. 아래 표의 첫 줄부터 확인하면 사용 중인 환경에 맞는 해결책을 바로 찾을 수 있습니다.

먼저 tmux 마우스 모드를 확인합니다. 휠이 작동하기 시작하면 첫 번째 원인이 맞습니다. 그래도 해결되지 않으면 실행 중인 도구에 맞춰 다음 설정을 확인합니다.

tmux 마우스 모드부터 켭니다: set -g mouse on

tmux 마우스 모드는 휠 이벤트를 안에서 실행 중인 프로그램에 전달하는 설정입니다. ~/.tmux.conf는 tmux 설정을 적어 두는 숨김 텍스트 파일입니다. 앞의 ~는 현재 사용자의 홈 폴더를 뜻합니다. 파일이 없어도 새로 만들 수 있습니다.

아래 명령은 Claude Code나 Codex CLI 입력창이 아니라 새 터미널의 셸에서 실행합니다.

nano ~/.tmux.conf

파일에 다음 한 줄을 추가합니다. 이미 set -g mouse off가 있다면 off를 on으로 바꿉니다.

set -g mouse on

nano는 터미널 안에서 도는 간단한 편집기입니다. 화면 아래쪽에 쓸 수 있는 단축키가 늘 떠 있으니 외울 필요가 없습니다. Ctrl+O와 Enter를 차례로 눌러 저장하고 Ctrl+X로 나옵니다. 저장한 설정을 현재 tmux에 적용하려면 셸에서 다음 명령을 실행합니다.

tmux source-file ~/.tmux.conf

이제 AI 도구 화면으로 돌아가 휠을 다시 움직여 봅니다. Claude Code에서 전체 화면 렌더링을 쓰는 중이라면 마우스 모드가 꺼져 있어도 PgUp과 PgDn을 이용한 키보드 스크롤은 작동합니다. 키보드는 되는데 휠만 안 됐다면 이 설정이 원인이었을 가능성이 큽니다.

코덱스는 대체 화면을 끕니다: --no-alt-screen

Codex CLI는 새 세션을 시작할 때 아래처럼 실행하면 됩니다.

codex --no-alt-screen

이 옵션은 대체 화면 모드를 끄고 Codex CLI를 인라인 모드로 실행합니다. 지나간 출력이 주 화면의 스크롤백에 남으므로 대화가 길어져도 이전 내용을 다시 볼 수 있습니다. tmux에서 Codex CLI를 자주 쓴다면 매번 복사 모드로 들어가기보다 이 옵션으로 시작하는 편이 낫습니다.

CLI 옵션은 버전에 따라 달라질 수 있습니다. 먼저 현재 설치된 Codex CLI의 도움말을 엽니다.

codex --help

도움말에서 --no-alt-screen을 찾으세요. 인라인 모드로 실행해 터미널 스크롤백을 보존한다는 설명이 있으면 이 글과 같은 방식으로 쓸 수 있습니다. 이 글에서 확인한 버전은 0.151.0입니다.

클로드 코드는 클래식 렌더러로 되돌립니다

렌더러는 Claude Code가 터미널에 대화를 그리는 방식입니다. 전체 화면 렌더링은 아직 연구 미리보기 단계이지만, 2026년 5월 6일 이후 Claude Code를 처음 쓴 세션이라면 이미 기본값으로 켜져 있을 수 있습니다. /tui fullscreen을 실행하거나 CLAUDE_CODE_NO_FLICKER=1 환경 변수를 설정해 직접 켤 수도 있습니다.

/로 시작하는 슬래시 명령은 터미널 셸이 아니라 Claude Code 입력창에 적는 명령입니다. 인수 없이 /tui를 실행하면 지금 전체 화면 렌더러와 클래식 렌더러 중 어느 쪽인지 확인할 수 있습니다. 전체 화면으로 나온다면 같은 입력창에서 다음 명령을 실행합니다.

/tui default

클래식 렌더러는 대화를 터미널의 기본 스크롤백에 유지합니다. 따라서 Cmd+f와 tmux 복사 모드가 평소대로 작동합니다.

환경 변수는 프로그램을 실행할 때 전달하는 이름과 값입니다. 저장된 tui 설정과 관계없이 클래식 렌더러를 강제로 쓰려면 Claude Code를 종료한 뒤 셸에서 다음처럼 실행합니다.

CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN=1 claude

전체 화면을 유지하면서 스크롤하려면

전체 화면 렌더링을 계속 쓰고 싶다면 Claude Code 안에서 스크롤합니다. 이때 대화는 터미널의 기본 스크롤백이 아니라 대체 화면 버퍼에 있습니다.

MacBook 키보드에는 PgUp, PgDn, Home, End 전용 키가 없습니다. Fn+↑는 PgUp, Fn+↓는 PgDn, Fn+←는 Home, Fn+→는 End를 보냅니다. 다만 Ctrl+Fn+→는 macOS에서 Claude Code까지 도달하지 않습니다. 맨 아래로 가는 기본 단축키 대신 Jump to bottom 버튼을 클릭하거나 휠로 맨 아래까지 내립니다.

지난 대화를 검색하거나 터미널 스크롤백으로 옮기려면 트랜스크립트 모드를 씁니다.

• Ctrl+o는 일반 프롬프트와 트랜스크립트 모드를 오갑니다.
• /로 검색하고 n과 N으로 다음 또는 이전 일치 항목으로 이동합니다.
• [를 누르면 전체 대화를 터미널의 기본 스크롤백 버퍼에 씁니다. 그 뒤에는 Cmd+f와 tmux 복사 모드로 내용을 찾을 수 있습니다.
• q나 Esc를 누르면 트랜스크립트 모드에서 나옵니다.

여기서 [는 Ctrl+o로 트랜스크립트 모드에 들어간 뒤 누르는 Claude Code 키입니다. tmux 복사 모드처럼 Ctrl+b를 먼저 누르지 않습니다.

터미널 환경에 따른 주의점도 둘 있습니다. iTerm2의 tmux 통합 모드는 전체 화면 렌더링과 호환되지 않습니다. tmux -CC로 들어간 세션에서는 휠이 작동하지 않고 더블 클릭이 터미널 상태를 손상시킬 수 있습니다. -CC 없이 실행한 일반 tmux는 정상적으로 작동합니다.

tmux 3.6 이하에서는 동기화된 출력을 지원하지 않아 화면을 다시 그릴 때 깜빡임이 더 보일 수 있습니다. 아래 명령으로 현재 버전을 확인할 수 있습니다.

tmux -V

지금 열린 세션에서 당장 보려면: tmux 복사 모드

이미 열린 세션에서 tmux가 보관한 내용을 보고 싶다면 복사 모드가 가장 빠릅니다. 안에서 Claude Code가 돌든 Codex CLI가 돌든 들어가는 방법은 같습니다. Claude Code 전체 화면의 대화 전체를 보려면 먼저 Ctrl+o를 누른 뒤 [로 대화를 기본 스크롤백에 써야 합니다.

1. 키보드의 Control 키를 누른 채 b를 한 번 누릅니다.
2. 두 키에서 손을 뗀 다음 [를 누릅니다.
3. 방향키나 PgUp으로 위로 올라갑니다. MacBook에서는 Fn+↑를 누릅니다.
4. 다 봤다면 q를 눌러 복사 모드에서 나옵니다.

세 키를 동시에 누르는 것이 아닙니다. Ctrl+b를 먼저 누르고 손을 뗀 뒤 [를 누릅니다. Ctrl+b는 다음 키를 tmux 명령으로 받게 하는 접두키입니다. 이 글은 tmux 기본값을 기준으로 합니다. 접두키를 직접 바꿨다면 Ctrl+b 대신 바꾼 키를 써야 합니다.

저라면 이미 작업 중인 세션에서는 이 방법부터 씁니다. 실행 중인 대화를 끝낼 필요가 없고 도구 종류도 가리지 않기 때문입니다.

Esc는 스크롤 키가 아닙니다

화면이 안 올라갈 때 Esc를 반복해서 누르면 이전 프롬프트로 돌아가는 오버레이가 열릴 수 있습니다. 이 화면에서 프롬프트를 고른 뒤 Failed to branch before the selected prompt 오류가 뜨기도 합니다. 실제로 tmux 안에서 Codex CLI를 쓰던 화면에 나타난 오류입니다.

Esc는 스크롤 단축키가 아닙니다. 눌러도 지난 대화가 위로 올라가지 않습니다. tmux 복사 모드에 들어갈 때는 Ctrl+b 다음 [, 나올 때는 q를 누르면 됩니다.