Claude Code Status Line: bật, tùy biến và sửa lỗi 2026



Bạn mở Claude Code lên, gõ vài lệnh, rồi tự hỏi: đang chạy model nào, ngốn hết bao nhiêu context rồi? Cái thanh trống trơn dưới đáy terminal chẳng nói gì. Đến lúc Claude tự /compact thì mới ngớ người ra là context đã đầy.

Thanh đó có tên: status line. Bật lên một lần, nó hiện model, % context, chi phí phiên, git branch ngay trước mắt. Bài này hướng dẫn bật, tùy biến và fix lỗi, kèm cả phần Windows mà phần lớn tutorial bỏ qua.

TL;DR: Status line là thanh dưới đáy Claude Code chạy một script bạn cấu hình, đọc dữ liệu phiên dạng JSON qua stdin rồi in ra những gì bạn muốn (model, % context, chi phí, git). Bật bằng lệnh /statusline hoặc thêm khối statusLine vào settings.json. Mất ~5 phút, chạy local, không tốn token API.

Đáng bật nếu: bạn hay quên theo dõi context, chạy nhiều phiên cùng lúc, hoặc muốn git branch luôn hiện. Bỏ qua nếu: bạn chỉ chạy vài lệnh ngắn rồi thoát.

Status line là gì và bật để làm gì?

Trả lời nhanh: một thanh tùy biến ở đáy giao diện Claude Code, chạy script của bạn sau mỗi lượt trả lời và in thông tin phiên ra màn hình. Trong Claude Code gọi là status line. Nó nằm trên các badge mặc định, không thay thế chúng.

Cơ chế rất gọn. Claude Code đẩy một cục dữ liệu JSON (model, thư mục, context, chi phí…) vào script của bạn qua stdin. Script đọc, lấy thứ cần, in ra stdout. Claude Code hiện đúng cái bạn in.

Ví dụ dễ hình dung: như đồng hồ công-tơ-mét trên xe. Bạn không cần mở nắp ca-pô để biết tốc độ, liếc một cái là thấy. Ở đây, bạn không cần gõ /context để biết đã dùng bao nhiêu, status line hiện sẵn.

Lý do số một người ta bật cái này: theo dõi % context. Khi context gần đầy, Claude sẽ tự nén lại (/compact) và bạn dễ mất mạch. Một thanh hiện 72% context màu vàng nhắc bạn chủ động trước. Đây cũng là lý do nó nối thẳng với chuyện tiết kiệm token trong Claude Code.

Một điểm hay: status line chạy local, không tốn token API. Nó chỉ chạy script trên máy bạn, không gọi lên Anthropic. (Nguồn: tài liệu chính thức Claude Code, truy cập 30/06/2026.)

Trước khi bắt đầu cần gì?

Cần ba thứ: Claude Code CLI bản gần đây, một terminal, và (nếu viết script bash) công cụ jq để đọc JSON. Git là tùy chọn, chỉ cần nếu bạn muốn hiện branch. Không cần cài service nền hay plugin gì thêm.

• Claude Code CLI: lệnh /statusline có sẵn trong các bản Claude Code gần đây (gõ claude --version để kiểm tra bản bạn đang dùng).
• jq: trình đọc JSON dòng lệnh. Trên macOS: brew install jq. Trên Windows: winget install jqlang.jq. Script Python hay Node thì không cần jq vì đã có sẵn parser JSON.
• Terminal hỗ trợ màu: gần như mọi terminal hiện đại đều OK. Riêng link click được thì cần loại hỗ trợ OSC 8 (iTerm2, Kitty, WezTerm).

Status line là một mục trong settings.json. Nếu bạn chưa quen file này, đọc trước bài cấu hình Claude Code: thư mục .claude & settings.json để nắm tổng thể, rồi quay lại đây.

Bước 1: Bật nhanh bằng lệnh /statusline

Cách nhanh nhất là để Claude tự dựng. Gõ /statusline kèm mô tả bằng lời những gì bạn muốn hiện. Claude Code sinh sẵn một script trong thư mục ~/.claude/ và tự cập nhật settings.json cho bạn. Không cần đụng tay vào file nào.

Ví dụ, gõ trong Claude Code:

/statusline hiện tên model và % context kèm thanh tiến trình

Claude sẽ tạo script, trỏ settings.json tới nó, và thanh xuất hiện ngay lần tương tác kế tiếp. Muốn đổi, gõ lại /statusline với mô tả mới. Muốn tắt, gõ /statusline delete (hoặc clear, remove).

Cách này hợp khi bạn muốn có kết quả trong 30 giây. Nhưng để hiểu cái script đang làm gì và sửa sâu, nên xem Bước 2.

Bước 2: Tự viết script và khai báo trong settings.json

Bật thủ công gồm hai phần: một script đọc JSON rồi in ra, và một khối statusLine trong settings.json trỏ tới script đó. Khối này đặt ở settings cấp user (~/.claude/settings.json) hoặc cấp project. Đây là cách cho bạn toàn quyền kiểm soát.

Khối statusLine đầy đủ trông như sau:

{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh",
    "padding": 2,
    "refreshInterval": 5,
    "hideVimModeIndicator": false
  }
}

Giải thích từng field (các field ngoài type và command đều tùy chọn):

• type: luôn là "command" (chạy một lệnh shell).
• command: đường dẫn script, hoặc một lệnh inline. Có thể dùng jq ngay trong đây mà không cần file riêng.
• padding: thêm khoảng trống ngang, tính theo ký tự. Mặc định 0.
• refreshInterval: chạy lại script mỗi N giây (tối thiểu 1). Để khi nào? Khi thanh hiện dữ liệu theo thời gian như đồng hồ, hoặc khi sub-agent nền đổi git state lúc phiên chính đang rảnh. Không cần thì bỏ trống.
• hideVimModeIndicator: ẩn dòng -- INSERT -- mặc định, dùng khi script của bạn tự vẽ vim mode.

Nếu lười tạo file, bạn nhét luôn lệnh jq vào command:

{
  "statusLine": {
    "type": "command",
    "command": "jq -r '\"[\\(.model.display_name)] \\(.context_window.used_percentage // 0)% context\"'"
  }
}

Còn muốn một script riêng cho dễ sửa, lưu file ~/.claude/statusline.sh:

#!/bin/bash
input=$(cat)                                              # đọc JSON từ stdin
MODEL=$(echo "$input" | jq -r '.model.display_name')
DIR=$(echo "$input" | jq -r '.workspace.current_dir')
PCT=$(echo "$input" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1)
echo "[$MODEL] 📁 ${DIR##*/} | ${PCT}% context"

Nhớ cấp quyền chạy: chmod +x ~/.claude/statusline.sh. Đoạn // 0 trong jq là giá trị dự phòng khi field bị null (lúc chưa có lượt API nào). ${DIR##*/} lấy tên thư mục cuối, bỏ đường dẫn dài.

Status line nhận được dữ liệu gì?

Claude Code gửi một object JSON qua stdin chứa toàn bộ trạng thái phiên. Hiểu được object này là chìa khóa để bạn hiện đúng thứ mình cần. Dưới đây là các nhóm field hay dùng nhất (nguồn: tài liệu chính thức Claude Code, truy cập 30/06/2026).

Nhóm	Field	Ý nghĩa
Model	model.id, model.display_name	Định danh + tên hiển thị model đang chạy (vd claude-opus-4-8 / Opus)
Thư mục	cwd, workspace.current_dir	Thư mục làm việc hiện tại (hai field cùng giá trị)
	workspace.project_dir	Thư mục lúc khởi động phiên
	workspace.repo.owner, .name, .host	Repo đọc từ remote origin (vd anthropics/claude-code)
Context	context_window.used_percentage	% context đã dùng (đã tính sẵn)
	context_window.remaining_percentage	% còn lại
	context_window.context_window_size	Tổng size (200000, hoặc 1000000 cho model context mở rộng)
	exceeds_200k_tokens	Token vượt mốc 200k hay chưa (true/false)
Chi phí	cost.total_cost_usd	Chi phí phiên ước tính (tính phía client)
	cost.total_duration_ms	Tổng thời gian phiên (mili-giây)
	cost.total_lines_added, .total_lines_removed	Số dòng code đã thêm/xóa
Phiên	session_id, transcript_path, version	ID phiên, đường dẫn transcript, version Claude Code
	output_style.name	Tên output style đang dùng
	effort.level	Mức reasoning (low/medium/high/xhigh/max)
Rate limit	rate_limits.five_hour.used_percentage	% hạn mức 5 giờ (chỉ có với tài khoản Pro/Max)
	rate_limits.seven_day.used_percentage	% hạn mức 7 ngày
Khác	vim.mode, agent.name, pr.number, worktree.*	Vim mode, tên agent, PR đang mở, worktree

Hai lưu ý dễ vấp:

1. used_percentage chỉ tính token input (input + cache đọc + cache ghi), không gồm output. Nếu bạn tự tính % từ current_usage, dùng đúng công thức input-only này cho khớp.
2. current_usage bằng null trước lượt API đầu tiên, và ngay sau /compact cho tới lượt kế tiếp. Luôn có giá trị dự phòng (// 0 trong jq) kẻo thanh hiện --.

Khi nào status line cập nhật? Sau mỗi lượt trả lời của Claude, sau /compact, khi đổi permission mode, hoặc khi bật/tắt vim. Các lần này được gộp (debounce) trong 300ms để khỏi nhấp nháy (Tài liệu chính thức Claude Code, truy cập 01/07/2026).

Bước 3: Vài script đáng chép ngay

Phần này gom bốn script thực dụng nhất, mỗi cái giải quyết một nhu cầu cụ thể: theo dõi context, chi phí, git, và gộp tất cả vào nhiều dòng. Chép vào ~/.claude/statusline.sh, chmod +x, trỏ settings.json tới là chạy.

Thanh % context đổi màu (xanh dưới 70%, vàng 70-89%, đỏ từ 90%):

#!/bin/bash
input=$(cat)
MODEL=$(echo "$input" | jq -r '.model.display_name')
PCT=$(echo "$input" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1)

if   [ "$PCT" -ge 90 ]; then COLOR='\033[31m'   # đỏ
elif [ "$PCT" -ge 70 ]; then COLOR='\033[33m'   # vàng
else COLOR='\033[32m'; fi                        # xanh
RESET='\033[0m'

FILLED=$((PCT / 10)); EMPTY=$((10 - FILLED))
printf -v FILL "%${FILLED}s"; printf -v PAD "%${EMPTY}s"
BAR="${FILL// /█}${PAD// /░}"
echo -e "[$MODEL] ${COLOR}${BAR}${RESET} ${PCT}%"

Chi phí và thời lượng phiên: lấy cost.total_cost_usd và cost.total_duration_ms, đổi mili-giây ra phút giây.

input=$(cat)
COST=$(echo "$input" | jq -r '.cost.total_cost_usd // 0')
MS=$(echo "$input" | jq -r '.cost.total_duration_ms // 0')
printf '💰 $%.2f | ⏱️ %dm %ds\n' "$COST" $((MS/60000)) $(((MS%60000)/1000))

Git branch: thêm một đoạn kiểm tra repo rồi gọi git branch --show-current. Lưu ý: lệnh git có thể chậm trong repo lớn. Nếu thấy giật, hãy cache kết quả vào file tạm theo session_id (đừng dùng $$ hay pid vì chúng đổi mỗi lần chạy, làm cache vô dụng).

Nhiều dòng: mỗi lệnh echo là một dòng riêng. Bạn để dòng một hiện model + thư mục + branch, dòng hai hiện thanh context + chi phí. Status line nhiều dòng đẹp nhưng dễ lỗi hiển thị hơn, nên test kỹ.

Mẹo nhỏ từ thực tế: giữ output ngắn. Thanh trạng thái hẹp, in dài sẽ bị cắt hoặc xuống dòng xấu. Mình thường chỉ để model + thanh % context + branch là đủ liếc.

Cấu hình trên Windows (Git Bash & PowerShell)

Đây là phần gần như mọi tutorial bỏ quên, mà lại là chỗ dân Windows hay vấp nhất. Trên Windows, Claude Code chạy lệnh status line qua Git Bash nếu có cài, không thì qua PowerShell. Hiểu đúng điều này tránh được lỗi “thanh không hiện mà chẳng báo gì”.

Gotcha số một: đường dẫn backslash. Git Bash coi dấu \ không trong ngoặc là ký tự escape. Một đường dẫn kiểu C:\Users\ban\script.ps1 khi tới script runner sẽ bị nuốt mất dấu phân tách và lệnh thất bại lặng lẽ. Cách sửa: viết đường dẫn trong command bằng forward slash /. Dấu ~ cũng chạy, trỏ về thư mục home Windows.

Mình chạy Claude Code trên Windows, và lần đầu cấu hình đúng dính đúng lỗi này: copy nguyên đường dẫn từ Explorer (có backslash) dán vào command, thanh im lìm. Đổi sang forward slash là chạy.

Để chạy script PowerShell làm status line, gọi qua powershell:

{
  "statusLine": {
    "type": "command",
    "command": "powershell -NoProfile -File C:/Users/ban/.claude/statusline.ps1"
  }
}

Và file statusline.ps1 đọc JSON từ stdin như sau:

$input_json = $input | Out-String | ConvertFrom-Json
$cwd   = $input_json.cwd
$model = $input_json.model.display_name
$used  = $input_json.context_window.used_percentage
$dirname = Split-Path $cwd -Leaf

if ($used) {
    Write-Host "$dirname [$model] ctx: $used%"
} else {
    Write-Host "$dirname [$model]"
}

Nếu có cài Git Bash, bạn vẫn chạy thẳng script .sh được như trên macOS/Linux, chỉ cần nhớ quy tắc forward slash trong đường dẫn.

Kiểm tra kết quả và sửa lỗi thường gặp

Trước khi tin vào thanh, hãy test script độc lập bằng dữ liệu JSON giả. Cách này tách bạch lỗi script với lỗi cấu hình, tiết kiệm cả buổi mò mẫm. Chạy:

echo '{"model":{"display_name":"Opus"},"workspace":{"current_dir":"/home/ban/duan"},"context_window":{"used_percentage":25},"session_id":"test"}' | ./statusline.sh

Nếu nó in ra dòng đẹp, script ổn. Còn vào Claude Code mà thanh không hiện, soi theo danh sách dưới (nguồn: tài liệu chính thức, truy cập 30/06/2026):

• Chưa cấp quyền chạy: chạy chmod +x ~/.claude/statusline.sh.
• In ra stderr thay vì stdout: Claude chỉ đọc stdout. Kiểm tra script không lỡ in lỗi ra stderr.
• disableAllHooks: true: cờ này trong settings tắt luôn cả status line. Bỏ đi hoặc đặt false.
• Chưa chấp nhận workspace trust: vì status line chạy lệnh shell, nó cần cùng mức tin cậy như hooks. Chưa accept thì bạn thấy thông báo statusline skipped · restart to fix. Khởi động lại Claude Code và đồng ý hộp trust.
• Windows nuốt backslash: xem lại phần Windows ở trên, dùng forward slash.
• Bí quá thì bật debug: chạy claude --debug để xem exit code và stderr của lần chạy status line đầu tiên.

Sai lầm hay mắc

• Quên // 0 cho field có thể null → thanh hiện -- ở những lượt đầu. Luôn thêm giá trị dự phòng.
• Copy đường dẫn Windows có backslash → script chết lặng. Forward slash mọi lúc.
• Viết script git nặng không cache → thanh giật trong repo lớn. Cache theo session_id.
• Quên chmod +x → script không chạy được, thanh trống.
• Nhầm context giữa status line và /context → số có thể lệch chút do thời điểm tính khác nhau. Dùng used_percentage cho trạng thái đơn giản, chính xác.

Đi xa hơn: ccstatusline, ccusage & công cụ dựng sẵn nào?

Nếu không muốn tự viết, có sẵn vài công cụ cộng đồng. Nhưng hệ sinh thái này thay đổi nhanh (vài tuần lại có tool mới), nên mình nói trước: học cái JSON contract ở trên là thứ bền nhất, tool chỉ là lớp tiện lợi phía trên. Dưới đây là ảnh chụp tại 30/06/2026.

• ccstatusline (sirmalloc): công cụ phổ biến nhất, hỗ trợ powerline, theme, nhiều tùy chọn. Chọn nếu bạn muốn đẹp và nhiều preset mà khỏi code.
• ccusage: chuyên hiển thị usage và chi phí thời gian thực, gọn. Chọn nếu ưu tiên theo dõi chi tiêu.
• CCometixLine: viết bằng Rust, có Git + usage + giao diện TUI để chỉnh. Chọn nếu thích binary nhanh và cấu hình bằng menu.
• Tự viết script: chọn nếu bạn muốn kiểm soát từng ký tự, không thêm phụ thuộc, và hiểu rõ thanh của mình làm gì.

Lời khuyên thẳng: người mới nên thử ccstatusline trước cho nhanh. Dev thích gọn nhẹ và chủ động thì 10 dòng bash tự viết là đủ, lại không lệ thuộc tool bên thứ ba.

Một mục liên quan: subagentStatusLine. Đây là setting riêng để tùy biến từng dòng sub-agent trong panel hiện dưới prompt, thay cho định dạng tên · mô tả · token mặc định. Hữu ích khi bạn chạy nhiều sub-agent và muốn panel gọn theo ý.

FAQ

Status line có tốn token API không?
Không. Nó chạy local trên máy bạn, chỉ gọi script và đọc JSON đã có sẵn, không gửi request nào lên Anthropic. Bạn có thể để nó cập nhật liên tục mà không lo tốn tiền API.

Khác gì lệnh /context?
/context là ảnh chụp bạn gõ khi cần, in chi tiết một lần. Status line hiện liên tục, gọn, tự cập nhật sau mỗi lượt. Số % giữa hai cái có thể lệch nhẹ do thời điểm tính khác nhau, nên dùng status line để liếc nhanh, /context khi cần soi kỹ.

refreshInterval để làm gì?
Mặc định status line chỉ chạy lại khi có sự kiện (Claude trả lời, /compact, đổi mode). Nếu thanh hiện dữ liệu theo thời gian như đồng hồ, hoặc sub-agent nền đổi git state lúc phiên chính rảnh, đặt refreshInterval (giây, tối thiểu 1) để chạy lại đều theo nhịp.

Bật cho một project hay toàn máy?
Cả hai đều được. Để statusLine trong ~/.claude/settings.json thì áp cho mọi project. Để trong settings cấp project thì chỉ riêng project đó, và nó đè lên cấu hình cấp user. Xem thứ tự ưu tiên ở bài cấu hình Claude Code.

Status line khác output style chỗ nào?
Hai thứ khác hẳn. Status line là thanh trạng thái dưới đáy, do script của bạn vẽ, hiện metadata phiên. Output style là cách Claude định dạng nội dung trả lời (giọng, độ dài, cấu trúc). Một cái là đồng hồ trên xe, cái kia là cách tài xế nói chuyện.

Kết luận

Status line là một trong những tùy biến đáng giá nhất mà tốn ít công nhất trong Claude Code. Bật bằng /statusline cho nhanh, hoặc tự viết script trỏ qua settings.json để kiểm soát hoàn toàn. Khi đã quen cái JSON contract, bạn muốn hiện gì cũng được: % context để khỏi bị /compact bất ngờ, chi phí, git, hay cả ba cùng lúc.

Nếu bạn dùng Windows, nhớ một câu thôi: forward slash trong đường dẫn. Đó là cái bẫy hay gặp nhất.

Status line chỉ là một mục nhỏ trong bức tranh settings.json. Muốn nắm trọn cách cấu hình Claude Code (permissions, hooks, env, model), đọc bài pillar cấu hình Claude Code: thư mục .claude & settings.json từ A đến Z. Và nếu lý do bạn bật thanh này là để canh context, ghép luôn với cách tiết kiệm token trong Claude Code cho trọn bộ.