Claude Chill: Claude Code 터미널 깜빡임과 지연 문제를 해결하는 PTY 프록시 도구

Claude Code를 터미널에서 사용하다 보면 화면이 계속 깜빡이거나, 출력이 느려지고, 스크롤백이 사라지는 불편함을 겪은 적이 있을 것입니다. 이 글에서는 이러한 문제의 원인과 함께, 이를 해결하기 위해 만들어진 Claude Chill이라는 도구가 어떤 방식으로 문제를 완화하는지, 주요 기능과 동작 원리, 그리고 실제 설치와 사용 방법까지 정리해 소개합니다. 터미널 환경에서 Claude Code를 보다 안정적이고 가독성 있게 사용하고 싶은 개발자라면 끝까지 읽어볼 만한 내용입니다.

반응형

---

Claude Code 터미널 출력 문제의 배경

Claude Code는 터미널 출력을 처리할 때, 화면 전체를 하나의 동기화 출력(sync block) 으로 감싸 한 번에 렌더링합니다. 이 방식은 일관된 화면을 보장하는 장점이 있지만, 다음과 같은 문제를 유발합니다.

• 수천 줄에 달하는 전체 화면 재렌더링
• 터미널 응답 지연
• 화면 깜빡임 현상
• 스크롤백 히스토리 손실

특히 출력량이 많은 작업을 수행할수록 이러한 문제는 더 자주, 더 크게 체감됩니다.

---

Claude Chill이란 무엇인가

Claude Chill은 이러한 터미널 출력 문제를 해결하기 위해 만들어진 PTY(가상 터미널) 프록시 프로그램입니다. Claude Code와 터미널 사이에 위치해, 출력 방식을 중간에서 조정하는 역할을 합니다.

구조는 다음과 같습니다.

Terminal ⇄ claude-chill ⇄ Claude Code

Claude Chill은 Claude Code의 출력을 그대로 터미널에 전달하지 않고, 화면 상태를 추적한 뒤 변경된 부분만 갱신하도록 처리합니다. 이를 통해 불필요한 전체 화면 갱신을 줄이고, 성능과 가독성을 동시에 개선합니다.

---

주요 기능 정리

1. Sync 블록 가로채기

Claude Chill은 Claude Code가 보내는 대규모 동기화 블록을 감지합니다. 이 블록을 그대로 출력하지 않고, 내부적으로 처리해 실제로 변경된 내용만 반영합니다.

2. VT100 기반 렌더링

내부적으로 VT100 에뮬레이터를 사용해 현재 화면 상태를 추적합니다. 이전 상태와 새로운 상태를 비교해 차이만 렌더링함으로써, 깜빡임과 지연을 크게 줄입니다.

3. 히스토리 유지와 룩백 모드

출력 내용을 내부 히스토리 버퍼에 저장해 스크롤백이 가능합니다.

• Ctrl+6 키로 룩백 모드 진입
• Claude Code의 출력을 일시 중단
• 지금까지의 전체 출력 기록을 터미널에 표시
• 다시 키를 누르거나 Ctrl+C로 종료

macOS에서는 Ctrl+Shift+6 (Ctrl+^) 조합으로 동일하게 동작합니다.

4. 자동 룩백(auto-lookback) 기능

일정 시간(기본 15초) 동안 입력이 없으면 자동으로 히스토리를 덤프해 전체 로그를 확인할 수 있습니다.

• 자동 룩백은 옵션으로 비활성화 가능
• 자동 덤프 시 화면이 잠깐 깜빡일 수 있음

---

설치 방법

Claude Chill은 Rust 기반 도구로, cargo를 통해 설치합니다.

cargo install --path crates/claude-chill

---

실행 및 사용 예시

Claude Chill은 기존 Claude Code 실행 명령 앞에 붙여 사용하는 방식입니다.

# 기본 실행
claude-chill claude

# Claude Code에 인자 전달
claude-chill -- claude --verbose

# 히스토리 최대 줄 수 지정
claude-chill -H 50000 claude

# 자동 룩백 기능 비활성화
claude-chill -a 0 claude

주요 옵션 정리

• -H, --history : 히스토리 최대 줄 수 (기본 100,000)
• -k, --lookback-key : 룩백 모드 전환 키
• -a, --auto-lookback-timeout : 자동 룩백 대기 시간(ms)

---

설정 파일로 세부 동작 조정하기

Claude Chill은 설정 파일을 통해 세부 동작을 제어할 수 있습니다.

설정 파일 위치

• Linux: ~/.config/claude-chill.toml
• macOS: ~/Library/Application Support/claude-chill.toml

주요 설정 항목

• history_lines : 히스토리 최대 줄 수
• lookback_key : 룩백 모드 전환 키
• refresh_rate : 렌더링 FPS
• auto_lookback_timeout_ms : 자동 룩백 시간

---

키보드 프로토콜과 키 설정

Claude Chill은 Kitty Keyboard Protocol을 지원하는 터미널에서 더 자연스럽게 동작합니다.

• 지원 터미널: Kitty, Ghostty, WezTerm 등
• Claude Code가 Kitty 모드를 활성화하면, Claude Chill도 자동 인식

키 설정은 다음 형식을 따릅니다.

[modifier][key]

예시:

• [f12]
• [ctrl][g]
• [ctrl][shift][j]

기본 룩백 키인 Ctrl+6은 ASCII 0x1E를 전송해 대부분의 터미널과 충돌하지 않습니다.

---

내부 동작 방식 요약

Claude Chill의 처리 흐름은 다음과 같습니다.

1. 가상 터미널(PTY) 생성
2. Claude Code를 자식 프로세스로 실행
3. 입력은 그대로 전달하되, 룩백 키만 차단
4. 출력에서 동기화 블록 탐지
5. VT 에뮬레이션으로 화면 상태 추적
6. 이전 상태와 비교해 변경된 부분만 렌더링
7. 히스토리 버퍼 유지 및 룩백 모드 지원
8. SIGWINCH, SIGINT, SIGTERM 등의 신호를 Claude Code로 전달

---

728x90

Claude Chill은 Claude Code 자체를 수정하지 않고도, 터미널 환경에서 발생하는 출력 지연과 깜빡임 문제를 효과적으로 완화하는 경량 솔루션입니다. 전체 화면을 반복적으로 다시 그리는 구조적 한계를, 출력 차이만 반영하는 방식으로 우회했다는 점이 핵심입니다.

터미널 성능과 가독성을 동시에 개선하고, 출력 히스토리를 안정적으로 관리하고 싶다면 Claude Chill은 충분히 고려해볼 만한 도구입니다. 특히 Linux와 macOS 환경에서 Claude Code를 자주 사용하는 개발자에게는 작업 흐름의 스트레스를 줄여줄 실질적인 대안이 될 수 있습니다.

300x250

https://github.com/davidbeesley/claude-chill

GitHub - davidbeesley/claude-chill