claude-token-saver 2.16.0 → 2.18.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.en.md +131 -193
- package/README.md +123 -186
- package/bin/cli.js +21 -1
- package/package.json +1 -1
- package/src/advice.js +49 -34
- package/src/cost.js +16 -1
- package/src/demo.js +11 -4
- package/src/formatters/statusline.js +29 -8
- package/src/formatters/table.js +2 -2
- package/src/history.js +5 -1
package/README.md
CHANGED
|
@@ -7,270 +7,207 @@
|
|
|
7
7
|
|
|
8
8
|
# claude-token-saver
|
|
9
9
|
|
|
10
|
-
|
|
10
|
+
**Claude Code 토큰 사용량을 statusline 한 줄로 진단하고 절약하는 CLI.** 의존성 0, 설치 한 줄이면 끝.
|
|
11
11
|
|
|
12
|
-
|
|
12
|
+
```bash
|
|
13
|
+
npm i -g claude-token-saver # postinstall이 statusline + Skill 자동 등록
|
|
14
|
+
```
|
|
13
15
|
|
|
14
16
|
|
|
15
17
|
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
## 실제 효과 — harness + ratchet 도입 전후 비용 절감 리포트
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
claude-token-saver에 최근 추가된 **harness 5/5 + ratchet** 기능을 실제 적용해보고 도입 전후를 비교한 결과입니다 (저자 본인의 Claude Code 사용 로그, **사용자 메시지 1건당**으로 정규화, 2026-05-02 기준, Opus 4.7 가격):
|
|
23
|
-
|
|
24
|
-
| 메트릭 | 도입 전 (7일 / 739msg) | 도입 후 (2일 / 157msg) | 변화 |
|
|
25
|
-
|---|---:|---:|---:|
|
|
26
|
-
| 메시지당 비용 | $2.345 | $1.910 | **−18.6%** |
|
|
27
|
-
| 메시지당 출력 토큰 | 7,391 | 6,052 | −18.1% |
|
|
28
|
-
| 메시지당 assistant 왕복 | 9.73 | 8.83 | −9.2% |
|
|
29
|
-
| 메시지당 도구 호출 | 5.72 | 5.25 | −8.2% |
|
|
30
|
-
|
|
31
|
-
같은 요청을 더 적은 왕복으로 끝낸다 = 첫 시도 적중률 ↑. PEV·Structured Task가 강제로 한 번에 가게 만든 효과로 보입니다.
|
|
18
|
+
## ⚡ 왜 쓰나 — 30초 요약
|
|
32
19
|
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
20
|
+
| | |
|
|
21
|
+
|---|---|
|
|
22
|
+
| 💸 **비용 실측 −18.6%** | harness+ratchet 도입 전후, 사용자 메시지당 비용 $2.35 → $1.91 (저자 로그, [상세](#실제-효과--도입-전후-리포트)) |
|
|
23
|
+
| 🚨 **한도 초과 예방** | 5H/7D rate-limit 윈도 90% 도달 시 즉시 경고 + `handoff`로 작업 백업 |
|
|
24
|
+
| 🧠 **캐시 낭비 감지** | 히트율·TTL 카운트다운·1M 컨텍스트 자동 감지 — 토큰 급증 원인을 코드로 진단 |
|
|
25
|
+
| 🅷 **같은 실수 차단** | 반복 에러를 감지해 ratchet 룰로 승격 — 다음 세션부터 자동 적용 |
|
|
26
|
+
| 💰 **절감액 가시화** | 프롬프트 캐시가 아껴준 금액을 실시간 표시 (`💰 Cache saved $2.1K`) |
|
|
40
27
|
|
|
41
|
-
|
|
28
|
+
📺 [출시 영상 (60초)](https://www.youtube.com/shorts/RaD8qMsPTnA)
|
|
42
29
|
|
|
43
30
|
---
|
|
44
31
|
|
|
45
|
-
##
|
|
46
|
-
|
|
47
|
-
### 사전 준비 — Node.js (≥ 18) 필요
|
|
48
|
-
|
|
49
|
-
`npm`은 Node.js에 포함되어 있습니다. 설치돼 있는지 확인:
|
|
50
|
-
|
|
51
|
-
```bash
|
|
52
|
-
node -v # v18.0.0 이상이면 OK
|
|
53
|
-
```
|
|
54
|
-
|
|
55
|
-
설치되어 있지 않다면:
|
|
56
|
-
|
|
57
|
-
- **macOS** — `brew install node` (Homebrew) 또는 [nodejs.org](https://nodejs.org/) 설치 프로그램
|
|
58
|
-
- **Windows** — [nodejs.org](https://nodejs.org/) LTS 설치 프로그램, 또는 `winget install OpenJS.NodeJS.LTS`
|
|
59
|
-
- **Linux / WSL** — 배포판 패키지 매니저(`apt install nodejs npm` 등) 또는 [nvm](https://github.com/nvm-sh/nvm)으로 사용자 영역 설치 (sudo 없이 가능, 추천)
|
|
60
|
-
|
|
61
|
-
> sudo로 글로벌 설치하면 postinstall 훅이 root의 `~/.claude`에 SKILL을 만들어 자동 등록이 어긋납니다. 가능하면 nvm/fnm/Volta로 사용자 영역에 Node를 설치하거나 `npm config set prefix ~/.npm-global` 같은 prefix 변경 후 사용하세요.
|
|
32
|
+
## 시작하기
|
|
62
33
|
|
|
63
|
-
|
|
34
|
+
**사전 준비:** Node.js ≥ 18 (`node -v`로 확인 · macOS `brew install node` · Windows `winget install OpenJS.NodeJS.LTS` · Linux/WSL은 [nvm](https://github.com/nvm-sh/nvm) 권장)
|
|
64
35
|
|
|
65
36
|
```bash
|
|
66
|
-
# (
|
|
67
|
-
npm uninstall -g claude-cache-monitor
|
|
68
|
-
|
|
69
|
-
# 설치 — postinstall 훅이 Skill과 statusline을 자동 등록합니다
|
|
37
|
+
npm uninstall -g claude-cache-monitor # (구 패키지 사용자만)
|
|
70
38
|
npm i -g claude-token-saver
|
|
71
39
|
```
|
|
72
40
|
|
|
73
|
-
설치
|
|
74
|
-
|
|
75
|
-
`--ignore-scripts`나 sudo 등으로 postinstall이 실행되지 않은 환경에서는 다음 명령으로 수동 등록할 수 있습니다.
|
|
76
|
-
|
|
77
|
-
```bash
|
|
78
|
-
claude-token-saver install
|
|
79
|
-
```
|
|
80
|
-
|
|
81
|
-
## Claude Code statusline
|
|
82
|
-
|
|
83
|
-
설치 후 Claude Code 하단 statusline에 캐시 상태가 5초마다 갱신됩니다 (postinstall이 `~/.claude/settings.json`에 자동 등록).
|
|
84
|
-
|
|
85
|
-
```
|
|
86
|
-
🤖 Opus 4.7 · 🧠 Cache hit 98.0% · ⏳ Cache expires 58:38 · ✦ current █░░░░░ 15% 🔄 08:50 · 📅 weekly █▒░░░░ 24% 🔄 Thu 13:00 · 📦 Ctx 200k · 💰 Cache saved $205 · last 1d
|
|
87
|
-
```
|
|
41
|
+
설치 즉시 Claude Code 하단에 statusline이 나타납니다. `--ignore-scripts`/sudo 등으로 자동 등록이 안 됐다면 `claude-token-saver install`로 수동 등록하세요.
|
|
88
42
|
|
|
89
|
-
|
|
43
|
+
> ⚠️ sudo 글로벌 설치는 Skill이 root의 `~/.claude`에 등록되는 함정이 있습니다 — nvm/fnm/Volta로 사용자 영역 설치를 권장합니다.
|
|
90
44
|
|
|
91
|
-
|
|
45
|
+
## statusline 읽는 법
|
|
92
46
|
|
|
93
47
|
```
|
|
94
|
-
|
|
48
|
+
🤖 Opus 4.8 · 🧠 Cache hit 98.0% · ⏳ Cache expires 58:38 · ✦ current █░░░░░ 15% 🔄 08:50 · 📅 weekly █▒░░░░ 24% 🔄 Thu 13:00 · 📦 Ctx 200k · 💰 Cache saved $205 · last 1d
|
|
95
49
|
```
|
|
96
50
|
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
"type": "command",
|
|
107
|
-
"command": "claude-token-saver --statusline --icon",
|
|
108
|
-
"refreshInterval": 5
|
|
109
|
-
}
|
|
110
|
-
}
|
|
111
|
-
```
|
|
112
|
-
|
|
113
|
-
`refreshInterval: 5`는 idle 상태에서도 TTL 카운트다운을 5초마다 갱신합니다. Windows(PowerShell)는 `examples/statusline-command.ps1` 참고.
|
|
114
|
-
|
|
115
|
-
## 경고 칩이 떴을 때 — Skill 워크플로
|
|
116
|
-
|
|
117
|
-
설치 시 함께 등록되는 Claude Code Skill이 "경고 칩 → 처방"의 다리 역할을 합니다.
|
|
118
|
-
|
|
119
|
-
1. **statusline에 경고 칩이 뜬다** — 예: `🚨 5H 94%`, `⚠ Cache miss`, `⚠ 1M ON`.
|
|
120
|
-
2. **`/claude-token-saver` Skill을 실행한다** — Claude에서 슬래시로 Skill을 직접 호출하는 게 가장 간단합니다. 또는 칩 문구를 그대로 말해도 동일한 Skill이 자동 활성화됩니다 ("5H cap 떴어", "cache miss 떴어", "1M context 왜 켜졌지?" 등 — 칩 텍스트가 트리거 단어로 등록돼 있음).
|
|
121
|
-
3. **Skill이 처방을 가져온다** — 내부적으로 `claude-token-saver last`를 실행해 가장 최근 경고 + 원인 코드 + 단계별 해결 명령을 한 번에 보여주고, 캡 임박 시에는 `claude-token-saver handoff`로 현재 작업 백업을 권합니다.
|
|
122
|
-
4. **수동 확인이 필요하면** — `claude-token-saver last` (최근 1건), `claude-token-saver history` (최근 7일 전이 로그), `claude-token-saver handoff` (cap 직전 백업)를 직접 실행해도 같은 정보를 얻을 수 있습니다.
|
|
123
|
-
|
|
124
|
-
> v2.6.0에서 레거시 `/token-monitor` 슬래시 커맨드는 이 Skill로 흡수됐습니다. 이전 버전 사용자는 `claude-token-saver install`을 한 번 더 실행하면 자동 정리됩니다.
|
|
125
|
-
|
|
126
|
-
## 단발 리포트
|
|
51
|
+
| 세그먼트 | 의미 |
|
|
52
|
+
|---|---|
|
|
53
|
+
| `🤖` | 현재 모델 |
|
|
54
|
+
| `🅷 5/5` | harness 원칙 점수 ([Harness 모드](#-harness-모드)) |
|
|
55
|
+
| `🧠` | 캐시 히트율 (85%+ 녹색) |
|
|
56
|
+
| `⏳` | 캐시 TTL 카운트다운 — 만료 전에 메시지를 보내면 캐시 유지 |
|
|
57
|
+
| `✦ current` / `📅 weekly` | 5시간 / 7일 rate-limit 윈도 사용률 + 리셋 시각 |
|
|
58
|
+
| `📦` | 컨텍스트 사용률 (예: `Ctx 68% of 1M`) — 사용률 기준 녹/황/적. 현재 모델은 1M이 기본·프리미엄 없음이지만, 토큰량 자체가 턴당 비용과 5H/7D 한도를 태웁니다 |
|
|
59
|
+
| `💰` | 캐시가 절약해준 누적 금액 |
|
|
127
60
|
|
|
128
|
-
|
|
61
|
+
문제가 감지되면 **경고 칩이 맨 앞에** 붙습니다:
|
|
129
62
|
|
|
130
63
|
```
|
|
131
|
-
|
|
132
|
-
(claude-token-saver v2.9.0)
|
|
133
|
-
══════════════════════════════════════════════════
|
|
134
|
-
|
|
135
|
-
Context window: 200k ✓ 200k context (standard)
|
|
136
|
-
Sessions: 11 | API calls: 578 | Cache hit rate: 98.0%
|
|
137
|
-
TTL Breakdown / Cost Impact / Daily Trend …
|
|
64
|
+
🚨 5H █████▓ 94% 🔄 12:36 · 🅷 5/5 · 🤖 Opus 4.8 · 🧠 Cache hit 72.1% · ⚠ Cache miss · 📅 weekly ▓░░░░░ 12% 🔄 Sun 14:26 · 📦 Ctx 200k · last 1d
|
|
138
65
|
```
|
|
139
66
|
|
|
140
|
-
|
|
67
|
+
칩 종류 — `🚨 5H/7D NN%`(캡 임박) · `⚠ Ctx 200k+`(단일 요청이 실제로 200k 초과) · `⚠ Cache miss` · `⚠ Input spike` · `⚠ Output heavy` · `⚠ Call surge` · `⚠ Rebuild churn` · `⚠ 5m TTL`. 두 윈도가 동시에 90%+면 리셋이 임박한 쪽이 🚨로 승격되고 나머지는 빨간 세그먼트로 유지됩니다 (v2.16.0+).
|
|
141
68
|
|
|
142
|
-
|
|
69
|
+
### 경고 칩이 떴을 때
|
|
143
70
|
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
```bash
|
|
147
|
-
claude-token-saver mode ko # 또는: claude-token-saver mode lang=ko
|
|
148
|
-
claude-token-saver mode en # 영어로 복귀
|
|
149
|
-
claude-token-saver mode # 현재 설정 확인
|
|
150
|
-
```
|
|
71
|
+
Claude 안에서 `/claude-token-saver` Skill을 실행하거나 칩 문구를 그대로 말하면("5H cap 떴어", "cache miss") Skill이 자동 활성화되어 **원인 코드 + 단계별 해결 명령**을 보여줍니다. 캡 임박 시에는 `claude-token-saver handoff`로 현재 작업을 마크다운으로 백업한 뒤 새 세션에서 이어가는 워크플로를 권합니다.
|
|
151
72
|
|
|
152
73
|
## 주요 명령
|
|
153
74
|
|
|
154
|
-
|
|
75
|
+
셸에서 직접 실행합니다 (Claude Code 안에서는 `/claude-token-saver` Skill 하나만 사용):
|
|
155
76
|
|
|
156
77
|
| 명령 | 설명 |
|
|
157
78
|
|---|---|
|
|
158
|
-
| `claude-token-saver` | 최근 1일 진단 리포트 (`--days N
|
|
159
|
-
| `claude-token-saver last` | 가장 최근 경고 1건 + 처방
|
|
160
|
-
| `claude-token-saver history` | 최근 7
|
|
161
|
-
| `claude-token-saver handoff` |
|
|
162
|
-
| `claude-token-saver mode [keywords...]` | 출력
|
|
163
|
-
| `claude-token-saver
|
|
164
|
-
| `claude-token-saver install` | Skill·statusline 수동 등록
|
|
165
|
-
| `claude-token-saver --install-hook` | 매 도구 호출마다 캐시 통계 자동 로깅 (선택) |
|
|
79
|
+
| `claude-token-saver` | 최근 1일 진단 리포트 (`--days N` / `--hours N`) |
|
|
80
|
+
| `claude-token-saver last` | 가장 최근 경고 1건 + 처방 |
|
|
81
|
+
| `claude-token-saver history` | 최근 7일 경고 전이 로그 |
|
|
82
|
+
| `claude-token-saver handoff` | 작업 상태를 `HANDOFF-*.md`로 백업 (캡 임박 시) |
|
|
83
|
+
| `claude-token-saver mode [keywords...]` | 출력 설정 (`icon`/`text`, `ko`/`en`, `1h`~`30d` 윈도 등) |
|
|
84
|
+
| `claude-token-saver harness ...` | 🅷 Harness 관리 (아래 참고) |
|
|
85
|
+
| `claude-token-saver install` | Skill·statusline 수동 등록 |
|
|
166
86
|
|
|
167
|
-
|
|
87
|
+
출력 언어는 `mode ko` / `mode en`으로 전환합니다 (기본 영어, statusline 칩은 항상 기호). 전체 옵션은 [영문 README](./README.en.md#options) 참고.
|
|
168
88
|
|
|
169
89
|
## 🅷 Harness 모드
|
|
170
90
|
|
|
171
|
-
다섯
|
|
91
|
+
다섯 원칙(Ratchet · Evidence · PEV · Structured Task · Default Safe Path)을 한 줄 명령으로 `CLAUDE.md`에 셋업하고 statusline이 `🅷 5/5`로 점수화합니다. 같은 에러가 반복되면 `🅷⚠ ratchet?` 알림이 떠서 룰로 승격할 수 있습니다.
|
|
172
92
|
|
|
173
93
|
```bash
|
|
174
|
-
claude-token-saver harness init #
|
|
175
|
-
claude-token-saver harness
|
|
176
|
-
claude-token-saver harness
|
|
177
|
-
claude-token-saver harness
|
|
178
|
-
claude-token-saver harness rm <N>
|
|
179
|
-
claude-token-saver harness
|
|
180
|
-
claude-token-saver harness off | on # statusline 🅷 표시 토글
|
|
94
|
+
claude-token-saver harness init # 이 프로젝트에 셋업
|
|
95
|
+
claude-token-saver harness init --global # ~/.claude/CLAUDE.md — 모든 프로젝트 적용
|
|
96
|
+
claude-token-saver harness check # 현재 점수 (글로벌 fallback 인정)
|
|
97
|
+
claude-token-saver harness promote <N> --project|--global # 경고 #N → ratchet 룰 (스코프 필수)
|
|
98
|
+
claude-token-saver harness list / rm <N> # 룰 조회 / 삭제 (자동 .bak)
|
|
99
|
+
claude-token-saver harness off | on # 🅷 표시 토글
|
|
181
100
|
```
|
|
182
101
|
|
|
183
|
-
|
|
102
|
+
- `promote`는 non-TTY(스크립트·LLM 호출)에서 `--project`/`--global` 플래그가 **필수** — 스코프가 묻지 않고 결정되는 사고를 막기 위한 설계입니다.
|
|
103
|
+
- 🅷⚠ 런타임 경고(`ratchet?` `no-evidence` `PEV-skip`)는 30분 후 자동 만료되고, 하위 디렉터리 세션도 프로젝트에 올바르게 매칭됩니다. PEV-skip은 변경성 도구(Edit/Write/Bash)만 카운트해 읽기 위주 세션에서는 발동하지 않습니다 (v2.16.0+).
|
|
184
104
|
|
|
185
|
-
|
|
105
|
+
<details>
|
|
106
|
+
<summary>⚠️ <code>harness rm</code>은 신중하게 — 삭제 전 체크리스트</summary>
|
|
186
107
|
|
|
187
|
-
|
|
188
|
-
- 예: `"하드코딩 금지"` → `"테스트 외 코드에서 하드코딩 금지"`
|
|
189
|
-
- **룰이 너무 좁아 거의 발동 안 되나?** → ❌ 삭제 ✅ **그냥 두기** (비용 0)
|
|
190
|
-
- **정말 잘못된 룰이라 확신?** → ✅ **그때만 삭제**
|
|
108
|
+
ratchet의 가치는 **한 방향 누적**에 있습니다. 룰을 가볍게 지우면 같은 실수가 다시 새기 시작합니다.
|
|
191
109
|
|
|
192
|
-
|
|
110
|
+
- **룰이 너무 광범위해서 정상 케이스도 막나?** → ❌ 삭제 ✅ 조건을 좁혀 다듬기 (예: `"하드코딩 금지"` → `"테스트 외 코드에서 하드코딩 금지"`)
|
|
111
|
+
- **룰이 너무 좁아 거의 발동 안 되나?** → ❌ 삭제 ✅ 그냥 두기 (비용 0)
|
|
112
|
+
- **정말 잘못된 룰이라 확신?** → ✅ 그때만 삭제
|
|
113
|
+
|
|
114
|
+
삭제 시 `.bak`이 남지만 **그 룰이 박힌 세션 컨텍스트(왜)는 복원되지 않습니다.**
|
|
115
|
+
</details>
|
|
193
116
|
|
|
194
117
|
## 토큰 급증 원인 코드
|
|
195
118
|
|
|
196
119
|
| 코드 | 의미 |
|
|
197
120
|
|---|---|
|
|
198
|
-
| `LARGE_INPUT_PER_REQUEST` | 단일 요청
|
|
121
|
+
| `LARGE_INPUT_PER_REQUEST` | 단일 요청 입력이 200k 초과 — 턴당 재과금·한도 소모 급증 |
|
|
199
122
|
| `LOW_HIT_RATE` | 캐시 히트율 50% 미만 |
|
|
200
|
-
| `BUCKET_5M_DOMINANT` | 캐시 쓰기의 70
|
|
201
|
-
| `HIGH_OUTPUT_RATIO` | 출력/입력 비율 0.15 초과 (출력
|
|
123
|
+
| `BUCKET_5M_DOMINANT` | 캐시 쓰기의 70%+가 5분 버킷 (Pro 플랜/Max 다운그레이드) |
|
|
124
|
+
| `HIGH_OUTPUT_RATIO` | 출력/입력 비율 0.15 초과 (출력 단가는 입력의 5배) |
|
|
125
|
+
| `HIGH_REQUEST_COUNT` | 요청 수가 중앙값의 3배+ (도구 호출 루프 의심) |
|
|
202
126
|
| `FREQUENT_CACHE_REBUILD` | 캐시 재작성이 읽기보다 많음 |
|
|
203
127
|
|
|
204
|
-
각 코드마다 OS별 해결
|
|
128
|
+
각 코드마다 OS별 해결 명령이 함께 출력됩니다.
|
|
205
129
|
|
|
206
|
-
##
|
|
130
|
+
## 실제 효과 — 도입 전후 리포트
|
|
207
131
|
|
|
208
|
-
|
|
209
|
-
npm uninstall -g claude-cache-monitor
|
|
210
|
-
npm i -g claude-token-saver
|
|
211
|
-
```
|
|
132
|
+
|
|
212
133
|
|
|
213
|
-
|
|
134
|
+
harness 5/5 + ratchet을 실제 적용한 전후 비교입니다 (저자 Claude Code 로그, **사용자 메시지 1건당** 정규화, 2026-05-02 기준, Opus 4.7 가격):
|
|
214
135
|
|
|
215
|
-
|
|
136
|
+
| 메트릭 | 도입 전 (7일/739msg) | 도입 후 (2일/157msg) | 변화 |
|
|
137
|
+
|---|---:|---:|---:|
|
|
138
|
+
| 메시지당 비용 | $2.345 | $1.910 | **−18.6%** |
|
|
139
|
+
| 메시지당 출력 토큰 | 7,391 | 6,052 | −18.1% |
|
|
140
|
+
| 메시지당 assistant 왕복 | 9.73 | 8.83 | −9.2% |
|
|
141
|
+
| 메시지당 도구 호출 | 5.72 | 5.25 | −8.2% |
|
|
216
142
|
|
|
217
|
-
|
|
143
|
+
같은 요청을 더 적은 왕복으로 끝낸다 = 첫 시도 적중률 ↑. PEV·Structured Task가 한 번에 가게 만든 효과로 보입니다.
|
|
218
144
|
|
|
219
|
-
|
|
145
|
+
<details>
|
|
146
|
+
<summary>측정 배경 — 캐시 히트율이 빠진 이유 · 샘플 주의</summary>
|
|
220
147
|
|
|
221
|
-
|
|
148
|
+
- 저자는 Max 플랜(캐시 TTL 1시간)이라 히트율이 이미 ~98%에 수렴해 개선 여지가 작았습니다. **Pro 플랜(5분 TTL) 사용자는** 만료 직전 handoff 워크플로 조합으로 히트율 자체가 오를 가능성이 큽니다.
|
|
149
|
+
- 만료 직전 handoff 워크플로: statusline TTL 카운트다운을 보다가 만료 직전 `claude-token-saver handoff`로 작업 상태를 백업하고 새 캐시 사이클을 시작. 1M 경고·cap 칩도 같은 흐름으로 처리.
|
|
150
|
+
- ⚠️ 도입 후 데이터는 2일치(157msg)로 통계적 의미가 약하고, 주별 작업 토픽 차이가 섞여 있어 도구 효과만 깨끗이 분리되진 않습니다.
|
|
151
|
+
</details>
|
|
222
152
|
|
|
223
|
-
##
|
|
153
|
+
## 동작 원리 · 환경
|
|
224
154
|
|
|
225
|
-
|
|
155
|
+
Claude Code는 모든 API 응답을 `~/.claude/projects/<dir>/<session>.jsonl`에 기록합니다. 이 도구는 `cache_read_input_tokens`, `cache_creation.ephemeral_5m/1h_input_tokens` 등을 `requestId` 기준으로 중복 제거 후 집계합니다.
|
|
226
156
|
|
|
227
|
-
|
|
157
|
+
Node.js ≥ 18 · macOS / Linux / Windows / WSL · **의존성 0**.
|
|
228
158
|
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
- `harness check`는 이제 글로벌을 **fallback**으로 인정 — 로컬 블록이 없어도 글로벌 harness가 깔려 있으면 `🅷 5/5 (covered by global)`로 표시(Claude Code가 전역 `CLAUDE.md`를 모든 프로젝트에 로드하는 실제 동작과 일치). `--project`/`--global`로 특정 스코프만 조회 가능.
|
|
232
|
-
- npm 패키지 homepage를 `https://rootstudioyaml.github.io/`로 변경, README에 **@DeepPulseEN** 채널·홈페이지 배지 추가.
|
|
159
|
+
<details>
|
|
160
|
+
<summary>알려진 환경 이슈 · 마이그레이션</summary>
|
|
233
161
|
|
|
234
|
-
|
|
235
|
-
- "실제 효과" 섹션을 **harness + ratchet 도입 전후 비용 절감 리포트** 형태로 재구성. Max(1h)/Pro(5m) 캐시 TTL 차이에 따른 히트율 개선 여지 차이 설명, 만료 직전 handoff 워크플로 안내, 7일치 누적 시점(2026-05-09) 갱신 예고 추가. 차트 제목도 동일하게 갱신.
|
|
162
|
+
**IntelliJ Claude Code plugin** — statusline 위젯이 프레임을 잘못 합성해 `59:548` 같은 잔재가 보이는 버그가 있습니다(이모지 출력에서만). v2.8.5+는 `TERMINAL_EMULATOR=JetBrains-JediTerm` 감지 시 자동으로 text 모드 폴백합니다.
|
|
236
163
|
|
|
237
|
-
|
|
238
|
-
|
|
164
|
+
**claude-cache-monitor에서 마이그레이션:**
|
|
165
|
+
```bash
|
|
166
|
+
npm uninstall -g claude-cache-monitor && npm i -g claude-token-saver
|
|
167
|
+
```
|
|
168
|
+
`~/.claude/settings.json`의 `statusLine.command`도 `claude-token-saver …`로 교체하세요.
|
|
169
|
+
</details>
|
|
239
170
|
|
|
240
|
-
|
|
241
|
-
- README에 실제 statusline 스크린샷과 "harness 5/5 + ratchet 적용 전후 효과" 차트 추가. 자체 사용 로그 기준 메시지당 비용 −18.6%, assistant 왕복 −9.2%, 일/월/년 환산 비용 절감 임팩트 카드 포함. 샘플 주의사항·작업 토픽 변수·갱신 일정(2026-05-09) 명시.
|
|
242
|
-
- npm 패키지 메타데이터(homepage / bugs / author) 정비 — DeepPulse YouTube 채널 링크 노출.
|
|
171
|
+
## 릴리스 노트
|
|
243
172
|
|
|
244
|
-
### v2.
|
|
245
|
-
-
|
|
173
|
+
### v2.18.0 (2026-07-02)
|
|
174
|
+
- **1M 컨텍스트 경고 의미 재정의** — 현재 모델(Fable 5, Opus 4.6~4.8, Sonnet 5)은 전부 1M 윈도가 기본이고 Opus 4.7부터 장기 컨텍스트 프리미엄도 없어, "1M 모드 ON = 비쌈" 프레임을 폐기했습니다. 경고는 이제 **실사용 신호**입니다: `⚠ 1M ON` → `⚠ Ctx 200k+`(단일 요청이 실제로 200k 초과), 처방도 "1M 끄기" 우선에서 "`/compact`/`/clear` + `/effort` 점검" 우선으로 재정렬. 잘못된 "200k 초과 시 장기 요금 적용" 문구 정정.
|
|
175
|
+
- **📦 세그먼트가 실시간 사용률 표시** — Claude Code stdin의 `context_window.used_percentage`를 사용해 `📦 Ctx 68% of 1M` 형태로 렌더 (사용률 기준 녹 <70 / 황 70–89 / 적 90+). stdin이 없으면 기존 크기 추론으로 폴백하되 1M은 빨강 대신 노랑.
|
|
176
|
+
- 구버전 히스토리 호환: `⚠ 1M ON` 칩·구 디테일 문구도 계속 해석됩니다.
|
|
246
177
|
|
|
247
|
-
### v2.
|
|
248
|
-
-
|
|
178
|
+
### v2.17.0 (2026-07-02)
|
|
179
|
+
- **Fable 5 가격 티어 추가** — `claude-fable-5`/`claude-mythos-5`가 Sonnet 단가($3/$15)로 폴백돼 비용이 ~3배 과소 추정되던 문제 수정. 실제 단가(입력 $10 / 출력 $50 / 캐시쓰기 5m $12.50·1h $20 / 캐시읽기 $1) 적용.
|
|
180
|
+
- README 전면 개편 — 최상위 임팩트 요약, 세그먼트 표, harness scope 플래그 문서화, 가격 테이블 최신화.
|
|
249
181
|
|
|
250
|
-
### v2.
|
|
251
|
-
-
|
|
252
|
-
-
|
|
182
|
+
### v2.16.0 (2026-07-02)
|
|
183
|
+
- **statusline 버그 수정** — 두 윈도 동시 90%+ 시 하나가 사라지던 문제(cap-warn 승격분만 숨김), `--no-color` 출력의 ANSI escape 제거, 세션 데이터 없어도 cap-warn·🅷·모델 칩 유지.
|
|
184
|
+
- **harness 경고 정확도** — 🅷⚠ 경고 30분 자동 만료(무기한 잔류 수정), 하위 디렉터리 세션 매칭, cwd 없는 상태의 전 프로젝트 누출 수정.
|
|
185
|
+
- **PEV-skip 오탐 감소** — 변경성 도구만 카운트(Read/Grep 제외), 윈도를 어시스턴트 턴 기준으로.
|
|
253
186
|
|
|
254
|
-
|
|
255
|
-
|
|
187
|
+
<details>
|
|
188
|
+
<summary>이전 버전 (v2.8.5 ~ v2.15.0)</summary>
|
|
256
189
|
|
|
257
|
-
### v2.
|
|
258
|
-
-
|
|
259
|
-
-
|
|
260
|
-
|
|
190
|
+
### v2.15.0 (2026-06-13)
|
|
191
|
+
- **글로벌 harness init** — `harness init --global`이 `~/.claude/CLAUDE.md`(+ `~/.claude/ratchet.md`)에 5개 섹션을 설치해 모든 프로젝트에 적용. `harness check`는 글로벌을 fallback으로 인정(`🅷 5/5 (covered by global)`).
|
|
192
|
+
- npm homepage 변경, @DeepPulseEN 채널·홈페이지 배지 추가.
|
|
193
|
+
|
|
194
|
+
### v2.13.x (2026-05-04)
|
|
195
|
+
- "실제 효과" 섹션을 harness+ratchet 도입 전후 리포트로 재구성, statusline 스크린샷·임팩트 차트 추가, npm 메타데이터 정비, YouTube 핸들 정정.
|
|
196
|
+
|
|
197
|
+
### v2.11.0 (2026-05-02)
|
|
198
|
+
- `harness list` / `harness rm <N>` 추가 (자동 `.bak` 백업, 삭제 전 "조건 좁히기 우선" 안내).
|
|
261
199
|
|
|
262
|
-
### v2.9.
|
|
263
|
-
-
|
|
264
|
-
- 기존 history 파일은 이중언어로 보관되며, 표시할 때 선택한 언어만 필터링됩니다.
|
|
200
|
+
### v2.9.x (2026-04-27)
|
|
201
|
+
- 출력 언어 전환(`mode ko`/`en`) 추가 — `last`/`history`/처방이 한 언어로 출력. Skill이 사용자 언어로 응답하도록 지시 추가. README에 Node.js 사전 설치 안내·Skill 워크플로 4단계 추가. `language` 설정 위치 정리.
|
|
265
202
|
|
|
266
203
|
### v2.8.6 (2026-04-27)
|
|
267
|
-
- **Skill 자동 등록** —
|
|
268
|
-
- 한·영 README 문장 다듬기, `claude-cache-monitor` alias 제거 시점 설명 정정.
|
|
204
|
+
- **Skill 자동 등록** — postinstall 훅이 Skill과 statusline을 `~/.claude`에 자동 등록.
|
|
269
205
|
|
|
270
206
|
### v2.8.5
|
|
271
|
-
- IntelliJ
|
|
207
|
+
- IntelliJ plugin 프레임 합성 버그 회피 — JediTerm 감지 시 자동 text 모드.
|
|
272
208
|
|
|
273
|
-
이전 버전은 `git log
|
|
209
|
+
더 이전 버전은 `git log` 참고.
|
|
210
|
+
</details>
|
|
274
211
|
|
|
275
212
|
## 라이선스
|
|
276
213
|
|
package/bin/cli.js
CHANGED
|
@@ -93,6 +93,24 @@ function bedrockDisplayFromId(id) {
|
|
|
93
93
|
return `${family} ${m[2]}.${m[3]}`;
|
|
94
94
|
}
|
|
95
95
|
|
|
96
|
+
/**
|
|
97
|
+
* Live context usage from Claude Code's stdin payload (`context_window`).
|
|
98
|
+
* More accurate than inferring from transcripts: it's the CURRENT session's
|
|
99
|
+
* real fill level, updated every refresh. Shape (subset):
|
|
100
|
+
* "context_window": { "context_window_size": 200000, "used_percentage": 68 }
|
|
101
|
+
*/
|
|
102
|
+
function extractContextUsage(stdinJson) {
|
|
103
|
+
const cw = stdinJson && stdinJson.context_window;
|
|
104
|
+
if (!cw || typeof cw !== 'object') return null;
|
|
105
|
+
const usedPct = Number(cw.used_percentage);
|
|
106
|
+
const size = Number(cw.context_window_size);
|
|
107
|
+
if (!Number.isFinite(usedPct)) return null;
|
|
108
|
+
return {
|
|
109
|
+
usedPct,
|
|
110
|
+
size: Number.isFinite(size) && size > 0 ? size : null,
|
|
111
|
+
};
|
|
112
|
+
}
|
|
113
|
+
|
|
96
114
|
function extractModel(stdinJson) {
|
|
97
115
|
if (!stdinJson || !stdinJson.model) return null;
|
|
98
116
|
const m = stdinJson.model;
|
|
@@ -894,6 +912,7 @@ async function main() {
|
|
|
894
912
|
const stdinJson = readStdinJson();
|
|
895
913
|
let caps = extractCaps(stdinJson);
|
|
896
914
|
let model = extractModel(stdinJson);
|
|
915
|
+
const ctxLive = extractContextUsage(stdinJson);
|
|
897
916
|
if (isStatusline && (caps || model)) {
|
|
898
917
|
try {
|
|
899
918
|
const { persistSnapshot } = await import('../src/caps-cache.js');
|
|
@@ -923,7 +942,7 @@ async function main() {
|
|
|
923
942
|
if (format === 'statusline') {
|
|
924
943
|
if (contextWindow.size === '1M') {
|
|
925
944
|
spikeChip = chipForIssues([], contextWindow);
|
|
926
|
-
chipDetail = `
|
|
945
|
+
chipDetail = `Single-request context exceeded 200k (max ${Math.round(contextWindow.maxContext / 1000)}k tokens)`;
|
|
927
946
|
} else {
|
|
928
947
|
const recentSession = sessions
|
|
929
948
|
.slice()
|
|
@@ -994,6 +1013,7 @@ async function main() {
|
|
|
994
1013
|
lastActivity,
|
|
995
1014
|
spikeReport,
|
|
996
1015
|
contextWindow,
|
|
1016
|
+
ctxLive,
|
|
997
1017
|
spikeChip,
|
|
998
1018
|
caps,
|
|
999
1019
|
model,
|
package/package.json
CHANGED