상태줄 커스터마이즈하기

상태줄 커스터마이즈하기 (Custom status line)

Claude Code는 입력 프롬프트 아래에 기본 상태줄을 표시하는데, statusLine 설정을 command 타입으로 지정하면 나만의 명령을 실행해 그 결과를 상태줄로 쓸 수 있습니다. 표준 입력으로 현재 상태(모델·비용·컨텍스트 사용량·git 정보·실행 중 훅 등)가 담긴 JSON을 받아, 한 줄로 원하는 내용을 그립니다. 출력 문자가 색상은 ANSI 코드로 표현합니다.

출처: 공식문서

본문

상태줄은 무엇인가

상태줄은 로그인·-p(print 모드)·headless 세션을 제외한 모든 인터랙티브 세션의 입력 프롬프트 아래에 표시되는, 화면 하단의 한 줄입니다. 커스텀 상태줄은 원하는 정보를 어떤 모양으로든 보여줄 수 있습니다. 기본값은 컨텍스트 사용량과 비용 같은 정보를 표시합니다.

설정

상태줄은 statusLine 설정으로 제어합니다. ~/.claude/settings.json(모든 프로젝트) 또는 .claude/settings.local.json(한 프로젝트)에 둡니다.

{
  "statusLine": {
    "type": "command",
    "command": "jq -r '\"[\\(.model.display_name)] \\(.context_window.used_percentage // 0)% context\"'",
    "padding": 2
  }
}
  • type: 현재 유일한 값은 "command". 기본(type 없음)은 Claude가 최적화한 기본 상태줄.
  • command: 셸 명령. 상태줄을 표시할 때마다 실행되어 표준 입력으로 상태 JSON을 받고, 표준 출력의 한 줄을 상태줄로 그립니다. 여러 줄이면 첫 줄을, 빈 출력이면 빈 줄을 표시합니다. 명령이 실패하면 오류를 말해 주고 기본 상태줄을 보여줍니다.
  • padding: 출력 앞에 붙일 공백 칸 수.

상태 JSON (페이로드)

명령은 표준 입력으로 아래 구조의 JSON을 받습니다.

{
  "session_id": "...",
  "transcript_path": "/path/to/history.jsonl",
  "cwd": "/path/to/cwd",
  "model": {
    "id": "claude-sonnet-5",
    "display_name": "Sonnet 5"
  },
  "workspace": {
    "current_dir": "/path/to/cwd",
    "project_dir": "/path/to/cwd"
  },
  "version": "2.1.150",
  "output_style": "default",
  "cost": {
    "total_cost_usd": 0.0942,
    "total_duration_ms": 10000,
    "total_api_duration_ms": 4000,
    "total_context_tokens": 30000
  },
  "context_window": {
    "used_percentage": 42,
    "total_percentage": 1,
    "used_tokens": 25104,
    "total_tokens": 60000,
    "token_usage": {
      "cache_read_input_tokens": 12552,
      "cache_creation_input_tokens": 156,
      "input_tokens": 156,
      "output_tokens": 960
    }
  },
  "hooks": {
    "running": 1,
    "blocking": 0
  },
  "git": {
    "branch": "main",
    "dirty": false,
    "detached": false,
    "ahead": 3,
    "behind": 2,
    "remote": "origin"
  }
}

필드 요약: model.id(모델 ID)·model.display_name(표시명), workspace.current_dir·workspace.project_dir(작업·프로젝트 디렉토리), cost.total_cost_usd(달러 비용)·total_duration_ms·total_api_duration_ms·total_context_tokens, context_window.used_percentage(0~100)·total_percentage·used_tokens·total_tokens·token_usage(캐시/입력/출력 토큰), hooks.running·hooks.blocking(실행 중·차단 중 훅 수), git.branch·git.dirty·git.detached·git.ahead·git.behind·git.remote.

색상 제어

출력의 문자가 ANSI 색상 코드를 지원합니다. 간단한 jq 예:

jq -r '"\[\u001b[32m\(.model.display_name)\u001b[0m] \(.context_window.used_percentage // 0)%"'

\u001b로 이스케이프 시퀀스를 만들어 \u001b[32m(초록 시작) \u001b[0m(리셋)처럼 표현합니다.

예시

custom script를 statusline에 넣는 예:

{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/scripts/statusline.sh"
  }
}

statusline.sh (bash):

#!/usr/bin/env bash
# read stdin JSON, print one line
model=$(jq -r '.model.display_name')
pct=$(jq -r '.context_window.used_percentage // 0')
echo "[$model] $pct% context"

pokemon(ASCII 아트) 같은 예: ~/.claude/scripts/pokedex.sh가 stdin으로 pokemon을 실행하고 jq '{ name: .jobs[0].name }' 로로 트림해 표시. git 정보 표시: jq -r '"\(.git.branch // "n/a") (+\(.git.ahead)//-\(.git.behind)"'. Windows git-bash에서는 MSYS_NO_PATHCONV=1을 붙이는 등 패스 변환 주의. go run·gh 등 원하는 어떤 언어/도구로도 가능합니다.

더 알아보기