@say8425/cc-statusline 1.3.0 → 1.4.0

package/README.md

@@ -1,5 +1,7 @@
 # cc-statusline
 
+English | [한국어](docs/README.ko.md) | [日本語](docs/README.ja.md) | [中文](docs/README.zh.md) | [Español](docs/README.es.md)
+
 Custom statusline for Claude Code.
 
 [![Claude Code](https://img.shields.io/badge/Claude_Code-D97757?style=flat&logo=claude&logoColor=white)](https://code.claude.com/docs/en/statusline)
@@ -7,29 +9,128 @@ Custom statusline for Claude Code.
 [![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?style=flat&logo=typescript&logoColor=white)](https://www.typescriptlang.org)
 [![Bun](https://img.shields.io/badge/Bun-black?style=flat&logo=bun)](https://bun.sh)
 
-## Preview
+## Installation
+
+Add the following to `~/.claude/settings.json`:
+
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "bunx @say8425/cc-statusline",
+    "padding": 0
+  }
+}
+```
+
+## CLI Options
+
+| Option | Description | Default |
+|--------|-------------|:-------:|
+| [`--plan <plan>`](#plan-selection) | Set token limit for your subscription (pro, max5x, max20x) | `pro` |
+| [`--no-usage`](#disable) | Hide usage metrics line | - |
+
+## Screenshots
+
+### Git diff only
+
+![scenario1_diff_only](docs/scenario1_diff_only.png)
+
+### PR only
+
+![scenario2_pr_only](docs/scenario2_pr_only.png)
+
+### Git diff + PR
+
+![scenario3_diff_pr](docs/scenario3_diff_pr.png)
+
+### Context Normal (< 50%)
+
+![Screenshot of status line with normal context usage, under 50%](docs/context_normal.png)
+
+### Context Warning (50-80%)
 
-![preview-1](docs/preview-1.png)
+![Screenshot of status line with warning context usage, between 50% and 80%](docs/context_warning.png)
 
-![preview-2](docs/preview-2.png)
+### Context Critical (> 80%)
+
+![Screenshot of status line with critical context usage, over 80%](docs/context_critical.png)
+
+### Limit Reset Timer
+
+![Screenshot of status line with limit reset timer](docs/limit_reset.png)
 
 ## Features
 
 - **Session Time**: Current session elapsed time
-- **Context %**: Current context window usage (updates immediately)
-- **Session Tokens**: Cumulative token usage
+- **Cost**: Session cost in USD
+- **Context**: Token usage with percentage (color-coded)
+- **Git Diff**: File count, insertions, deletions
 - **PR URL**: Clickable OSC 8 hyperlink
 - **TrueColor**: Dynamic colors based on thresholds
+- **Limit Reset Timer**: Countdown to usage limit reset
+- **Block Usage**: 5-hour block token usage with percentage
+- **Burn Rate**: Token consumption rate per minute
 
-## Installation
+## Emoji Guide
 
-Add the following to `~/.claude/settings.json`:
+| Emoji | Description              |
+| ----- | ------------------------ |
+| 📁    | Project folder name      |
+| 🌿    | Current Git branch       |
+| ⏱️    | Session elapsed time     |
+| 💰    | Session cost in USD      |
+| 🧠    | Context window usage     |
+| ⏳    | Limit reset countdown    |
+| 📊    | 5-hour block token usage |
+| 🔥    | Token burn rate (per min)|
+| ✏️    | Uncommitted changes      |
+| 📎    | Pull request link        |
+
+## Usage Metrics
+
+Shows usage information for the 5-hour billing block.
+
+### How It Works
+
+Automatically parses JSONL files from `~/.claude/projects/` to detect:
+
+1. **Usage limit error messages** - Extracts exact reset time from "Claude AI usage limit reached" errors
+2. **5-hour billing blocks** - Calculates block end time based on latest activity (like [ccusage](https://github.com/ryoppippi/ccusage))
+3. **Token usage** - Sums input and output tokens within the current 5-hour block
+4. **Burn rate** - Calculates average token consumption per minute
+
+No manual configuration required.
+
+### Plan Selection
+
+Different Claude Code plans have different token limits. Use the `--plan` flag to set your plan:
 
 ```json
 {
   "statusLine": {
     "type": "command",
-    "command": "bunx @say8425/cc-statusline",
+    "command": "bunx @say8425/cc-statusline --plan max5x",
+    "padding": 0
+  }
+}
+```
+
+| Plan | Token Limit | Command |
+|------|-------------|---------|
+| Pro (default) | 450K | `--plan pro` or omit |
+| Max 5x | 2.25M | `--plan max5x` |
+| Max 20x | 9M | `--plan max20x` |
+
+### Disable
+
+To hide the usage metrics line (reset timer, block usage, burn rate), use the `--no-usage` flag:
+
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "bunx @say8425/cc-statusline --no-usage",
     "padding": 0
   }
 }
@@ -42,9 +143,10 @@ Add the following to `~/.claude/settings.json`:
 
 ## Color Thresholds
 
-| Metric    | Normal (white) | Warning (yellow) | Critical (red) |
-| --------- | -------------- | ---------------- | -------------- |
-| Context % | < 50%          | 50-80%           | > 80%          |
+| Metric        | Normal (white) | Warning (yellow) | Critical (red) |
+| ------------- | -------------- | ---------------- | -------------- |
+| Context %     | < 50%          | 50-80%           | > 80%          |
+| Block Usage % | < 50%          | 50-80%           | > 80%          |
 
 ## License
 

package/package.json

@@ -1,15 +1,19 @@
 {
   "name": "@say8425/cc-statusline",
-  "version": "1.3.0",
-  "type": "module",
-  "description": "Custom statusline for Claude Code",
+  "version": "1.4.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/say8425/cc-statusline.git"
   },
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.9",
+    "@types/bun": "latest",
+    "typescript": "^5.9.3"
+  },
   "bin": {
     "cc-statusline": "src/index.ts"
   },
+  "description": "Custom statusline for Claude Code",
   "files": [
     "src/index.ts"
   ],
@@ -21,9 +25,8 @@
     "lint": "biome check src/",
     "typecheck": "tsc --noEmit"
   },
-  "devDependencies": {
-    "@biomejs/biome": "^2.3.9",
-    "@types/bun": "latest",
-    "typescript": "^5.9.3"
+  "type": "module",
+  "dependencies": {
+    "ccusage": "^18.0.5"
   }
 }

package/src/index.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env bun
 
 import { $ } from "bun";
+import { loadSessionBlockData } from "ccusage/data-loader";
 
 // 공식 Claude Code JSON input 타입 정의
 interface ClaudeStatusInput {
@@ -23,11 +24,22 @@ interface ClaudeStatusInput {
 	};
 }
 
+// 블록 사용량 정보 타입
+interface BlockUsageInfo {
+	resetTime: Date | null;
+	blockTokens: number;
+	blockStartTime: number | null;
+}
+
 // 캐시 구조
 const cache = {
 	branch: { value: "", timestamp: 0 },
 	gitChanges: { files: 0, insertions: 0, deletions: 0, timestamp: 0 },
 	prUrl: { value: null as string | null, timestamp: 0 },
+	blockUsage: {
+		value: null as BlockUsageInfo | null,
+		timestamp: 0,
+	},
 };
 
 // 캐시 TTL (ms)
@@ -35,8 +47,20 @@ const CACHE_TTL = {
 	branch: 5000, // 5초
 	gitChanges: 3000, // 3초
 	prUrl: 30000, // 30초
+	blockUsage: 60000, // 60초 (JSONL 파싱은 비용이 크므로 긴 TTL)
 };
 
+// Plan별 5시간 토큰 한도
+const PLAN_LIMITS = {
+	pro: 450_000, // Pro plan
+	max5x: 2_250_000, // Max 5x (450K * 5)
+	max20x: 9_000_000, // Max 20x (450K * 20)
+} as const;
+
+type Plan = keyof typeof PLAN_LIMITS;
+
+const DEFAULT_PLAN: Plan = "pro";
+
 // TrueColor 색상 정의
 const C = {
 	RESET: "\x1b[0m",
@@ -50,8 +74,8 @@ const C = {
 	UNDERLINE: "\x1b[4m",
 };
 
-// Context 사용률에 따른 색상
-function getContextColor(pct: number): string {
+// 사용률에 따른 색상 (Context 및 Block Usage 공통)
+function getUsageColor(pct: number): string {
 	if (pct < 50) return C.WHITE;
 	if (pct < 80) return C.YELLOW;
 	return C.RED;
@@ -138,6 +162,114 @@ async function getPrUrlCached(): Promise<string | null> {
 	}
 }
 
+// CLI 인자 파싱
+const args = process.argv.slice(2);
+const noUsage = args.includes("--no-usage");
+
+// --plan 옵션 파싱 (예: --plan max5x)
+const planIndex = args.indexOf("--plan");
+const planArg =
+	planIndex !== -1 && planIndex + 1 < args.length
+		? args[planIndex + 1]
+		: DEFAULT_PLAN;
+const BLOCK_TOKEN_LIMIT =
+	PLAN_LIMITS[planArg as Plan] ?? PLAN_LIMITS[DEFAULT_PLAN];
+
+// ccusage를 사용하여 블록 사용량 정보 추출
+async function getBlockUsageFromCcusage(): Promise<BlockUsageInfo> {
+	const result: BlockUsageInfo = {
+		resetTime: null,
+		blockTokens: 0,
+		blockStartTime: null,
+	};
+
+	try {
+		const blocks = await loadSessionBlockData({
+			sessionDurationHours: 5,
+			offline: true,
+			order: "desc",
+		});
+
+		if (blocks.length === 0) return result;
+
+		// 가장 최근의 활성 블록 찾기 (갭 블록 제외)
+		const activeBlock = blocks.find((b) => !b.isGap);
+		if (!activeBlock) return result;
+
+		// 블록 토큰 합산 (input + output만, 캐시 토큰 제외)
+		const { tokenCounts } = activeBlock;
+		result.blockTokens = tokenCounts.inputTokens + tokenCounts.outputTokens;
+
+		result.blockStartTime = activeBlock.startTime.getTime();
+
+		// 리셋 시간 설정 (ccusage가 제공하는 usageLimitResetTime 또는 블록 종료 시간)
+		if (
+			activeBlock.usageLimitResetTime &&
+			activeBlock.usageLimitResetTime > new Date()
+		) {
+			result.resetTime = activeBlock.usageLimitResetTime;
+		} else if (activeBlock.endTime > new Date()) {
+			result.resetTime = activeBlock.endTime;
+		}
+
+		return result;
+	} catch {
+		return result;
+	}
+}
+
+// 블록 사용량 가져오기 (캐싱)
+async function getBlockUsageCached(): Promise<BlockUsageInfo | null> {
+	if (Date.now() - cache.blockUsage.timestamp < CACHE_TTL.blockUsage) {
+		return cache.blockUsage.value;
+	}
+
+	const blockUsage = await getBlockUsageFromCcusage();
+	cache.blockUsage = { value: blockUsage, timestamp: Date.now() };
+	return blockUsage;
+}
+
+// 리셋까지 남은 시간 계산
+function getTimeUntilReset(resetTime: Date): {
+	hours: number;
+	minutes: number;
+} {
+	const now = new Date();
+	const diff = resetTime.getTime() - now.getTime();
+
+	if (diff <= 0) {
+		return { hours: 0, minutes: 0 };
+	}
+
+	const hours = Math.floor(diff / (1000 * 60 * 60));
+	const minutes = Math.floor((diff % (1000 * 60 * 60)) / (1000 * 60));
+
+	return { hours, minutes };
+}
+
+// 토큰 수를 K 단위로 포맷팅
+function formatTokensK(tokens: number): string {
+	if (tokens >= 1000) {
+		return `${Math.round(tokens / 1000)}K`;
+	}
+	return tokens.toString();
+}
+
+// 분당 번레이트 계산 (tokens/min)
+function calculateBurnRate(
+	blockTokens: number,
+	blockStartTime: number | null,
+): number {
+	if (!blockStartTime || blockTokens === 0) return 0;
+
+	const now = Date.now();
+	const elapsedMinutes = (now - blockStartTime) / (1000 * 60);
+
+	if (elapsedMinutes < 1) return 0; // 1분 미만에는 변동성이 큰 값을 표시하지 않음
+
+	return Math.round(blockTokens / elapsedMinutes);
+}
+
 // 메인 함수
 async function main() {
 	// 1. stdin에서 Claude Code JSON 읽기
@@ -167,13 +299,14 @@ async function main() {
 		: 0;
 
 	const contextPct = Math.round((totalTokens / contextSize) * 100);
-	const ctxColor = getContextColor(contextPct);
+	const ctxColor = getUsageColor(contextPct);
 
-	// 6. Git 정보 (캐싱, 병렬 실행)
-	const [branch, gitChanges, prUrl] = await Promise.all([
+	// 6. Git 정보 + 블록 사용량 (캐싱, 병렬 실행)
+	const [branch, gitChanges, prUrl, blockUsage] = await Promise.all([
 		getBranchCached(),
 		getGitChangesCached(),
 		getPrUrlCached(),
+		noUsage ? Promise.resolve(null) : getBlockUsageCached(),
 	]);
 
 	// 7. 출력
@@ -185,31 +318,67 @@ async function main() {
 	console.log(line1);
 
 	// 2번째 줄: 세션 시간 | 비용 | 컨텍스트
-	console.log(
-		`${C.WHITE}⏱️ ${formatTime(sessionHrs, sessionMins)}${C.RESET} | ` +
-			`${C.WHITE}💰 $${costUsd.toFixed(2)}${C.RESET} | ` +
-			`${ctxColor}🧠 ${formatNumber(totalTokens)} (${contextPct}%)${C.RESET}`,
-	);
+	const line2 =
+		`${C.WHITE}⏱️ ${formatTime(sessionHrs, sessionMins)}${C.RESET}` +
+		` | ${C.WHITE}💰 $${costUsd.toFixed(2)}${C.RESET}` +
+		` | ${ctxColor}🧠 ${formatNumber(totalTokens)} (${contextPct}%)${C.RESET}`;
+
+	console.log(line2);
+
+	// 3번째 줄: 리셋 타이머 | 사용량 | 번레이트 (--no-usage가 아닐 때)
+	if (!noUsage && blockUsage) {
+		const parts: string[] = [];
+
+		// 리셋 타이머
+		if (blockUsage.resetTime) {
+			const resetTime = getTimeUntilReset(blockUsage.resetTime);
+			parts.push(
+				`${C.WHITE}⏳ ${formatTime(resetTime.hours, resetTime.minutes)}${C.RESET}`,
+			);
+		}
+
+		// 블록 사용량
+		const usagePct = Math.round(
+			(blockUsage.blockTokens / BLOCK_TOKEN_LIMIT) * 100,
+		);
+		const usageColor = getUsageColor(usagePct);
+		parts.push(
+			`${usageColor}📊 ${formatTokensK(blockUsage.blockTokens)}/${formatTokensK(BLOCK_TOKEN_LIMIT)} (${usagePct}%)${C.RESET}`,
+		);
+
+		// 번레이트
+		const burnRate = calculateBurnRate(
+			blockUsage.blockTokens,
+			blockUsage.blockStartTime,
+		);
+		if (burnRate > 0) {
+			parts.push(`${C.WHITE}🔥 ${formatTokensK(burnRate)}/min${C.RESET}`);
+		}
+
+		if (parts.length > 0) {
+			console.log(parts.join(" | "));
+		}
+	}
 
-	// 3번째 줄: git changes | PR URL
+	// 4번째 줄: git changes | PR URL
 	const hasGitChanges =
 		gitChanges.files > 0 ||
 		gitChanges.insertions > 0 ||
 		gitChanges.deletions > 0;
 	if (hasGitChanges || prUrl) {
-		let line3 = "";
+		let line4 = "";
 		if (hasGitChanges) {
-			line3 += `✏️ ${C.WHITE}${gitChanges.files} files${C.RESET} ${C.GREEN}+${gitChanges.insertions}${C.RESET} ${C.RED}-${gitChanges.deletions}${C.RESET}`;
+			line4 += `✏️ ${C.WHITE}${gitChanges.files} files${C.RESET} ${C.GREEN}+${gitChanges.insertions}${C.RESET} ${C.RED}-${gitChanges.deletions}${C.RESET}`;
 		}
 		if (prUrl) {
 			const prLabel = prUrl
 				.replace("https://github.com/", "")
 				.replace("/pull/", "#");
-			if (line3) line3 += " | ";
+			if (line4) line4 += " | ";
 			// OSC 8 하이퍼링크
-			line3 += `📎 ${C.WHITE}${C.UNDERLINE}\x1b]8;;${prUrl}\x07${prLabel}\x1b]8;;\x07${C.RESET}`;
+			line4 += `📎 ${C.WHITE}${C.UNDERLINE}\x1b]8;;${prUrl}\x07${prLabel}\x1b]8;;\x07${C.RESET}`;
 		}
-		console.log(line3);
+		console.log(line4);
 	}
 }