작성자 Claude Code statusLine 설정 및 VPS 호스트 표시 방법
Claude Code의 statusLine 기능을 사용하여 VPS 환경에서 호스트명, 디렉터리, Git 브랜치를 프롬프트 아래에 표시하는 방법을 설명합니다. 잘못된 서버에서 명령을 실행하는 실수를 방지하기 위한 settings.json 설정법과 스크립트 작성 가이드를 확인하십시오.
Claude Code 상태 표시줄의 의미
Claude Code 상태 표시줄은 프롬프트 아래에 위치하며 사용자가 작성한 스크립트의 출력 결과를 보여주는 행입니다. settings.json 파일에 statusLine 블록을 추가하고 특정 명령어를 지정하면 됩니다. Claude Code는 해당 명령어를 실행하고 세션 상태를 JSON 형식으로 표준 입력(stdin)에 전달하며, 명령어가 표준 출력(stdout)에 기록하는 내용을 그대로 표시합니다.
이것이 계약의 전부입니다. 사용자의 스크립트는 표준 입력에서 JSON을 읽고 표준 출력에 텍스트를 출력합니다. 이 과정은 사용자의 로컬 머신에서 실행되며 출력된 내용은 모델로 전송되지 않으므로 토큰 비용이 발생하지 않습니다.
하나의 프로젝트만 다루는 노트북 환경에서는 단순한 장식에 불과할 수 있습니다. 하지만 3대의 서버를 운영할 때는 안전장치 역할을 합니다. 모든 Claude Code 세션은 터미널에서 동일하게 보이기 때문에, 레이블이 없는 4개의 SSH 창을 띄워두면 마이그레이션 작업 중 잘못된 서버에 명령을 내리는 실수가 발생할 수 있습니다. 호스트 이름으로 시작하는 상태 표시줄을 설정하면 이러한 유형의 실수를 방지할 수 있습니다.
settings.json에서 statusLine 설정이 위치하는 곳
이 설정은 해당 머신의 모든 프로젝트에 적용되는 ~/.claude/settings.json의 사용자 설정에 추가합니다. 저장소 내부의 .claude/settings.json에 있는 프로젝트 설정도 가능하며, 해당 디렉터리에서는 이 설정이 우선합니다.
{
"statusLine": {
"type": "command",
"command": "~/.claude/statusline.sh"
}
}type는 항상 "command"입니다. command 값은 셸을 통해 실행되므로 스크립트 경로가 될 수도 있고 일반 명령어가 될 수도 있습니다. 스크립트를 작성하기 전에 연결이 정상적으로 작동하는지 확인하십시오.
{
"statusLine": {
"type": "command",
"command": "hostname -s"
}
}Claude Code를 시작하고 메시지를 하나 보냅니다. 프롬프트 아래의 막대에 서버의 짧은 호스트 이름이 표시됩니다. 만약 비어 있다면, 문제는 스크립트가 아니라 설정이나 신뢰 대화 상자에 있는 것입니다. 아래의 "statusline이 비어 있는 이유"를 읽어 보십시오.
2026년 8월 기준으로 세 가지 선택적 키가 존재합니다. padding은 가로 간격을 문자 단위로 추가하며 기본값은 0입니다. refreshInterval은 일반적인 트리거 외에 N초마다 명령을 다시 실행하며, 최소값은 1입니다. 이 설정은 라인에 시계나 세션이 유휴 상태일 때 변경되는 정보가 표시될 때만 사용하십시오. hideVimModeIndicator는 사용자의 스크립트가 이미 vim 모드를 렌더링하고 있을 때 내장된 -- INSERT -- 텍스트를 숨깁니다.
statusline 스크립트는 어떤 데이터를 수신합니까?
이 페이지를 포함하여 어디에서 읽은 필드 목록도 그대로 신뢰하지 마십시오. 사용 중인 버전이 실제로 전송하는 객체를 직접 캡처해야 합니다. 표준 입력(stdin)을 파일로 저장하는 임시 스크립트를 작성하십시오.
cat > ~/.claude/statusline-capture.sh <<'EOF'
#!/bin/bash
cat > /tmp/statusline-input.json
echo "captured"
EOF
chmod +x ~/.claude/statusline-capture.shstatusLine.command를 해당 파일로 지정하고, 세션을 시작한 뒤 메시지를 하나 전송하십시오. 바(bar)는 captured를 읽습니다. 이제 도착한 내용을 확인하십시오.
jq . /tmp/statusline-input.json빌드에 필요한 정확한 형태를 파악할 수 있으며, 업데이트로 인해 무언가 변경될 때마다 이 과정을 반복할 수 있습니다.
2026년 8월에 문서화된 안정적인 부분들은 평면적인 키가 아니라 중첩된 객체입니다. model은 id과 display_name을 포함합니다. workspace는 current_dir과 project_dir을 포함합니다. current_dir는 현재 세션 위치이며, project_dir은 세션이 시작된 위치입니다. 세션 도중 작업 디렉터리가 변경되면 두 값은 서로 달라집니다. 최상위 cwd는 workspace.current_dir와 동일한 값을 가집니다. context_window은 토큰 개수와 미리 계산된 used_percentage을 포함합니다. cost은 total_cost_usd와 지속 시간 카운터를 포함합니다. session_id은 세션 수명 동안 안정적이며 세션마다 고유하므로, 나중에 캐싱할 때 중요하게 작용합니다.
스키마 변경에도 스크립트를 유지하기 위한 세 가지 규칙이 있습니다.
일부 키는 null이 아니라 아예 존재하지 않습니다. vim, agent, pr, worktree, effort는 해당 기능이 활성화된 경우에만 나타납니다. vim 모드가 꺼진 상태에서 jq -r을 사용하여 .vim.mode을 읽으면 리터럴 문자열 null이 출력되고, 바에는 사용자에게 null가 표시됩니다. 모든 선택자에 // empty을 추가하여 키가 누락되었을 때 아무것도 출력되지 않도록 하십시오.
일부 값은 초기에 null입니다. context_window.used_percentage과 context_window.current_usage는 첫 번째 API 응답 전까지 null이며, current_usage은 /compact 이후 다음 호출이 값을 다시 채울 때까지 null로 돌아갑니다. 따라서 바에 표시되는 컨텍스트 백분율에는 // 0가 필요합니다. 그렇지 않으면 모든 세션의 첫 몇 초 동안 null으로 표시됩니다. 해당 숫자를 바에 넣기 전에 컨텍스트 윈도우가 실제로 어떻게 채워지는지 이해하는 것이 도움이 됩니다.
git 브랜치는 JSON에 포함되어 있지 않습니다. 이를 보고하는 필드는 없습니다. 바에 표시되는 모든 브랜치 정보는 스크립트가 직접 git을 실행하여 가져온 것입니다.
중단되지 않고 성능이 저하되는 상태 표시줄 스크립트
이 버전은 복사하여 바로 사용할 수 있습니다. 호스트 이름, 작업 디렉터리, git 브랜치, 모델 이름을 출력합니다. 모든 필드에 대체 값이 설정되어 있어, 빈 JSON 객체라도 사용 가능한 줄을 생성합니다.
#!/bin/bash
# ~/.claude/statusline.sh
input=$(cat)
# Read one field. Prints nothing when the key is missing or null.
field() { printf '%s' "$input" | jq -r "$1 // empty" 2>/dev/null; }
HOST=$(hostname -s 2>/dev/null)
[ -z "$HOST" ] && HOST="host"
DIR=$(field '.workspace.current_dir')
[ -z "$DIR" ] && DIR=$(field '.cwd')
[ -z "$DIR" ] && DIR="$PWD"
MODEL=$(field '.model.display_name')
[ -z "$MODEL" ] && MODEL="claude"
SHORT="$DIR"
if [ -n "$HOME" ]; then
case "$DIR" in
"$HOME") SHORT="~" ;;
"$HOME"/*) SHORT="~/${DIR#"$HOME"/}" ;;
esac
fi
BRANCH=""
if git -C "$DIR" rev-parse --git-dir >/dev/null 2>&1; then
BRANCH=$(git -C "$DIR" branch --show-current 2>/dev/null)
[ -z "$BRANCH" ] && BRANCH="detached"
fi
CYAN=$'\033[36m'
YELLOW=$'\033[33m'
DIM=$'\033[2m'
RESET=$'\033[0m'
LINE="${CYAN}${HOST}${RESET} ${SHORT}"
[ -n "$BRANCH" ] && LINE="${LINE} ${YELLOW}${BRANCH}${RESET}"
LINE="${LINE} ${DIM}${MODEL}${RESET}"
printf '%s\n' "$LINE"모든 읽기 작업은 field을 거치며, 여기에 // empty가 추가됩니다. 따라서 키 이름이 변경되거나 삭제되어도 빈 문자열이 생성되며, 다음 줄에서 기본값을 제공합니다. 디렉터리는 workspace.current_dir에서 cwd을 거쳐 $PWD로 대체됩니다. 브랜치는 단순한 git가 아닌 git -C "$DIR"에서 가져오므로, 브랜치는 항상 바(bar)에 표시되는 디렉터리와 일치합니다.
파일을 저장한 뒤 실행 권한을 부여합니다.
chmod +x ~/.claude/statusline.sh실행 비트는 필수입니다. Claude Code는 셸을 통해 명령을 실행하므로, +x가 없는 스크립트는 Permission denied 오류와 함께 실패합니다. 이 경우 표준 출력(stdout)이 생성되지 않아 상태 표시줄이 아무런 오류 메시지 없이 빈 상태로 유지됩니다.
jq은 명령줄에서 JSON을 파싱하는 도구이며, 새로 설치한 Ubuntu 서버에는 기본으로 포함되어 있지 않습니다.
sudo apt update && sudo apt install -y jq그런 다음 위에서 언급한 첫 번째 settings.json 블록을 사용하여 설정을 해당 스크립트로 지정합니다.
스크립트를 신뢰하기 전에 테스트하십시오
스크립트를 수동으로 두 번 실행하십시오. 먼저 일반 세션 객체를 사용합니다.
echo '{"model":{"display_name":"Opus"},"workspace":{"current_dir":"/srv/api"},"session_id":"t1"}' | ~/.claude/statusline.sh호스트 이름이 출력된 다음 /srv/api, 이어서 Opus이 출력됩니다. 사용자의 컴퓨터에 있는 /srv/api은 아마도 git 저장소가 아닐 것이므로 브랜치는 나타나지 않습니다.
다음은 사람들이 흔히 건너뛰는 성능 저하 테스트입니다.
echo '{}' | ~/.claude/statusline.sh빈 객체는 스키마 변경 시 발생할 수 있는 최악의 상황입니다. 이 경우에도 호스트 이름, $PWD에서 가져온 현재 디렉터리, 그리고 모델 이름이 들어갈 자리에 claude이라는 단어가 출력됩니다. 아무것도 충돌하지 않으며 null도 출력되지 않습니다. 이 테스트를 통과한 스크립트는 필드 이름이 변경되어도 정상적으로 작동합니다. 스크립트 입장에서는 필드 이름이 변경된 것이나 필드가 누락된 것이나 동일한 이벤트로 처리되기 때문입니다.
확인해야 할 사항
상태 표시줄은 내장된 하둡 배지 위쪽의 별도 행에 렌더링되며 기존 배지를 대체하지 않습니다. 정상적으로 설정되었다면 한 행에 다음 정보가 표시됩니다. 시안색의 짧은 호스트 이름, ~로 축약된 홈 디렉터리를 포함한 현재 작업 디렉터리, 디렉터리가 git 저장소일 경우 노란색으로 표시되는 브랜치 이름, 그리고 흐리게 표시되는 모델 이름입니다. 이 네 가지 요소가 색상별로 구분되어 web-01 ~/api main Opus과 유사한 형태로 나타나야 합니다.
이 행은 세션 시작(재개 포함), 새로운 어시스턴트 메시지 수신, /compact 종료 후, 권한 모드 변경, vim 모드 전환, 그리고 설정한 경우 refreshInterval 틱이 발생할 때마다 스크립트를 다시 실행합니다. 업데이트는 300 ms 단위로 디바운스(debounced) 처리되므로, 짧은 시간에 여러 변경 사항이 발생해도 스크립트는 한 번만 실행됩니다. 자동 완성, 도움말 메뉴, 권한 프롬프트가 표시되는 동안에는 표시줄이 숨겨졌다가 다시 나타납니다.
호스트 이름을 가장 먼저 표시해야 하는 이유
여러 서버에서 에이전트를 실행할 때, 현재 위치를 알려주는 유일한 수단은 터미널뿐이지만 터미널은 종종 잘못된 정보를 보여줍니다. tmux 창 내부에서 두 번째 ssh 연결을 열면 창 제목이 이전 이름을 그대로 유지하는 경우가 많은데, 이는 셸이 이동 사실을 인지하지 못하고 제목을 설정하기 때문입니다. VPS의 분리된 tmux 세션에서 Claude Code를 실행해 둔 채 하루 뒤에 다시 접속하면, 화면상으로는 빌드 서버와 운영 서버를 구분할 방법이 없습니다.
상태 표시줄은 다릅니다. 이는 Claude Code가 세션별로, 해당 세션이 보유한 데이터를 기반으로 직접 렌더링하기 때문입니다. 잘못된 창에서 상속되거나 갱신되지 않은 셸 프롬프트에 의해 정보가 정체될 일이 없습니다. 상태 표시줄에 나타나는 정보는 에이전트가 파일을 작성 중인 서버를 정확히 가리킵니다.
각 서버에 고유한 색상을 지정하여 읽기 전에 먼저 인식할 수 있도록 하십시오. LINE= 할당문 위에 다음 두 줄을 추가합니다.
CODE=$(printf '%s' "$HOST" | cksum | cut -d' ' -f1)
HOST_COLOR=$(printf '\033[%dm' "$((31 + CODE % 6))")그런 다음 ${CYAN} 대신 ${HOST_COLOR}을 사용하십시오. cksum은 호스트 이름의 체크섬을 출력하므로, 특정 이름은 항상 31에서 36 사이(빨간색에서 청록색)의 동일한 색상으로 매핑됩니다. 이 스크립트를 모든 서버에 복사하면 각 서버가 스스로를 식별하게 됩니다.
디렉터리 경로 역시 같은 이유로 표시할 가치가 있습니다. /srv/api와 /srv/api-staging는 ssh 명령에서 키 입력 한 번 차이지만, 그 결과는 전체 장애로 이어질 수 있습니다. 모델과 브랜치 정보 또한 화면 공간을 할애할 가치가 있습니다. 모델은 어떤 세션을 재개했는지 알려주며, 브랜치는 에이전트가 main에 커밋하려는지 여부를 알려줍니다.
화면이 작을수록 의존할 창 제목이 없으므로 이러한 정보는 더욱 중요해집니다. 이러한 환경을 사용 중이라면 휴대폰으로 Claude Code 제어하기를 참조하십시오.
스크립트 속도 유지하기
스크립트는 모든 어시스턴트 메시지마다 실행되며, 새로운 업데이트가 도착하면 Claude Code는 실행 중인 작업을 취소합니다. 따라서 스크립트가 느리면 오래된 텍스트가 표시되거나 아예 텍스트가 나타나지 않을 수 있습니다.
각 jq 호출은 수 밀리초가 소요됩니다. git는 속도가 느려지는 부분입니다. 캐시가 없는 대규모 저장소에서 git status을 실행하면 수백 밀리초가 걸립니다. 위 스크립트는 의도적으로 git status을 피하고 git branch --show-current를 호출합니다. 이 명령은 .git/HEAD을 읽고 즉시 반환합니다.
더 무거운 작업을 추가해야 한다면 파일에 캐시하고 몇 초마다 갱신하십시오. 세션별로 파일 키를 지정하십시오.
CACHE="/tmp/statusline-$(field '.session_id')"$$ 대신 session_id를 사용하십시오. $$은 스크립트의 프로세스 ID이며 호출할 때마다 달라지므로, 이를 키로 사용한 캐시는 적중하지 않으며 매번 전체 비용을 지불하게 됩니다. session_id은 전체 세션 동안 안정적으로 유지되며 세션마다 값이 다르므로, 서로 다른 저장소에서 실행 중인 두 개의 Claude Code 세션이 서로의 캐시된 브랜치 이름을 읽을 수 없습니다.
알아두어야 할 한 가지 제한 사항이 더 있습니다. tput cols은 상태 표시줄 스크립트 내부에서 작동하지 않습니다. Claude Code는 스크립트를 터미널에 연결하는 대신 출력을 캡처하므로, 너비 감지 기능이 측정할 대상이 없습니다. Claude Code는 v2.1.153 이상 버전에서 명령을 실행하기 전에 COLUMNS 및 LINES 환경 변수를 설정합니다. 따라서 출력량을 결정해야 할 때는 $COLUMNS을 읽으십시오.
상태 표시줄이 비어 있는 이유
아무것도 나타나지 않습니다. ls -l ~/.claude/statusline.sh로 실행 권한(execute bit)을 확인한 다음, 위에서 언급한 모의 입력을 사용하여 스크립트를 직접 실행해 보십시오. 셸에서는 한 줄이 출력되지만 Claude Code에서는 나타나지 않는다면, 세션의 첫 번째 상태 표시줄 실행 시 종료 코드와 stderr를 기록하는 claude --debug으로 시작하십시오.
디버그 로그에 Status line command skipped: workspace trust not accepted가 표시됩니다. 상태 표시줄은 셸 명령을 실행하므로, 후크(hooks)와 동일한 작업 공간 신뢰(workspace trust) 제한을 받습니다. 해당 디렉터리에 대한 신뢰 대화 상자를 수락하기 전까지는 명령이 실행되지 않습니다. 이는 새로운 클론이 생성될 때마다 Claude Code가 처음 보는 디렉터리가 되는 VPS 환경에서 흔히 발생합니다. 해당 디렉터리에서 Claude Code를 재시작하고 대화 상자를 수락하십시오.
모든 것이 비어 있고 disableAllHooks가 설정되어 있습니다. settings.json의 "disableAllHooks": true은 동일한 셸 실행 제한을 받으므로 상태 표시줄도 비활성화합니다. 이를 제거하거나 false로 설정하십시오.
행에 null이 출력됩니다. jq 선택자가 누락되었거나 null인 키에 도달했으며, jq -r는 null을 null이라는 네 글자로 출력합니다. 텍스트에는 // empty을, 숫자에는 // 0를 추가하십시오.
스크립트를 편집한 직후 행이 비어 버립니다. 0이 아닌 값으로 종료되거나 아무것도 출력하지 않는 명령은 행을 비우게 만듭니다. 흔한 원인은 [ -n "$BRANCH" ] && LINE="..."과 같은 마지막 줄인데, 이는 브랜치가 비어 있을 때 1을 반환하며 전체 스크립트의 종료 코드까지 1로 만듭니다. printf를 마지막에 두거나 exit 0를 추가하십시오.
\e]8;;과 같은 이스케이프 코드가 막대 위에 그대로 텍스트로 표시됩니다. echo -e 대신 printf '%b'을 사용하십시오. 클릭 가능한 OSC 8 링크를 사용하려면 해당 기능을 지원하는 터미널이 필요하며, tmux나 SSH는 해당 시퀀스를 제거할 수 있으므로 원격 환경에서는 일반 색상을 사용하는 것이 더 안전합니다.
행의 오른쪽이 잘립니다. 시스템 알림과 상세 모드(verbose-mode) 토큰 카운터가 오른쪽 영역을 공유하므로, 터미널 폭이 좁으면 겹치는 부분이 잘립니다. 출력을 짧게 유지하십시오. 막대 위의 숫자가 아닌 실제 사용량 집계를 확인하려면 Claude Code의 토큰 계산 방식을 참조하십시오.
FAQ
Claude Code statusline 설정은 어디에 위치합니까?
settings.json 내부에 있으며, type을(를) "command"(으)로, command을(를) 스크립트 경로 또는 셸 명령어로 설정한 statusLine 블록 형태입니다. 사용자 설정은 ~/.claude/settings.json에 위치하며 해당 머신의 모든 프로젝트에 적용됩니다. 프로젝트 설정은 저장소 내부의 .claude/settings.json에 위치하며 해당 디렉터리에 우선 적용됩니다. 설정은 자동으로 다시 로드되지만, 변경 사항은 다음 메시지 전송과 같은 업데이트 트리거가 발생해야 화면에 반영됩니다.
Claude Code statusline이 비어 있는 이유는 무엇입니까?
대부분 다음 네 가지 원인 중 하나입니다. 첫째, 스크립트에 실행 권한이 없어 셸이 Permission denied을(를) 반환하고 표준 출력(stdout)으로 아무것도 전달되지 않는 경우입니다. 둘째, 작업 공간 신뢰 대화 상자를 수락하지 않아 claude --debug이(가) Status line command skipped: workspace trust not accepted을(를) 기록하는 경우입니다. 셋째, disableAllHooks가 true으로 설정되어 동일한 제약 조건에 의해 statusline이 비활성화된 경우입니다. 넷째, 스크립트가 0이 아닌 종료 코드를 반환하여 행이 비어 보이는 경우입니다. 먼저 수동으로 echo '{}' | ~/.claude/statusline.sh을(를) 실행하여 출력이 정상적으로 나오는지 확인하십시오.
statusline JSON에 git 브랜치 정보가 포함됩니까?
아니요. JSON에는 모델, 작업 공간 디렉터리, 컨텍스트 윈도우 수치, 비용과 같은 세션 상태 정보만 포함됩니다. git 관련 정보는 포함되지 않습니다. 상태 표시줄에 브랜치가 나타나게 하려면 사용자의 스크립트에서 git branch --show-current를 호출해야 합니다. JSON에서 디렉터리 정보를 가져와 git -C "$DIR"에 전달하면, 상태 표시줄이 항상 현재 디렉터리에 맞는 브랜치를 표시하게 할 수 있습니다.
statusline이 토큰 비용을 발생시키거나 세션 속도를 저하시킵니까?
스크립트가 로컬에서 실행되고 그 결과가 모델로 전송되지 않으므로 토큰 비용은 발생하지 않습니다. 속도는 사용자가 관리해야 합니다. 명령어는 어시스턴트 메시지가 발생할 때마다 300 ms 디바운스(debounce)를 거쳐 실행되며, 새로운 업데이트가 도착하면 Claude Code가 기존 실행을 취소합니다. 따라서 스크립트 실행에 1초 이상 소요되면 이전 텍스트가 표시될 수 있습니다. 대규모 저장소에서 git status 사용을 피하고, 느린 작업은 session_id를 키로 사용하여 파일에 캐싱하십시오.
서버마다 다른 statusline을 표시하려면 어떻게 합니까?
하나의 스크립트를 유지하면서 머신 정보를 읽도록 구성하십시오. 위 스크립트는 hostname -s을(를) 대체값으로 사용하여 $HOSTNAME을(를) 출력하므로, 동일한 파일을 모든 서버에 복사해도 각 서버를 올바르게 식별할 수 있습니다. 또한 체크섬 색상 트릭을 사용하면 호스트 이름별로 고유한 색상을 지정할 수 있습니다. 특정 서버에서 다른 레이아웃이 필요하다면, 해당 서버의 저장소 프로젝트 설정에 statusLine 블록을 추가하십시오. 프로젝트 설정은 해당 디렉터리의 사용자 설정을 덮어씁니다.