ccstatusline은 Claude Code 아래에 필요한 정보를 모아 보여 주는 외부 도구입니다. 모델·작업 폴더·Git 브랜치·컨텍스트 사용량 등을 원하는 순서로 배치합니다. 기본 승인 모드 표시는 별도이며, 표시줄을 바꾼다고 승인 방식이 바뀌지는 않습니다.
설치하면 어떻게 보입니까?
설명을 위해 만든 화면 예시이며 실제 캡처가 아닙니다. 항목·색·순서·줄 수는 사용자가 설정 화면에서 고릅니다.
입력 상자 바로 아래가 ccstatusline이고, 그 아래 흐린 글씨는 Claude Code 자체 표시입니다. 모델 이름·폴더·브랜치·Context만 표시하는 도구가 아닙니다. 사용 시간·구독 한도 사용률·비용 등 필요한 정보를 더할 수 있습니다. 아래 모델 이름·경로·수치·시간·금액은 모두 예시값입니다.
① 설치 직후 기본 구성 — 한 줄, 4개 항목
제작자 기본값은 모델 · 컨텍스트 길이 · Git 브랜치 · Git 변경량입니다. 컨텍스트는 모델이 지금 대화에서 참고하는 문맥이며, 길이는 토큰이라는 글 처리 단위로 표시합니다.
auto mode on입니다.Ctx: 48.2k는 문맥 길이 약 48,200토큰, ⎇ main은 현재 Git 브랜치, (+42,-10)은 삽입 42줄·삭제 10줄이라는 뜻입니다. Git은 파일 변경 이력을 관리하는 도구이며, 브랜치는 작업 흐름을 나눈 갈래입니다.
② 항목을 더한 3줄 구성 — 사용자가 고른 경우
모델의 사고 노력 수준인 Thinking: high, 현재 폴더, 대화의 문맥 사용률, 세션 시간, 비용과 구독 한도를 더한 예시입니다. 세션은 한 번 이어서 작업하는 대화 단위이며, 이 구성은 설치 직후 기본값이 아닙니다.
auto mode on입니다.좁은 화면에서는 터미널 예시 안을 좌우로 스크롤해 나머지 항목을 확인합니다. 실제 상태줄은 터미널 폭에서 5칸을 뺀 공간을 사용하며, 넘치는 내용은 잘립니다. 좁은 터미널에서는 Claude Code 알림과 같은 줄에 놓여 일부가 잘릴 수도 있습니다.
표시할 수 있는 정보 — 예시 항목 읽는 방법
처음에는 ✓ 표시 항목 중 필요한 것부터 고릅니다. 아래는 분류별 대표 항목이며, 모든 항목을 한꺼번에 넣을 필요는 없습니다.
| 중요도 | 분류 | 대표 항목 | 읽는 방법 | 처음 추천 |
|---|---|---|---|---|
| 핵심 | ① Claude·세션 | Model | 현재 사용 중인 모델 이름을 표시합니다. | ✓ 모델 |
| 참고 | Session Clock | Session: 1hr 12m은 현재 세션에서 1시간 12분이 지났음을 표시합니다. | ✓ Session 시간 | |
| 참고 | Thinking Effort 등 | Thinking: high 같은 사고 노력 수준을 표시하며, 이 밖에도 버전·세션 이름·Claude 서비스 상태 등을 표시합니다. | — | |
| 핵심 | ② 작업 폴더·Git | Current Working Dir | cwd: 뒤에 현재 작업 폴더의 경로를 표시합니다. | ✓ 현재 폴더 |
| 참고 | Git Branch | ⎇ main처럼 현재 Git 브랜치를 표시합니다. | ✓ Git 브랜치 | |
| 참고 | Git Changes 등 | 삽입·삭제한 줄 수를 표시하며, 이 밖에도 저장소의 변경 상태·충돌·작업 사본 정보 등을 표시합니다. | — | |
| 핵심 | ③ 토큰·컨텍스트 | Context % · Context Bar | 지금 대화가 모델의 기억 공간을 얼마나 쓰는지 비율이나 막대로 표시합니다. | ✓ Context % 또는 막대 |
| 참고 | Context Length 등 | Ctx: 48.2k는 사용한 토큰 수, Ctx Used: 24.0%는 사용 비율입니다. 문맥 길이를 토큰 수로 표시하며, 이 밖에도 입력·출력 토큰 수·처리 속도·대화 압축 횟수 등을 표시합니다. | — | |
| 핵심 | ④ 사용량·비용 (구독 한도) | Block Usage | 5h: 38.0%처럼 5시간 구독 한도의 사용률을 표시합니다. | ✓ 5h 사용량 |
| 중요 | Weekly Usage · Reset 등 | 주간 구독 한도 사용률과 한도 재설정까지 남은 시간을 표시하며, 이 밖에도 예상 사용률·한도 도달까지 남은 시간 등을 표시합니다. | — | |
| 중요 | Session Cost | Cost: $1.84처럼 현재 세션 비용을 미국 달러로 표시합니다. | — | |
| 참고 | ⑤ 화면 꾸미기·사용자 정의 | Custom Text · Flex Separator 등 | 직접 쓴 글과 폭을 조절하는 구분자를 배치하며, 이 밖에도 기호·링크·사용자 명령의 출력 등을 표시합니다. | — |
Context %는 구독 잔여량이 아닙니다. 지금 대화가 모델 기억 공간을 얼마나 쓰는지 나타냅니다. Ctx Used: 24.0%를 구독 사용량이 76% 남았다는 뜻으로 읽지 않습니다. 별도 항목인 Context % (usable)은 자동으로 대화를 압축하기 전까지 쓸 수 있는 예산의 추정 비율이며, 기본 예산은 전체 기억 공간의 80%입니다.
5h·Weekly는 구독 사용 한도입니다. Claude Code가 전달하는 값과 로그인한 Claude 계정의 사용량 정보를 가져와 표시합니다. 예시의 Reset: 3hr 10m은 5시간 한도 재설정까지 3시간 10분이 남았다는 뜻입니다.
Cost는 현재 세션의 비용(USD) 표시입니다. 구독 요금 청구액과 같은 값으로 해석하지 않습니다. auto mode on은 ccstatusline 항목이 아닌 Claude Code 자체의 승인 모드 표시입니다.
화면은 어디까지 꾸밀 수 있습니까?
설정 도구에서 여러 줄을 만들고 항목을 추가·삭제하거나 순서를 바꾸며, 항목마다 색을 고르고 실시간 미리보기로 확인합니다. Flex Separator는 화면 폭에 맞춰 항목 사이 간격을 조절하는 구분자입니다. Powerline은 화살표 모양으로 구간을 나누는 스타일이며, 기호를 제대로 표시하려면 전용 글꼴이 필요할 수 있습니다.
처음에는 단순한 글자 구성으로 시작합니다. 설정은 ~/.config/ccstatusline/settings.json에 저장하며, JSON이라는 설정 파일 형식으로 내보내거나 가져올 수 있습니다.
프로젝트가 공개한 공식 소개와 실제 데모 및 공식 사용 안내에서 항목과 꾸미기 기능을 확인합니다.
1. 어느 컴퓨터에 설정할지 정합니다
Claude Code가 실행되는 컴퓨터에 설정합니다. 내 컴퓨터(로컬)에서 직접 실행하면 로컬에 설정합니다. SSH로 접속한 원격 컴퓨터에서 실행하면 원격 컴퓨터에 설정합니다. 원격 컴퓨터의 설정이 로컬에도 자동 적용되지는 않습니다.
기존 상태줄을 사용 중이면 설정 도구의 내보내기로 구성을 보관합니다. 연결 작업은 Claude Code 사용자 설정의 statusLine을 바꿀 수 있으므로 기존 상태줄 구성을 확인합니다.
2. Node.js와 npm을 확인합니다
Claude Code 자체는 권장 네이티브 방식으로 Node.js 없이 설치됩니다. npm 설치 방식을 선택할 때만 Node.js 22 이상이 필요합니다. Claude Code 공식 설치 문서
아래 방법은 Node.js와 함께 제공되는 npm·npx를 사용합니다. 없다면 Node.js 공식 다운로드에서 현재 LTS의 해당 OS 설치 방법을 따릅니다. Claude Code 자체 설치와 ccstatusline 실행 준비는 구분합니다.
Mac — 일반 터미널의 zsh
node --version
npm --version
npx -y ccstatusline@latestWindows — 일반 PowerShell
node --version
npm --version
npx -y ccstatusline@latestLinux — 일반 터미널의 bash
node --version
npm --version
npx -y ccstatusline@latest세 OS의 실행 명령은 같습니다. 위 세 줄을 차례로 확인하며, Claude Code의 대화 입력창이 아닌 일반 셸에 입력합니다. 마지막 줄은 패키지를 내려받아 설정 도구를 실행합니다. @latest는 최신판을 뜻합니다.
실행 근거: 제작자 시작 안내 · 제작자 Windows 안내.
3. 설정 도구에서 표시 항목과 Claude Code 연결을 선택합니다
- 설정 화면에서 모델·현재 폴더·문맥 사용량 같은 기본 항목을 골라 미리보기를 확인합니다.
- 처음에는 특수 글꼴이 필요한 장식 대신 단순한 글자 구성을 선택합니다.
- Claude Code에 설치·연결하는 기능을 진행합니다. Pinned global install을 선택하면 지금 실행 중인 버전을 전역 설치하고 그 버전으로 연결합니다.
- 고정 설치를 선택하지 않은 npx 방식은 연결 설정에 따라 최신판을 따라갈 수 있습니다. 어떤 명령으로 연결됐는지 확인합니다.
- 설정 화면을 종료하고 Claude Code를 다시 실행합니다. 기존 작업 중이라면 저장된 결과를 확인한 뒤 Claude Code에서
/exit로 종료합니다.
고정 설치 후에는 일반 셸에서 ccstatusline으로 설정 화면을 다시 열 수 있습니다. 세 OS 모두 같은 명령이지만 실행 파일을 찾을 수 있는 환경이어야 합니다. 권한이나 실행 정책 오류가 나면 오류 내용과 사용 셸을 확인하며 관리자 실행이나 보안 설정 변경을 자동으로 덧붙이지 않습니다.
4. 표시와 복구를 확인합니다
Mac·Windows·Linux 모두 프로젝트 폴더의 일반 셸에서 claude를 실행합니다. 짧은 요청을 보낸 뒤 아래 표시줄이 나타나는지 확인합니다. 폴더와 모델 표시가 실제 작업 대상과 맞는지도 확인합니다.
빈 항목은 해당 데이터가 아직 없거나 별도 도구가 필요한 경우가 있습니다. 기본 항목부터 확인하고, 깨진 기호는 글꼴 또는 단순 테마로 조정합니다. 특정 폴더에서만 비어 있으면 그 폴더를 Claude Code에서 신뢰한 작업 폴더로 설정했는지 확인합니다. 상태줄 명령은 신뢰한 작업 폴더에서만 실행됩니다. 사용을 중단할 때는 ccstatusline 설정 도구의 Claude Code 연결 해제 기능을 이용하고 이전에 내보낸 구성을 필요에 따라 복원합니다.
확인일: 2026-11-08. Claude Code 공식 상태줄 설명 · 기본 모드 표시 읽기 · 승인 모드.