Quick Reference
Claude Code는 별도 설정 없이 대부분의 터미널에서 실행됩니다. 설정은 기능을 켜는 일이 아니라, 줄바꿈·알림·tmux·상태 표시가 현재 터미널에서 잘못 동작할 때만 고칩니다. 특히 상태 표시줄(statusLine)은 화면 장식이 아니라 매 세션에서 셸 명령을 실행하는 설정입니다.
| 증상 | 먼저 쓸 방법 | 터미널별 경계 |
|---|---|---|
| Enter 없이 줄바꿈 | Ctrl+J 또는 \ 뒤 Enter | 모든 터미널에서 설정 없이 동작합니다. |
Shift+Enter가 전송됨 | VS Code·Cursor·Alacritty·Zed에서는 /terminal-setup | gnome-terminal과 JetBrains 터미널에서는 지원되지 않아 다른 줄바꿈 방법을 씁니다. |
| 긴 작업 완료를 놓침 | preferredNotifChannel: "terminal_bell" 또는 Notification hook | VS Code 통합 터미널은 기본 데스크톱 알림을 받지 않을 수 있습니다. |
| 현재 브랜치·문맥 사용량이 안 보임 | /statusline 또는 statusLine 설정 | 스크립트가 자주 실행되므로 빠르고 신뢰할 수 있어야 합니다. |
{
"preferredNotifChannel": "terminal_bell",
"statusLine": {
"type": "command",
"command": "~/.claude/statusline.sh",
"padding": 1
}
}여러 줄 입력과 tmux
Enter는 메시지를 전송합니다. 줄을 나누려면 모든 터미널에서 Ctrl+J를 누르거나, 줄 끝에 \를 입력한 뒤 Enter를 누릅니다. Shift+Enter는 Ghostty, Kitty, iTerm2, WezTerm, Warp, Apple Terminal, Windows Terminal에서는 별도 설정 없이 동작하지만, VS Code·Cursor·Devin Desktop·Alacritty·Zed에서는 /terminal-setup을 한 번 실행해야 합니다.
/terminal-setup은 tmux나 screen 안이 아니라 실제 호스트 터미널에서 실행합니다. VS Code 계열에서는 터미널 키 설정뿐 아니라 텍스트 깨짐을 피하기 위한 GPU 가속 설정도 바꿀 수 있으므로, 이미 의도적으로 설정한 값이 있다면 변경 내용을 확인합니다.
tmux에서는 기본적으로 Shift+Enter 구분과 알림·진행 표시 전달이 깨질 수 있습니다. ~/.tmux.conf에 아래 설정을 넣고 tmux source-file ~/.tmux.conf로 적용합니다.
set -g allow-passthrough on
set -s extended-keys on
set -as terminal-features 'xterm*:extkeys'첫 줄은 Claude Code의 알림과 진행 표시를 바깥 터미널로 전달하고, 나머지 줄은 Shift+Enter를 일반 Enter와 구분하게 합니다.
알림과 테마
Claude Code가 작업을 마치거나 권한을 요청하면 알림 이벤트를 냅니다. Ghostty·Kitty·iTerm2는 기본 데스크톱 알림을 지원하지만, 다른 터미널은 preferredNotifChannel을 "terminal_bell"로 설정하거나 Notification hook을 씁니다. hook은 기본 알림을 대체하지 않고 함께 실행되므로, 실행할 명령의 보안성과 속성을 따로 검토합니다.
theme는 /theme 또는 /config에서 고릅니다. auto는 터미널의 밝고 어두운 배경을 감지하지만, 터미널 애플리케이션 자체의 색상 구성까지 바꾸지는 않습니다. 화면 색이 맞지 않는 문제는 Claude Code theme와 터미널 theme 중 어느 쪽의 문제인지 나눠 확인합니다.
상태 표시줄을 안전하게 쓰는 법
statusLine은 Claude Code가 JSON 세션 데이터를 표준 입력으로 넘기면, 지정한 셸 명령이 표준 출력으로 표시할 문자열을 만드는 방식입니다. /statusline에 "모델 이름과 문맥 사용률을 보여 줘"처럼 요청하면 Claude Code가 ~/.claude/에 스크립트와 설정을 만들 수 있습니다. 수동으로 설정할 때는 사용자 설정 또는 프로젝트 설정에 type: "command"와 실행 명령을 넣습니다.
표시할 수 있는 대표 값은 현재 모델, 작업 디렉터리, Git 상태, 문맥 사용률, 비용입니다. 그러나 상태 표시 명령은 세션 시작·응답·문맥 압축·권한 모드 변경마다 실행됩니다. 느린 git 검색이나 네트워크 호출을 넣으면 표시가 오래된 채로 남거나 다음 실행이 취소될 수 있으므로, 짧은 로컬 명령만 쓰고 값이 없을 때의 기본값도 처리합니다.
| 설정값 | 기본값 | 언제 바꾸는가 | 잘못 두었을 때 |
|---|---|---|---|
type | 없음 | 사용자 스크립트를 실행할 때 "command" | 다른 값이면 명령형 status line으로 동작하지 않습니다. |
command | 없음 | 스크립트 경로 또는 짧은 셸 명령 | 실행 권한·출력·경로가 틀리면 빈 줄이 됩니다. |
padding | 0 | 표시에 좌우 여백이 필요할 때 | 큰 값은 좁은 터미널에서 더 빨리 잘립니다. |
refreshInterval | 이벤트 기반만 실행 | 시간·백그라운드 상태를 주기적으로 표시할 때 | 너무 짧으면 불필요한 셸 실행으로 느려집니다. |
hideVimModeIndicator | false | 스크립트가 Vim 모드를 직접 그릴 때 | true로만 두면 기본 Vim 표식이 사라집니다. |
자주 틀리는 부분
statusLine과 hook은 설정 파일에 적은 셸 명령을 로컬에서 실행합니다. 신뢰하지 않은 저장소의 프로젝트 설정은 검토 없이 승인하지 말고, workspace trust를 수락하지 않았다면 status line이 비어 있는 것이 정상일 수 있습니다.
status line이 비어 있을 때
1. workspace trust를 수락했는지 확인한다.
2. 스크립트가 실행 가능하고 표준 출력에 문자열을 내보내는지 직접 실행해 본다.
3. claude --debug로 첫 실행의 종료 코드와 표준 오류를 확인한다.
4. 값이 null일 수 있으므로 스크립트에 기본값을 둔다.
표시가 느리거나 흔들릴 때
1. 네트워크 호출과 느린 명령을 제거한다.
2. refreshInterval을 지우거나 늘린다.
3. 한 줄의 짧은 일반 텍스트 출력부터 다시 확인한다.참고 링크
2 sources