claude-code-token-saver 0.1.0 → 0.1.3

package/README.md

@@ -38,6 +38,7 @@ Cả 3 cách đều **không ghi đè** file đã tồn tại. Toàn bộ nội
 |----|---------|
 | `--force` | Ghi đè cả những file đã tồn tại (mặc định: bỏ qua) |
 | `--no-detect` | Không tự dò lệnh build/test/lint |
+| `--no-usage` | Không thêm status line theo dõi usage 5 giờ (mặc định là **có**) |
 | `-h`, `--help` | Hiện hướng dẫn |
 
 Ví dụ:
@@ -99,6 +100,7 @@ Trong lúc đó các hook tự chạy ngầm: chặn lệnh nguy hiểm, tự fo
 | `.claude/settings.json` | Hooks + danh sách chặn quyền (chặn đọc `.env`, `secrets/`) — **nên commit** |
 | `.claude/hooks/guard-bash.sh` | Chặn lệnh shell nguy hiểm (`rm -rf /`, fork bomb, `git push --force`, `chmod -R 777`, pipe script từ mạng vào shell) |
 | `.claude/hooks/format-file.sh` | Tự động format file sau khi Claude ghi (prettier / ruff / gofmt / rustfmt) |
+| `.claude/hooks/statusline.js` | Vẽ thanh usage 5 giờ ở đáy phiên (chỉ khi bật usage; xem mục bên dưới) |
 | `.claude/agents/explorer.md` | Subagent điều tra codebase **read-only**, chạy model `haiku` để tiết kiệm token |
 | `.claude/agents/verifier.md` | Subagent kiểm chứng độc lập — chạy test/build/lint, soi diff, báo PASS/FAIL |
 | `.claude/commands/*.md` | Các slash command: `/plan`, `/save`, `/verify`, `/wrap` |
@@ -108,6 +110,30 @@ Script tự nhận diện stack (**Node/TS, Python, Go, Rust**) và điền sẵ
 
 ---
 
+## Theo dõi usage 5 giờ (status line)
+
+Mặc định, tool thêm một **thanh tiến trình usage 5 giờ** vào đáy phiên Claude Code (trong VSCode), kiểu giống hệt widget native của Claude, tự cập nhật:
+
+```
+Current session  ███████████████████░░░░░  80% used
+Resets in 1 hr 5 min
+```
+
+- Thanh amber lấp đầy theo **% usage đã dùng** của khối 5 giờ, kèm thời gian còn lại tới reset.
+- Màu đổi theo mức: xanh < 50%, amber 50–85%, đỏ > 85%.
+
+Con số là **chính xác** — bằng đúng số `/usage` hiển thị. Nó đọc thẳng field `rate_limits.five_hour` mà **Claude Code truyền sẵn vào status line**, nên **không cần công cụ ngoài** (không ccusage, không gọi API).
+
+**Yêu cầu:** Claude Code ≥ 2.1.x, tài khoản **Claude.ai Pro/Max**, và có **`node`** trên máy. Thanh chỉ hiện **sau tin nhắn đầu tiên** của phiên (lúc `rate_limits` mới có); tài khoản API/không phải Pro-Max sẽ không có dữ liệu này → thanh tự ẩn, không lỗi.
+
+Không muốn tính năng này? Cài bằng `--no-usage`:
+
+```bash
+npx claude-code-token-saver --no-usage
+```
+
+---
+
 ## Các slash command
 
 | Lệnh | Tác dụng |
@@ -136,5 +162,6 @@ Script tự nhận diện stack (**Node/TS, Python, Go, Rust**) và điền sẵ
 ## Yêu cầu
 
 - `bash`
-- `python3` (dùng để hooks đọc JSON từ stdin — không cần `jq`)
+- `node` — cần cho cách cài `npx` và cho thanh usage 5 giờ (`statusline.js`)
+- `python3` (dùng để hai hook guard/format đọc JSON từ stdin — không cần `jq`)
 - Tùy chọn: `jq` (dò script trong `package.json` chính xác hơn), và các trình format (`prettier`, `ruff`, `gofmt`, `rustfmt`)

package/bin/cli.js

@@ -42,8 +42,13 @@ function candidateBashes() {
 
 const args = process.argv.slice(2);
 
+// Pass a forward-slash path to bash. On Windows the script path uses
+// backslashes (C:\Users\...), which bash would treat as escape sequences and
+// mangle (C:UsersAdmin...). Git Bash / MSYS accept C:/Users/... just fine.
+const scriptArg = script.replace(/\\/g, "/");
+
 for (const bash of candidateBashes()) {
-  const res = spawnSync(bash, [script, ...args], {
+  const res = spawnSync(bash, [scriptArg, ...args], {
     stdio: "inherit",
     cwd: process.cwd(),
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-token-saver",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "description": "One-shot installer that adds token-saving Claude Code rails (CLAUDE.md, hooks, subagents, slash commands, dev-docs) to any git repo.",
   "bin": {
     "claude-code-token-saver": "bin/cli.js",

package/setup-claude-code.sh

@@ -19,16 +19,21 @@ set -euo pipefail
 # ---------- options ---------------------------------------------------------
 FORCE=0
 SKIP_DETECT=0
+USAGE=1          # add a live 5-hour usage status line (ccusage) by default
 for arg in "$@"; do
   case "$arg" in
     --force)       FORCE=1 ;;
     --no-detect)   SKIP_DETECT=1 ;;
+    --usage)       USAGE=1 ;;
+    --no-usage)    USAGE=0 ;;
     -h|--help)
       cat <<'EOF'
-Usage: bash setup-claude-code.sh [--force] [--no-detect]
+Usage: bash setup-claude-code.sh [--force] [--no-detect] [--no-usage]
 
   --force       Overwrite files that already exist (default: skip them)
   --no-detect   Do not auto-detect build/test/lint commands
+  --no-usage    Do not add the 5-hour usage status line (ccusage)
+  --usage       Add the usage status line (this is the default)
 EOF
       exit 0 ;;
     *) echo "Unknown option: $arg" >&2; exit 1 ;;
@@ -143,10 +148,22 @@ EOF
 # ===========================================================================
 # Quality gate: block `git commit` unless tests pass.
 # Safety gate: block obviously destructive shell commands.
-write_file ".claude/settings.json" <<'EOF'
+# Usage line: a native-style amber bar showing the current 5-hour usage % + reset
+# countdown at the bottom of the Claude Code session. Numbers come straight from
+# rate_limits.five_hour on the statusLine stdin (exact, same as /usage) — no
+# external tool. Rendered by .claude/hooks/statusline.js (below). Off: --no-usage.
+if [[ $USAGE -eq 1 ]]; then
+  STATUSLINE_BLOCK=$'  "statusLine": {\n    "type": "command",\n    "command": "node \\"$CLAUDE_PROJECT_DIR/.claude/hooks/statusline.js\\""\n  },\n'
+else
+  STATUSLINE_BLOCK=""
+fi
+
+# NOTE: unquoted heredoc so ${STATUSLINE_BLOCK} expands. Everything Claude Code
+# must see literally ($schema, $CLAUDE_PROJECT_DIR) is backslash-escaped.
+write_file ".claude/settings.json" <<EOF
 {
-  "$schema": "https://json.schemastore.org/claude-code-settings.json",
-  "permissions": {
+  "\$schema": "https://json.schemastore.org/claude-code-settings.json",
+${STATUSLINE_BLOCK}  "permissions": {
     "deny": [
       "Read(./.env)",
       "Read(./.env.*)",
@@ -160,7 +177,7 @@ write_file ".claude/settings.json" <<'EOF'
         "hooks": [
           {
             "type": "command",
-            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/guard-bash.sh\""
+            "command": "\"\$CLAUDE_PROJECT_DIR/.claude/hooks/guard-bash.sh\""
           }
         ]
       }
@@ -171,7 +188,7 @@ write_file ".claude/settings.json" <<'EOF'
         "hooks": [
           {
             "type": "command",
-            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/format-file.sh\""
+            "command": "\"\$CLAUDE_PROJECT_DIR/.claude/hooks/format-file.sh\""
           }
         ]
       }
@@ -180,6 +197,61 @@ write_file ".claude/settings.json" <<'EOF'
 }
 EOF
 
+# 2c. Usage status line renderer (Node, zero deps). Reads the statusLine JSON on
+# stdin and draws a native-style amber 5-hour usage bar. Numbers come from
+# rate_limits.five_hour (exact, same as /usage) — present for Claude.ai Pro/Max
+# after the first API response; renders nothing otherwise. Only written with --usage.
+if [[ $USAGE -eq 1 ]]; then
+write_file ".claude/hooks/statusline.js" <<'EOF'
+#!/usr/bin/env node
+// Claude Code statusLine renderer: a native-style amber "Current session" bar
+// showing 5-hour usage % + reset countdown. Zero dependencies (Node only).
+// Data is read straight from rate_limits.five_hour on stdin (exact, same as
+// /usage); that field is present for Claude.ai Pro/Max after the first API
+// response. When it is absent, this prints nothing so the footer stays clean.
+"use strict";
+
+let input = "";
+process.stdin.setEncoding("utf8");
+process.stdin.on("data", function (d) { input += d; });
+process.stdin.on("end", function () {
+  let data = {};
+  try { data = JSON.parse(input); } catch (e) { process.exit(0); }
+
+  const rl = data.rate_limits && data.rate_limits.five_hour;
+  if (!rl || rl.used_percentage == null) process.exit(0); // no data yet
+
+  let pct = Number(rl.used_percentage);
+  if (!isFinite(pct)) process.exit(0);
+  pct = Math.max(0, Math.min(100, pct));
+
+  // reset countdown from resets_at (unix epoch seconds)
+  let resetStr = "";
+  if (rl.resets_at) {
+    let secs = Math.floor(Number(rl.resets_at) - Date.now() / 1000);
+    if (secs < 0) secs = 0;
+    const h = Math.floor(secs / 3600);
+    const m = Math.floor((secs % 3600) / 60);
+    resetStr = h > 0 ? h + " hr " + m + " min" : m + " min";
+  }
+
+  // colour by level, mirroring Claude's own coding: green < 50, amber 50-85, red > 85
+  const RESET = "\x1b[0m";
+  const DIM = "\x1b[2m";
+  const fill = pct > 85 ? "\x1b[38;5;203m" : pct >= 50 ? "\x1b[38;5;214m" : "\x1b[38;5;42m";
+  const track = "\x1b[38;5;238m";
+
+  const width = 24;
+  const filled = Math.round((pct / 100) * width);
+  const bar = fill + "█".repeat(filled) + track + "█".repeat(width - filled) + RESET;
+
+  const line1 = "Current session  " + bar + "  " + fill + Math.round(pct) + "% used" + RESET;
+  const line2 = resetStr ? DIM + "Resets in " + resetStr + RESET : "";
+  process.stdout.write(line2 ? line1 + "\n" + line2 : line1);
+});
+EOF
+fi
+
 # 2a. Safety hook — blocks destructive Bash commands (exit 2 = block)
 write_file ".claude/hooks/guard-bash.sh" <<'EOF'
 #!/usr/bin/env bash
@@ -383,3 +455,12 @@ ${c_ylw}Next:${c_reset}
 ${c_dim}Note: hooks run real shell commands. Read the two scripts in
 .claude/hooks/ before trusting them on a sensitive repo.${c_reset}
 EOF
+
+if [[ $USAGE -eq 1 ]]; then
+  echo
+  info "5-hour usage bar added (statusLine → .claude/hooks/statusline.js)."
+  printf "  %sA native-style amber bar showing your 5h usage %% + reset countdown at\n" "$c_dim"
+  printf "  the bottom of the session. Reads exact numbers from Claude Code's\n"
+  printf "  rate_limits (Claude.ai Pro/Max, after the first message; needs node).\n"
+  printf "  Disable with --no-usage.%s\n" "$c_reset"
+fi