Claude Chill: 터미널에서 Claude Code의 깜빡임 현상 수정하기

• Claude Chill은 Claude Code가 터미널 전체를 반복적으로 다시 그릴 때 발생하는 지연과 깜빡임 문제를 완화하는 PTY 프록시 도구
• Claude Code가 사용하는 동기화 출력(sync blocks) 을 가로채고, VT100 기반 렌더링으로 화면의 변경된 부분만 갱신
• 히스토리 버퍼를 유지해 스크롤백이 가능하며, Ctrl+6 키로 ‘룩백 모드’에 진입해 전체 출력 기록을 확인할 수 있음
• 일정 시간 입력이 없을 경우 자동으로 히스토리를 덤프하는 자동 룩백(auto-lookback) 기능 제공
• Linux와 macOS에서 동작하며, 터미널 성능과 가독성을 개선하는 경량 솔루션

개요

• Claude Chill은 Claude Code의 터미널 출력 문제를 해결하기 위해 만들어진 PTY 프록시 프로그램
  • Claude Code는 출력 전체를 동기화 블록으로 감싸 한 번에 렌더링하지만, 이 과정에서 수천 줄의 전체 화면 갱신이 발생
  • 이로 인해 지연, 깜빡임, 스크롤백 손실 등의 문제가 생김
• Claude Chill은 터미널과 Claude Code 사이에 위치해 출력 차이만 반영하고, 히스토리 버퍼를 유지

주요 기능

• Sync 블록 가로채기: Claude Code가 보내는 대규모 동기화 블록을 감지해 처리
• VT 기반 렌더링: VT100 에뮬레이터를 사용해 화면 상태를 추적하고 변경된 부분만 출력
• 히스토리 유지 및 룩백 모드: 출력 내용을 버퍼에 저장해 과거 로그를 확인 가능
  • Ctrl+6 키로 룩백 모드 진입
  • Claude의 출력을 일시 중단하고 전체 히스토리를 터미널에 표시
  • 다시 키를 누르거나 Ctrl+C로 종료 가능
• 자동 룩백(auto-lookback) : 일정 시간(기본 15초) 입력이 없으면 자동으로 히스토리를 덤프
  • -a 0 옵션으로 비활성화 가능
  • 자동 덤프 시 화면이 잠시 깜빡일 수 있음

설치 및 사용

• 설치: cargo install --path crates/claude-chill
• 실행 예시:
  • 기본 실행: claude-chill claude
  • 인자 전달: claude-chill -- claude --verbose
  • 히스토리 크기 지정: claude-chill -H 50000 claude
  • 자동 룩백 비활성화: claude-chill -a 0 claude
• 주요 옵션:
  • -H, --history: 히스토리 최대 줄 수 (기본 100000)
  • -k, --lookback-key: 룩백 모드 전환 키
  • -a, --auto-lookback-timeout: 자동 룩백 대기 시간(ms)

설정 파일

• 위치:
  • Linux: ~/.config/claude-chill.toml
  • macOS: ~/Library/Application Support/claude-chill.toml
• 주요 항목:
  • history_lines: 히스토리 최대 줄 수
  • lookback_key: 룩백 모드 전환 키
  • refresh_rate: 렌더링 FPS
  • auto_lookback_timeout_ms: 자동 룩백 시간

키보드 프로토콜 및 키 설정

• Kitty Keyboard Protocol을 지원하는 터미널(Kitty, Ghostty, WezTerm 등)에서 자동으로 모드 전환
  • Claude Code가 Kitty 모드를 활성화하면 Claude Chill도 자동으로 해당 인코딩을 인식
• 키 형식: [modifier][key]
  • 예: [f12], [ctrl][g], [ctrl][shift][j]
• 기본 키 Ctrl+6은 ASCII 0x1E을 전송하며, 대부분의 터미널과 충돌하지 않음
  • macOS에서는 Ctrl+Shift+6 (Ctrl+^) 로 동일 동작

작동 방식

• Claude Chill은 가상 터미널(PTY) 을 생성하고 Claude Code를 자식 프로세스로 실행
• 입출력 프록시 구조: Terminal ⇄ claude-chill ⇄ Claude Code
• 주요 처리 단계:
  • 입력: Claude로 전달, 룩백 키만 차단
  • 출력: 동기화 블록을 탐지하고 비동기 출력은 그대로 전달
  • VT 에뮬레이션으로 화면 상태 추적
  • 이전 상태와 비교해 차이만 렌더링
  • 히스토리 버퍼 유지 및 룩백 모드 지원
  • SIGWINCH, SIGINT, SIGTERM 등의 신호를 Claude로 전달

주의 사항

• 개인 편의를 위해 개발된 도구로, 광범위한 테스트는 진행되지 않음
• Linux와 macOS에서 동작 확인
• 중요 시스템이나 인프라 환경에서는 사용을 권장하지 않음
• MIT 라이선스