cship: Claude Code를 위한 세련된 상태줄

cship 로고

Claude Code를 사용하다 보면 한 가지 아쉬운 점이 있다. 현재 세션의 비용이 얼마나 누적되었는지, 컨텍스트 윈도우는 얼마나 사용했는지, API 사용량 제한은 어느 정도인지 — 이 모든 정보를 한눈에 확인하기 어렵다는 것이다.

cship은 이 문제를 해결한다. Rust로 작성된 가볍고 빠른 상태줄(statusline)로, Claude Code 세션의 핵심 정보를 터미널에서 실시간으로 보여준다.

왜 cship인가?

1. 비용 가시성

Claude Code를 하루 종일 사용하다 보면 비용이 꽤 쌓일 수 있다. cship은 세션 비용을 실시간으로 추적하며, 설정한 임계값에 도달하면 색상이 변해 경고를 준다.

[cship.cost]
warn_threshold = 2.0      # $2에서 노란색
warn_style = "yellow"
critical_threshold = 5.0  # $5에서 빨간색
critical_style = "bold red"

2. 컨텍스트 윈도우 관리

Claude의 컨텍스트 윈도우는 한정되어 있다. cship은 시각적인 프로그레스 바로 컨텍스트 사용량을 보여주므로, 언제 새 세션을 시작해야 할지 직관적으로 파악할 수 있다.

cship 데모

3. API 사용량 모니터링

Claude API에는 5시간 및 7일 기준 사용량 제한이 있다. cship은 이 제한을 퍼센트로 표시해, 갑작스러운 API 차단을 예방한다.

[cship.usage_limits]
five_hour_format = "5h {pct}%"
seven_day_format = "7d {pct}%"
warn_threshold = 70.0
critical_threshold = 90.0

Starship과의 완벽한 통합

cship의 가장 큰 장점은 Starship passthrough다. 이미 Starship으로 터미널을 꾸며놨다면, 그 설정을 그대로 활용할 수 있다.

[cship]
lines = [
  "$directory $git_branch $git_status",
  "$cship.model $cship.cost $cship.context_bar",
]

위 설정은 첫 번째 줄에 프로젝트 디렉토리와 Git 상태를, 두 번째 줄에 Claude 관련 정보를 표시한다. Starship 모듈과 cship 모듈을 자유롭게 섞을 수 있다.

cship 전체 예시

설치와 설정

빠른 설치

curl -fsSL https://cship.dev/install.sh | bash

이 스크립트는 OS와 아키텍처를 자동으로 감지해 바이너리를 설치하고, ~/.claude/settings.json에 필요한 설정을 추가한다.

수동 설치 (Cargo)

cargo install cship

이후 ~/.claude/settings.json에 다음을 추가:

{
  "statusLine": { "type": "command", "command": "cship" }
}

최소 설정

~/.config/cship.toml을 생성하고:

[cship]
lines = ["$cship.model $cship.cost $cship.context_bar"]

이것만으로도 모델명, 비용, 컨텍스트 바가 표시된다.

주요 모듈

cship이 제공하는 핵심 토큰들:

토큰	설명
`$cship.model`	Claude 모델 이름
`$cship.cost`	세션 비용 (USD)
`$cship.context_bar`	컨텍스트 사용량 프로그레스 바
`$cship.context_window`	토큰 수 (사용/전체)
`$cship.usage_limits`	API 사용량 제한 (5시간/7일)
`$cship.agent`	서브 에이전트 이름
`$cship.session`	세션 식별 정보
`$starship_prompt`	Starship 프롬프트 전체

Nerd Fonts로 더 예쁘게

Nerd Fonts를 사용하면 아이콘을 활용해 더 세련된 상태줄을 만들 수 있다.

[cship.model]
symbol = "󰚩 "  # 로봇 아이콘
style = "bold fg:#7aa2f7"

[cship.context_bar]
symbol = " "  # CPU 아이콘
style = "fg:#7dcfff"

[cship.cost]
symbol = "💰 "
style = "fg:#a9b1d6"

디버깅

뭔가 잘 작동하지 않을 때는 cship explain 명령으로 현재 상태를 확인할 수 있다.

cship explain

이 명령은 cship이 Claude Code의 JSON에서 어떤 데이터를 읽고 있는지, 어떤 설정 파일을 사용하는지 보여준다.

마치며: 터미널에서 Claude Code 완전 정복

cship은 단순한 상태줄이 아니다. Claude Code를 사용하는 개발자에게 필요한 정보를 필요한 순간에 제공하는 대시보드다.

비용 관리: 실시간 비용 추적으로 예산 초과 방지
컨텍스트 최적화: 사용량 시각화로 효율적인 세션 관리
API 제한 모니터링: 갑작스러운 차단 없이 안전하게 사용
Starship 통합: 기존 터미널 설정과 완벽하게 조화

Rust로 작성되어 10ms 이내 렌더링을 보장하며, 시스템에 거의 부하를 주지 않는다. Claude Code를 자주 사용한다면, cship은 필수 도구다.

🔗 관련 정보

GitHub: https://github.com/stephenleo/cship
공식 문서: https://cship.dev
Starship: https://starship.rs
Nerd Fonts: https://www.nerdfonts.com