opencode-usage-limit
v1.0.3
Published
OpenCode plugin that shows today's remaining usage limit as a sidebar gauge, tracks 429 rate limits, and provides a /usage dashboard
Maintainers
Readme
opencode-usage-limit
OpenCode 플러그인 — 오늘 남은 사용량 한도를 사이드바 최하단 게이지로 표시하고, 429 rate limit을 실측 추적합니다.
⚡ 오늘 남음 1.16M (38%) · 10h 11m 리셋
[████░░░░░░] 사용 1.8M · 86 req
⛔ 429 쿨다운 38m (429 발생 시에만)- 바의 채워진 부분 = 남은 비율 (사용할수록 줄어드는 연료게이지)
- 50% 이하 노랑, 20% 이하 빨강 + 자동 toast 경고
- 매일 자정(타임존 설정 가능) 리셋
- 429 감지 시 provider별 쿨다운 표시 (NVIDIA NIM 40분 리필, opencode Zen 무료 모델 3분, 기타 5분)
/usage슬래시 커맨드: 오늘 상세 / 모델별 Top 5 / 429 통계 대시보드
설치
PC (Linux / macOS / Windows)
npx opencode-usage-limitnpx가 TUI 게이지와 백그라운드 수집기를 ~/.config/opencode/에 설치하고 설정까지 등록합니다 (재실행 안전). 설치 후 opencode를 재시작하세요.
Android (Termux)
Termux는 표준 shebang 경로(/usr/bin/env)가 없어 npx 직접 실행이 안 됩니다. 전역 설치 후 node로 실행하세요:
npm install -g opencode-usage-limit
node "$(npm root -g)/opencode-usage-limit/bin/opencode-usage-limit.mjs"opencode의 plugin 배열로 설치 (선택)
~/.config/opencode/opencode.jsonc에 추가하면 opencode가 npm에서 자동 설치합니다 (백그라운드 수집기만 해당):
{
"plugin": ["opencode-usage-limit"]
}TUI 게이지는 위의 npx/node 실행으로 별도 설치가 필요합니다.
제거
npx opencode-usage-limit --remove # PC
# Termux: node "$(npm root -g)/opencode-usage-limit/bin/opencode-usage-limit.mjs" --remove설정 (~/.config/opencode/usage-tracker.json)
| 키 | 기본값 | 설명 |
|---|---|---|
| trackedProviders | ["opencode"] | 측정 대상 provider ID. 기본은 opencode(Console/Zen) 연결 사용량만 집계. 예: ["opencode", "nvidia"] |
| dailyLimit | 3000000 | 일일 순토큰 한도. 0이면 남은 한도 대신 사용량만 표시 |
| plan | "free" | "go" / "go-plus" 지정 시 OpenCode Go 달러 한도 게이지로 전환 (5시간 = 월 한도 20%, 월간 = 100%, 공식 단가표 내장) |
| cacheWeights | {"read": 0.1, "write": 0.25} | 순토큰 = input + output + cacheRead×0.1 + cacheWrite×0.25 |
| resetTimezone | "Asia/Seoul" | 일일 리셋 자정 기준 시간대 |
| pollSeconds | 30 | 집계 갱신 주기 |
| rateLimitPatterns | (기본 제공) | 429 감지용 에러 문자열 패턴 |
설치 시 기존 설정 파일이 있으면 덮어쓰지 않습니다.
동작 방식
- opencode의 로컬 DB(
opencode.db,part테이블의 step-finish 파트)를 읽기 전용으로 집계 — 별도 기록 없이 설치 즉시 오늘 사용량이 표시됩니다 message.part.updated이벤트 + 주기적 폴링으로 실시간 갱신- 백그라운드 수집기(
index.js)가 429 에러를 감지해~/.config/opencode/usage-tracker/rate-limits.json에 기록하면 TUI가 표시합니다
구성 요소
| 파일 | 설치 위치 | 역할 |
|---|---|---|
| index.js | npm 플러그인 (opencode가 자동 설치) | 백그라운드 429 수집기 |
| tui/usage-tracker.js | ~/.config/opencode/tui-plugins/usage-tracker.js | TUI 게이지 + /usage 대시보드 |
| config-default.json | ~/.config/opencode/usage-tracker.json | 기본 설정 (설치 시 기존 파일이 없을 때만 생성) |
유의사항
- opencode.db는 기기별 로컬입니다. 여러 기기가 같은 계정을 써도 각 기기 사용량만 집계되며, 각 기기에 설치하면 각자 표시됩니다. 서버 측 전체 사용량은 opencode.ai/console에서 확인하세요.
- 다른 플러그인이
sidebar_footer슬롯(단일 승자)을 사용 중이면 게이지가 대신 표시될 수 있습니다. 기존 footer 플러그인은sidebar_content(append 방식) 슬롯으로 옮기면 공존합니다.
요구 사항
- opencode
- node 18 이상 (설치 CLI용)
License
MIT
