Claude mod가 나와서 만든 첫 플러그인, usage-status

시작하며

Cmux, Orca처럼 새로 나오는 AI 개발 도구는 실험 삼아 써 보는 편입니다. Claude 데스크탑 앱은 불편한 점이 하나 있었는데, 사용량 한도를 화면에서 바로 확인하기 어렵다는 것이었습니다. 5시간 한도를 얼마나 썼는지 보려면 매번 설정 화면에 들어가야 했습니다.

그러던 중 Claude Code에 mod가 나왔습니다. 어떻게 활용할까 고민하다가, 그 아쉬움부터 해결하는 플러그인을 만들었습니다.

Claude Code 2.1.295 기준입니다. mod API는 새 기능이라 바뀔 수 있습니다.

만든 것

입력창 아래 한 줄에 네 가지를 보여줍니다. 형식은 Orca를 참고했습니다.

• 5시간 한도: 사용률과 리셋까지 남은 시간
• 7일 한도: 사용률과 리셋까지 남은 시간
• 컨텍스트: 대화가 컨텍스트 창을 얼마나 채웠는지
• 세션 비용: 쓴 토큰을 API 요금으로 환산한 값

한도가 80%, 95%를 넘으면 토스트로 한 번 알려줍니다.

바로 써 보기

두 가지 방법이 있습니다.

1. 플러그인 설치

터미널에서 claude를 실행하고 한 줄이면 됩니다.

/plugin install usage-status --marketplace sijunnoh/claude-usage-status

user 범위로 설치하면 새로 여는 세션마다 자동으로 켜집니다. 데스크탑 앱 Code 탭에서는 이 명령을 쓸 수 없지만, 터미널에서 한 번 설치하면 데스크탑 앱에도 뜹니다.

2. 프롬프트로 직접 만들기

형식을 내 입맛대로 바꾸고 싶다면 아래 프롬프트를 Claude Code에 붙여 넣으면 됩니다. Claude가 mod를 만들고 테스트하고 설치까지 합니다.

Claude Code mod를 만들어줘. 데스크탑 앱 상태줄에 사용량을 항상 띄우는 mod야.
 
## 이름
usage-status
 
## 표시 형식
예: `14% used 3h 3m · 8% used 6d 9h · 84k/200k 42% · $1.23`
(` · ` 는 실제로 `\u2003·\u2003` — 일반 공백은 화면에서 합쳐짐)
 
순서
1. 5시간 한도(five_hour): `{사용률}% used {리셋까지 남은 시간}`
2. 7일 한도(seven_day): 같은 형식
3. 컨텍스트: `{사용 토큰}/{전체 토큰} {퍼센트}%`
4. 세션 비용: `$` + 소수 둘째 자리
 
규칙
- 사용률은 정수로 반올림
- 남은 시간은 내림: 1일 이상 `6d 9h`, 1시간 이상 `3h 3m`, 그 미만 `42m`
- 토큰: 1000 미만 그대로, 1000 이상 `84k`, 100만 이상 `1M` · `1.5M`
- 컨텍스트 퍼센트는 엔진 값, 없으면 tokens/window 로 계산
- 값이 없는 항목은 숨김, 전부 없으면 상태줄을 비움
 
## 갱신
- 세션 시작: $.session.usage()
- 매 턴 끝: session.measure 이벤트
- 1분마다: 분 경계에 맞춰($.clock.after → $.clock.every) 다시 그림
- session.start 가 다시 와도 타이머가 겹치지 않게
- 그리기는 $.ui.status (앞에 플러그인 이름이 붙는 건 그대로 둠)
 
## 한도 경고
- five_hour · seven_day 가 80%, 95% 를 넘으면 $.ui.toast 로 한 번
- 같은 창(종류 + resetsAt)에서는 문턱마다 한 번만, 리셋되면 다시
 
## 테스트
- 포맷 단위 테스트: 시간 · 토큰 형식, 순서, 값 없는 항목 숨김
- mock.clock 통합 테스트: 시작 → 분 경계 → 1분마다 남은 시간이 줄어드는지, 타이머 중복 없는지
- claude plugin validate, claude plugin test, tsc 통과
 
## 설치
- ~/.claude/mods/usage-status 에 두고 로컬 marketplace 로 등록해 user 범위로 설치
- claude plugin list 로 enabled 확인

mod란

Claude Code의 화면과 동작을 바꾸는 확장입니다. 바꿀 수 있는 건 생각보다 많습니다.

• 상태줄: 입력창 아래 한 줄 (이번에 만든 것)
• 토스트: 잠깐 떴다 사라지는 알림
• 입력창 위 띠: 버튼까지 넣을 수 있는 한 줄
• 옆 패널: 실시간으로 갱신되는 화면
• 도구 호출: 특정 명령을 막거나, 실행 전에 확인받거나, 인자를 고치기
• 프롬프트: 사용자 입력이나 시스템 프롬프트에 내용 덧붙이기
• 슬래시 명령: /my-command 같은 명령 추가

파일 세 개면 됩니다.

usage-status/
├── .claude-plugin/plugin.json   # 이름 · 버전
└── hooks/
    ├── hooks.json               # { "modules": ["./register.ts"] }
    └── register.ts              # 코드

코드는 이벤트에 훅을 거는 방식입니다.

export const register: Register = on => {
  on('session.start', async ($, e, next) => {
    const result = await next(e) // 엔진 기본 동작
    $.ui.status('hello')         // 상태줄에 표시
    return result
  })
}

$는 엔진 기능, e는 이벤트 입력, next는 다음 단계입니다. Express 미들웨어와 비슷합니다.

핵심 코드

사용량은 엔진이 이미 갖고 있습니다. 세션 시작 때 $.session.usage()로 읽고, 이후엔 매 턴 끝에 오는 session.measure 이벤트로 갱신합니다.

on('session.measure', async ($, e, next) => {
  $.ui.status(format(e, await $.clock.now()))
  return next(e)
})

한도 정보에 리셋 시각(resetsAt)이 있어서 남은 시간은 직접 계산합니다. 턴이 없어도 시간이 줄어들도록 분 경계에 맞춰 1분마다 다시 그립니다.

const now = await $.clock.now()
timer?.cancel() // 중복 방지
timer = $.clock.after(60_000 - (now % 60_000), () => {
  void show()
  timer = $.clock.every(60_000, () => void show())
})

마치며

상태줄 한 줄을 띄우는 작은 플러그인이었지만, mod로 Claude Code를 내 작업 방식에 맞게 바꿀 수 있다는 걸 알게 됐습니다. 예를 들어 git push --force나 운영 DB에 쓰는 명령처럼 위험한 명령은 실행하기 전에 항상 확인을 받게 할 수도 있습니다. 앞으로도 mod로 이것저것 시도해 볼 만한 것 같습니다.

참조자료

• Claude Code 문서