claude-code-token-saver

Script cài đặt để dựng bộ "rails" (khung làm việc) cho Claude Code trong bất kỳ repo git nào — giúp tiết kiệm token và làm việc kỷ luật hơn.

Chạy một lần, bạn sẽ có sẵn: CLAUDE.md gọn nhẹ, hooks kiểm soát chất lượng + an toàn, hệ thống dev-docs để không mất ngữ cảnh, các subagent chuyên biệt, và vài slash command tiện dụng.

Cài đặt

Vào thư mục gốc repo bạn muốn gắn rails, rồi chọn 1 trong các cách:

① npx — không cần cài gì (khuyên dùng)

npx claude-code-token-saver

② curl — 1 dòng, không cần Node

curl -fsSL https://raw.githubusercontent.com/NgTrgGiang/claude-code-token-saver/main/setup-claude-code.sh | bash

③ Chạy trực tiếp file (nếu đã có sẵn script)

bash setup-claude-code.sh

Cả 3 cách đều không ghi đè file đã tồn tại. Toàn bộ nội dung nằm trong .claude/ (+ CLAUDE.md ở gốc). Đây là đồ dùng local, tái tạo được — cần đâu cài đó, nên tool tự thêm chúng vào .gitignore để repo dự án của bạn luôn sạch.

Mọi cách đều cần bash trên máy. Trên Windows: dùng Git Bash / WSL, hoặc cài Git for Windows.

Tùy chọn

| Cờ | Ý nghĩa | |----|---------| | --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ụ:

bash setup-claude-code.sh --force        # dựng lại từ đầu, ghi đè hết
bash setup-claude-code.sh --no-detect    # không tự dò lệnh build/test/lint

Sử dụng

Bước 1 — Cài rails vào dự án của bạn

Lưu ý: chạy trong repo dự án bạn muốn code (ví dụ my-shop, my-api...), không phải trong repo claude-code-token-saver.

cd đường/dẫn/tới/du-an-cua-ban
npx claude-code-token-saver            # hoặc dùng cách curl ở trên

Xong bước này, dự án của bạn sẽ mọc ra CLAUDE.md + thư mục .claude/. Script tự nhận diện dự án là Node / Python / Go / Rust để điền sẵn lệnh build/test/lint.

Bước 2 — Điền CLAUDE.md

Mở CLAUDE.md, viết ngắn gọn phần Architecture (code nằm đâu), Conventions (quy ước riêng), và lệnh dev/run. Đây là phần Claude đọc mỗi lượt nên giữ thật gọn.

Bước 3 — Không cần commit gì

Tool đã tự thêm .claude/ và CLAUDE.md vào .gitignore, nên repo dự án của bạn vẫn sạch. Cần dùng ở máy/dự án khác thì chạy lại installer là có ngay — không phải commit hay chia sẻ gì cả.

Bước 4 — Làm việc trong Claude Code

Mở Claude Code ngay trong thư mục dự án đó. Từ giờ bạn có sẵn các slash command và làm theo vòng lặp:

/plan   →   /clear   →   code   →   /verify   →   /save

1. /plan <ý tưởng> — Claude phỏng vấn bạn rồi viết spec vào .claude/dev-docs/SPEC.md trước khi code.
2. /clear — xoá ngữ cảnh cho nhẹ (spec đã nằm trên đĩa, không mất gì).
3. Code — để Claude làm theo spec. Việc điều tra nặng nó tự đẩy sang subagent explorer.
4. /verify — subagent verifier độc lập chạy test/build/lint, soi diff, báo PASS/FAIL.
5. /save — lưu tiến độ vào .claude/dev-docs/ để phiên sau resume không mất ngữ cảnh.

Trong lúc đó các hook tự chạy ngầm: chặn lệnh nguy hiểm, tự format file, không cho Claude đọc .env. Chạy /hooks trong Claude Code để xác nhận hook đã đăng ký.

Nó tạo ra những gì

| Đường dẫn | Công dụng | |-----------|-----------| | CLAUDE.md | Bộ nhớ dự án gọn (< ~200 dòng): commands, kiến trúc, quy ước, gotchas, workflow | | .claude/settings.json | Hooks + danh sách chặn quyền (chặn đọc .env, secrets/) + status line | | .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 | | .claude/dev-docs/ | Lưu trạng thái task ngoài hội thoại, sống sót qua /clear và compaction |

Script tự nhận diện stack (Node/TS, Python, Go, Rust) và điền sẵn lệnh build/test/lint tương ứng.

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:

npx claude-code-token-saver --no-usage

Các slash command

| Lệnh | Tác dụng | |------|----------| | /plan <ý tưởng> | Phỏng vấn bạn kỹ lưỡng rồi viết spec vào .claude/dev-docs/SPEC.md trước khi code | | /save | Ghi trạng thái task vào dev-docs để phiên mới resume không mất ngữ cảnh | | /verify | Giao thay đổi hiện tại cho subagent verifier kiểm chứng độc lập | | /wrap | Post-mortem bug: giải thích nguyên nhân gốc, xác nhận fix, thêm rule vào ## Gotchas |

Vì sao "token-saver"?

• Delegate cho subagent — việc điều tra/đọc code nặng nề đẩy sang explorer (chạy haiku), giữ context chính sạch.
• Dev-docs — trạng thái task nằm trên đĩa, nên /clear thoải mái mà không mất công việc đang dở.
• CLAUDE.md gọn — mỗi dòng đều được nạp mỗi lượt, nên chỉ giữ thứ thật sự cần.

Lưu ý an toàn

⚠️ Hooks chạy lệnh shell thật. Hãy đọc kỹ hai script trong .claude/hooks/ trước khi tin dùng trên repo nhạy cảm.

Yêu cầu

• bash
• 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)