Statusline reference (한국어)

절감 원장에 기록이 쌓이면 statusline이 두 줄로 출력됩니다. 첫째 줄에는 라우팅 절감액만 표시하고, 둘째 줄에는 진단 칩을 표시합니다.

statusline 읽는 법

절감 원장에 기록이 쌓이면 statusline이 두 줄로 출력됩니다. 첫째 줄에는 라우팅 절감액만 표시하고, 둘째 줄에는 진단 칩을 표시합니다.

🔀 Routing saved $2.09  |  fable→sonnet 1× $0.72 · opus→haiku 1× $0.57
⚠ Ctx 500k+ · 🅷 5/5 · 🤖 Opus 5 · 🧠 Cache hit 98.8% · ⏳ Cache expires 59:46 · ✦ current ▰▰▰▰▰▰▰▱▱▱▱▱ 62% 🔄 21:33 · 📅 weekly ▰▰▰▰▰▱▱▱▱▱▱▱ 38% 🔄 Tue 19:33 · 📦 Ctx 47% of 1M · 💰 Cache saved $1.0K · last 1d

원장이 비어 있으면, 다시 말해 아직 실측된 위임이 없으면 첫째 줄을 그리지 않고 종전처럼 한 줄로 출력합니다. 일부 환경(구버전 macOS Claude Code)에서 첫째 줄만 표시된다면 --single-line 옵션으로 한 줄 레이아웃을 유지하십시오.

세그먼트	의미
`🔀` 첫째 줄	라우팅으로 절감한 누적 금액과 모델 이동 내역입니다. 내역 합계는 누적 금액과 정확히 일치하고, 모델명은 계열만 남깁니다(`opus→haiku`). 근거는 `route-scan savings` 로 전부 확인할 수 있습니다
`📄` 둘째 줄	doc2md 문서 변환이 절감한 누적 금액과 형식별 내역입니다. 라우팅과 문서 변환 중 금액이 큰 쪽이 첫째 줄을 차지합니다
`🤖`	현재 모델
`🔬 high`	세션이 돌아가는 effort 레벨입니다(`/effort`). Claude Code 가 그 레벨에 쓰는 색을 그대로 씁니다. 레벨을 고른 화면과 칩이 같은 색을 보여 주어야 하기 때문입니다. `low` 는 노란색(`warning`), `medium` 은 녹색(`success`), `high` 는 하늘색(`permission`), `xhigh` 와 `ultracode` 는 보라색(`autoAccept` 와 `effortUltra`)이고, `max` 는 무지개 일곱 색을 글자마다 나누어 칠합니다. 이 중 두 가지는 원래 움직이는 색입니다. `xhigh` 는 반짝이고 `max` 는 색이 순환하는데, statusline 은 재실행 간격이 초 단위이고 매번 새 프로세스로 실행되어 애니메이션을 만들 수 없으므로 정지된 형태로 표시합니다. 그래서 `xhigh` 와 `ultracode` 가 같은 색이 되는데, 이는 Claude Code 가 두 레벨을 색이 아니라 반짝임으로 구분하기 때문이며 레벨 이름이 둘을 갈라 줍니다. 색은 Claude Code 의 `theme` 설정을 따르고 색약 대응 테마도 함께 지원하며, 24비트 색을 못 쓰는 터미널에서는 Claude Code 의 ANSI 테마 값으로 떨어집니다. effort 설정이 없는 모델과 2.1.276 이전 버전에서는 칩이 나오지 않습니다. `/effort ultracode` 는 xhigh 에 동적 워크플로 오케스트레이션을 더한 레벨인데 statusline 에는 `xhigh` 로만 도착하므로, 세션 트랜스크립트에서 두 가지 근거를 읽어 `🔬 ultracode` 로 구분해 표시합니다. 하나는 `/effort` 명령이 응답한 즉시 기록되는 그 명령의 출력이고, 다른 하나는 다음 턴이 조립될 때 기록되는 ultracode 알림이며, 둘 중 나중에 기록된 쪽을 따릅니다. 그래서 레벨을 바꾸면 곧바로 반영되고, ultracode 가 이미 켜진 상태로 세션을 시작한 경우에만 첫 턴까지 `xhigh` 로 보입니다
`🅷 5/5`	harness 원칙 점수 (Harness 모드)
`🧠`	분석 구간 동안의 캐시 히트율입니다 (85%+ 녹색)
`⏳`	캐시 TTL 카운트다운입니다. 만료되기 전에 메시지를 보내면 캐시가 유지됩니다. 입력이 없을 때도 초 단위로 줄어드는 표시는 Claude Code v2.1.97 이상에서 동작합니다 (아래 카운트다운이 멈춰 보일 때 참고)
`✦ current` / `📅 weekly`	5시간 / 7일 rate-limit 윈도 사용률 + 리셋 시각
`📦`	컨텍스트 사용률입니다(예: `Ctx 68% of 1M`). 사용률에 따라 녹색·노란색·빨간색으로 표시합니다. 최신 모델은 1M 컨텍스트가 기본이고 별도 요금이 붙지 않지만, 토큰량 자체가 턴당 비용과 5시간·7일 한도를 빠르게 소모시킵니다
`💵 Sep $42`	이번 달 1일 00시(로컬) 이후 지출 추정치입니다. 이 머신의 세션 로그에만 세션별 모델 단가를 적용해 합산합니다. 게이트웨이 예산 칩이 함께 뜨는 환경에서는 표시하지 않습니다. 그 칩은 해당 키로 들어온 모든 호출의 실측 지출을 보여 주므로, 서로 어긋나는 금액이 두 개 나오면 오히려 판단을 방해합니다 (v3.35.0)
`💳 budget`	LiteLLM 게이트웨이 키의 예산 게이지입니다. stdin 에 rate_limits 가 오지 않는 환경에서 키의 `max_budget` 대비 `spend` 를 `💳 budget ▰▰▰▱▱▱▱▱▱▱▱▱ 26% $1.0K/$4.0K` 형태로 보여 주며, 결제 주기가 얼마나 남았는지 함께 표시합니다 (v3.35.0, 아래)
`💰`	분석 구간 동안 프롬프트 캐시가 절약해 준 금액입니다. 첫째 줄의 `🔀` 는 원장에 쌓인 전체 기간 누적액이라 기준이 다른 수치입니다
`(last 1d)`	분석 구간입니다. 이 구간을 기준으로 삼는 두 칩(`🧠`, `💰`)에 구분자 없이 붙여서, 줄 전체의 기준으로 잘못 읽히지 않게 했습니다. `sprag mode 7d` 로 바꿉니다
`v3.24.0`	지금 실행 중인 sprag의 버전입니다. 최신이면 회색으로 줄 끝에 조용히 놓입니다
`⬆ v3.24.0 → 3.25.0`	새 버전이 배포되어 있다는 표시입니다. 조치가 필요한 칩이므로 줄 앞쪽으로 올라옵니다 (업데이트 안내)

문제가 감지되면 경고 칩을 줄 맨 앞에 붙입니다.

🚨 5H ▰▰▰▰▰▰▰▰▰▰▰▱ 94% 🔄 12:36 · 🅷 5/5 · 🤖 Opus 4.8 · 🧠 Cache hit 72.1% · ⚠ Cache miss · 📅 weekly ▰▱▱▱▱▱▱▱▱▱▱▱ 12% 🔄 Sun 14:26 · 📦 Ctx 200k · last 1d

칩의 종류는 다음과 같습니다. 🚨 5H/7D NN%(한도 임박) · ⚠ Ctx 500k+(단일 요청이 실제로 500k를 초과) · ⚠ Cache miss · ⚠ Input spike · ⚠ Output heavy · ⚠ Call surge · ⚠ Rebuild churn · ⚠ 5m TTL. 두 윈도가 동시에 90%를 넘으면 리셋이 더 임박한 쪽을 🚨로 올리고, 나머지 하나는 빨간 세그먼트로 계속 표시합니다 (v2.16.0 이상).

경고 칩이 떴을 때

Claude Code 안에서 /claude-token-saver Skill을 실행하거나, 칩에 적힌 문구를 그대로 말하기만 해도("5H cap 떴어", "cache miss") Skill이 자동으로 활성화되어 원인 코드와 단계별 해결 명령을 보여 줍니다. 한도가 임박한 상황에서는 sprag handoff로 진행 중인 작업을 마크다운 파일에 백업한 뒤 새 세션에서 이어가는 방식을 권장합니다.

⬆ 업데이트 안내

statusline은 대화 상자를 띄울 수 없고, 300밀리초마다 다시 그려지기 때문에 그리는 시점에 네트워크를 쓸 수도 없습니다. 그래서 안내를 두 지점으로 나누었습니다.

statusline은 알리기만 합니다. 최신 버전이면 줄 끝에 v3.24.0을 회색으로 조용히 표시하고, 새 버전이 있으면 ⬆ v3.24.0 → 3.25.0을 줄 앞쪽에 노란색으로 올립니다. 빨간색은 쓰지 않습니다. 무엇도 고장 난 상태가 아니기 때문입니다.
묻는 일은 세션 시작에서 합니다. 새 세션이나 /clear 시점에 SessionStart 훅이 "새 버전이 있으니 사용자에게 업그레이드할지 물어보라"는 한 줄을 모델에게 주입합니다. 모델은 사용자에게 확인한 뒤에만 sprag upgrade를 실행합니다. 묻지 않고 설치하지 않습니다.
무엇이 새로 생겼는지 함께 알립니다. 해당 버전의 릴리스 노트에서 최대 세 줄을 읽어 붙입니다. 그래야 질문이 "숫자가 바뀌었으니 올리겠습니까"가 아니라 "이런 것들이 생겼는데 올리겠습니까"가 됩니다. 노트는 필수가 아니며, 산문으로만 쓰인 릴리스는 항목이 잡히지 않습니다. 그때도 버전 안내는 그대로 나갑니다.
거절은 기억합니다. 사용자가 원치 않으면 sprag update-check --dismiss로 그 버전을 묻지 않도록 설정합니다. 더 새로운 버전이 배포되면 다시 묻습니다. statusline 칩은 그대로 남습니다. 거절한 것은 질문이지, 새 버전이 있다는 사실이 아니기 때문입니다.

버전 조회는 24시간에 한 번, 분리된 백그라운드 프로세스가 수행하고 결과만 파일에 남깁니다(update-check.json). 이 방식은 npm의 update-notifier가 쓰는 것과 같습니다. 그 조회에서 새 버전을 발견하면 릴리스 노트도 함께 읽습니다. npm 레지스트리는 변경 내역을 제공하지 않기 때문입니다. 이 요청은 인증이 필요 없고(시간당 60회 한도이며 여기서는 하루 한 번 씁니다), 실패하면 노트만 빠지고 안내 자체는 나갑니다. 네트워크가 끊겨 있어도 실패 시각을 기록해 두므로 매 렌더마다 재시도하지 않습니다. 확인 자체를 끄려면 환경 변수 CTS_NO_UPDATE_CHECK=1 또는 NO_UPDATE_NOTIFIER를 설정하십시오.

토큰 급증 원인 코드

코드	의미
`LARGE_INPUT_PER_REQUEST`	단일 요청의 입력이 200k를 초과했습니다. 턴마다 다시 과금되고 한도 소모가 급격히 늘어납니다
`LOW_HIT_RATE`	캐시 히트율 50% 미만
`BUCKET_5M_DOMINANT`	캐시 쓰기의 70%+가 5분 버킷 (Pro 플랜/Max 다운그레이드)
`HIGH_OUTPUT_RATIO`	출력/입력 비율 0.15 초과 (출력 단가는 입력의 5배)
`HIGH_REQUEST_COUNT`	요청 수가 중앙값의 3배+ (도구 호출 루프 의심)
`FREQUENT_CACHE_REBUILD`	캐시 재작성이 읽기보다 많음

각 코드마다 OS별 해결 명령이 함께 출력됩니다.

라벨 모드

칩은 세 가지 스타일로 나옵니다. 기본값은 이모지이며, 나머지 두 가지는 이모지를 제대로 그리지 못하는 터미널을 위해 존재합니다.

모드	표시 형태	선택 방법
`icon`	`🧠 Cache hit 98.8% · 📦 Ctx 47% of 1M · 🔬 high`	기본값, 또는 `sprag mode icon`
`narrow`	`◉ Cache hit 98.8% · ◧ Ctx 47% of 1M · ▲ high`	JetBrains IDE 에서 자동 적용, 또는 `sprag mode narrow` / `--narrow`
`text`	`Cache hit 98.8% · Ctx 47% of 1M · Effort high`	`sprag mode text` / `--text`

JetBrains IDE 에서 좁은 글리프를 쓰는 이유

JetBrains IDE 내장 터미널(IntelliJ, PyCharm, WebStorm, DataGrip 처럼 TERMINAL_EMULATOR=JetBrains-JediTerm 을 설정하는 환경)에서는 이모지 세트가 깨집니다. 증상은 statusline 이 숫자를 잘못 계산한 것처럼 보입니다.

⏳ Cache expires 4:545      (4:54 로 나와야 합니다)
📦 Ctx 330% of 1M           (33% 로 나와야 합니다)
💳 budget $1.0K/$4.:0K      (＄4.0K 로 나와야 합니다)

계산이 틀린 것은 아닙니다. 카운트다운 포매터는 콜론이 없는 값을 만들지 못하고 퍼센트는 0에서 100 사이로 잘리므로, 위와 같은 문자열은 애초에 생성될 수 없습니다. 화면에 보이는 것은 이전 프레임에서 남은 문자입니다.

원인은 폰트가 해당 문자를 가지고 있지 않다는 점입니다. IDE 기본 폰트인 JetBrains Mono 에는 이모지 글리프가 없어서 터미널이 대체 폰트로 그리는데, 그 폰트의 글자 폭이 셀 격자와 맞지 않습니다. 고정된 텍스트는 그래도 버티지만, 매초 값이 바뀌는 칩은 일부만 다시 그려지기 때문에 어긋난 만큼이 화면에 잔여물로 남습니다. 마우스로 그 줄을 드래그하면 전체가 다시 그려져 정상으로 보이는데, 버퍼는 처음부터 옳았고 화면에 그리는 단계만 어긋났다는 증거입니다.

narrow 세트의 모든 글리프는 JetBrains Mono 가 실제로 가지고 있는 문자입니다. 원인을 찾은 경로도 여기였습니다. statusline 에서 한 번도 깨지지 않은 부분이 게이지뿐이었고, 게이지가 쓰는 블록 문자만 폰트에 들어 있었습니다.

게이지도 같은 규칙을 따릅니다. 눈금은 기본적으로 ▰▱ 이지만 JetBrains Mono 에는 두 문자가 모두 없어서, narrow 모드에서는 폰트가 가지고 있는 ■□ 로 같은 바를 그립니다. 두 경우 모두 눈금 열두 칸으로 읽히고, 눈금 하나의 모양만 다릅니다.

다른 터미널에서도 줄이 깨진다면

이모지 글리프가 없는 폰트를 쓰는 터미널이라면 어디서든 같은 잔여물이 보일 수 있습니다. 자동으로 감지하는 것은 JetBrains IDE 뿐인데, 프로그램이 터미널에게 어떤 폰트를 쓰는지 물어볼 방법이 없기 때문입니다. 그런 경우에는 직접 전환하십시오.

sprag mode narrow    # 이모지 없이 칩마다 글리프를 남깁니다
sprag mode text      # 글리프를 모두 뺍니다

JetBrains IDE 에서 깨짐을 감수하고 이모지를 그대로 쓰려면 다음과 같이 합니다.

sprag mode icon-force      # 설정에 저장합니다
SPRAG_ICON=force           # 한 번만 적용합니다(예: 스크린샷을 찍는 동안)

sprag mode 는 실제로 무엇이 렌더되는지와 어느 규칙이 그렇게 정했는지 알려 줍니다.

labels:  icon
renders: narrow (IntelliJ: emoji garble in the IDE font. `sprag mode icon-force` keeps them anyway)