Statusline Claude Code: cấu hình dòng trạng thái để tăng năng suất (2026)

Tác giả: Jasmine, dev dùng Claude Code hằng ngày trên Windows.

Statusline Claude Code là gì?

Statusline Claude Code là một thanh chữ tuỳ biến hiện ở đáy mỗi phiên Claude Code, do một shell script bạn tự cấu hình sinh ra. Mỗi lần trạng thái phiên thay đổi, Claude Code gọi script đó, đẩy toàn bộ dữ liệu phiên dưới dạng JSON qua stdin, và in lại những gì script trả về stdout thành dòng trạng thái. Nói cách khác, bạn nhận một cục JSON, tự chọn lấy field nào cần, format ra sao, rồi in ra - Claude Code chỉ hiển thị hộ.

Điểm quan trọng cần nhớ ngay: statusline chạy local trên máy bạn, không gọi API và không tốn token. Nó không phải một tính năng "AI" - chỉ là một script bash/PowerShell/Python đọc stdin. Vì thế bạn hiện bao nhiêu thông tin cũng được, không ảnh hưởng đến chi phí phiên. Claude Code chỉ chạy lại script khi có sự kiện (đổi model, chạy tool, cập nhật context…) và có debounce nhẹ để không gọi liên tục - nên script hơi nặng một chút vẫn ổn, miễn đừng lạm dụng (xem mục hiệu năng bên dưới).

Khác với thanh trạng thái mặc định (chỉ hiện thư mục làm việc), statusline tuỳ biến cho bạn kéo về đúng thứ mình quan tâm khi code. Nếu bạn mới bắt đầu, hãy đọc trước bài Claude Code là gì và dùng để làm gì để nắm bối cảnh, rồi quay lại đây cấu hình.

Nên hiện gì trên statusline để tăng năng suất?

Đừng nhồi mọi field vào statusline. Một dòng ngắn, đọc lướt trong nửa giây mà vẫn ra quyết định được mới là dòng tốt. Sau vài tháng dùng thật, đây là những thứ mình thấy đáng hiện nhất:

• Phần trăm context còn lại - quan trọng số một. Thấy context tụt về vùng nguy hiểm là bạn chủ động /compact hoặc tách việc, thay vì bị Claude Code nén hội thoại bất ngờ giữa lúc đang làm.
• Model đang dùng - biết mình đang ở Opus hay Sonnet để không "dùng dao mổ trâu giết gà" (hoặc ngược lại). Rất dễ quên mình vừa đổi model.
• Chi phí phiên - con số USD cộng dồn giúp bạn cảm nhận được việc nào đang đốt tiền, đặc biệt khi chạy theo API token.
• Git branch + số file staged/modified - tránh commit nhầm nhánh, biết mình còn bao nhiêu thay đổi chưa lưu.
• Rate limit 5 giờ / 7 ngày (gói Pro/Max) - thấy hạn mức sắp cạn để không bị cụt giữa một tác vụ dài.
• Thư mục / worktree - hữu ích khi bạn mở nhiều worktree song song.

Nguyên tắc của mình: dòng 1 luôn có model + context %, còn cost/git/rate limit thì thêm dần khi thực sự cần. Muốn xem thêm các lệnh hay dùng, tham khảo Claude Code cheat sheet.

Cách nhanh nhất: lệnh /statusline

Nếu bạn không muốn động vào file cấu hình, cách nhanh nhất là gõ tự nhiên ngay trong phiên Claude Code. Nhập lệnh /statusline kèm mô tả bằng tiếng Anh những gì bạn muốn hiện:

/statusline show model name and context percentage with a progress bar

Claude Code sẽ tự viết script, lưu vào thư mục ~/.claude/ và tự thêm khối cấu hình vào settings.json giúp bạn. Vì bước này sinh file mới và sửa cấu hình, Claude Code sẽ hỏi bạn duyệt trước khi ghi - cứ đọc qua rồi chấp nhận. Sau khi xong, statusline hiện ngay ở lần tương tác kế tiếp.

Đây là cách tốt nhất để có bản nháp nhanh, rồi bạn mở file script ra chỉnh tay theo ý mình. Nếu muốn hiểu rõ nút bấm và luồng làm việc cơ bản trước, xem hướng dẫn Claude Code cho người mới.

Cấu hình thủ công qua settings.json (từng bước)

Muốn kiểm soát hoàn toàn thì cấu hình tay. Chỉ 3 bước.

Bước 1 - Tạo script ~/.claude/statusline.sh đọc JSON từ stdin, dùng jq lấy field cần rồi in ra một dòng:

#!/bin/bash
input=$(cat)
model=$(echo "$input" | jq -r '.model.display_name // "?"')
dir=$(echo "$input" | jq -r '.workspace.current_dir // "."' | xargs basename)
pct=$(echo "$input" | jq -r '.context_window.used_percentage // 0')
printf "[%s] 📁 %s | %s%% context" "$model" "$dir" "$pct"

Bước 2 - Cấp quyền chạy:

chmod +x ~/.claude/statusline.sh

⚠️ Lỗi phổ biến nhất: quên chmod +x → statusline không hiện gì cả và không báo lỗi rõ ràng. Nếu dòng trạng thái "im lặng", kiểm tra quyền thực thi trước tiên.

Bước 3 - Khai báo trong ~/.claude/settings.json:

{
 "statusLine": {
 "type": "command",
 "command": "~/.claude/statusline.sh",
 "padding": 0
 }
}

Claude Code tự nạp lại ở lần tương tác kế tiếp, không cần khởi động lại. Một vài tuỳ chọn hữu ích: padding căn lề trái (đặt 0 để dòng sát mép), refreshInterval (mili-giây) buộc chạy lại theo thời gian cho dữ liệu như đồng hồ/rate limit. Với script cực ngắn bạn thậm chí có thể nhét thẳng lệnh jq -r vào field command mà không cần file rời - nhưng tách file dễ bảo trì hơn nhiều.

Bảng dữ liệu JSON - statusline nhận được gì

Mỗi lần chạy, script nhận một object JSON đầy đủ qua stdin. Đây là bản tra cứu tiếng Việt các field hay dùng (nguồn: docs chính thức code.claude.com/docs/en/statusline, truy cập 08/2026):

Lưu ý quan trọng: nhiều field có thể vắng hoặc null, đặc biệt trước khi có API response đầu tiên. Luôn dùng fallback trong jq: // 0 cho số, // "empty" hoặc // "" cho chuỗi. Một số field mới yêu cầu Claude Code đủ mới; đừng khẳng định field không tồn tại nếu bạn chưa test trên bản đang chạy.

Script mẫu copy-paste (chọn cái bạn cần)

Các preset dưới đây dùng bash + jq. Nếu viết bằng Python hoặc Node, bạn có JSON parse sẵn nên còn gọn hơn.

1) Context bar - thanh tiến trình + %:

#!/bin/bash
input=$(cat)
pct=$(echo "$input" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1)
filled=$((pct / 10)); empty=$((10 - filled))
bar=$(printf '▓%.0s' $(seq 1 $filled))$(printf '░%.0s' $(seq 1 $empty))
printf "%s %s%%" "$bar" "$pct"

2) Git màu - nhánh + file staged (xanh) / modified (vàng), dùng mã màu ANSI:

#!/bin/bash
input=$(cat)
branch=$(git branch --show-current 2>/dev/null)
staged=$(git diff --cached --numstat 2>/dev/null | wc -l | tr -d ' ')
modified=$(git diff --numstat 2>/dev/null | wc -l | tr -d ' ')
printf " %s \033[32m+%s\033[0m \033[33m~%s\033[0m" "$branch" "$staged" "$modified"

3) Chi phí + thời lượng:

#!/bin/bash
input=$(cat)
cost=$(echo "$input" | jq -r '.cost.total_cost_usd // 0')
ms=$(echo "$input" | jq -r '.cost.total_duration_ms // 0')
sec=$((ms / 1000)); min=$((sec / 60)); s=$((sec % 60))
printf "\$%.2f | %dm %ds" "$cost" "$min" "$s"

4) Multi-line + threshold màu - dòng 1: model/dir/branch; dòng 2: bar đổi màu (xanh <70, vàng 70-89, đỏ 90+) + cost + rate limit:

#!/bin/bash
input=$(cat)
model=$(echo "$input" | jq -r '.model.display_name // "?"')
dir=$(echo "$input" | jq -r '.workspace.current_dir // "."' | xargs basename)
branch=$(git branch --show-current 2>/dev/null)
pct=$(echo "$input" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1)
cost=$(echo "$input" | jq -r '.cost.total_cost_usd // 0')
rl=$(echo "$input" | jq -r '.rate_limits.five_hour.used_percentage // empty')
if [ "$pct" -ge 90 ]; then c="\033[31m"; elif [ "$pct" -ge 70 ]; then c="\033[33m"; else c="\033[32m"; fi
printf "[%s] 📁 %s %s\n" "$model" "$dir" "$branch"
printf "${c}%s%% context\033[0m | \$%.2f" "$pct" "$cost"
[ -n "$rl" ] && printf " | 5h: %s%%" "$rl"

Mình dùng chính preset multi-line này hằng ngày: dòng trên để định vị, dòng dưới đổi màu cảnh báo khi context sắp đầy - rất hiệu quả để không bị /compact giữa chừng.

Cấu hình cho Windows (PowerShell + Git Bash)

Phần lớn hướng dẫn ngoài kia là bash-only. Nếu bạn dùng Windows (như mình), có hai đường chạy được.

Cách A - Git Bash: đơn giản nhất. Các script .sh ở trên chạy trực tiếp nếu Git Bash và jq đã cài. Trỏ command tới file .sh như bình thường.

Cách B - PowerShell: viết script .ps1 đọc stdin rồi parse JSON:

# C:/Users/ban/.claude/statusline.ps1
$data = $input | Out-String | ConvertFrom-Json
$model = $data.model.display_name
$pct = [math]::Floor($data.context_window.used_percentage)
Write-Host "[$model] $pct% context" -NoNewline

Rồi khai báo trong settings.json:

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

⚠️ Bẫy backslash trên Windows: luôn viết đường dẫn bằng dấu / (gạch chéo xuôi) trong field command. Git Bash "nuốt" dấu \ khiến lệnh fail âm thầm - statusline không hiện mà chẳng báo lỗi. Ký tự ~ vẫn dùng được bình thường.

Đây là điểm khiến nhiều bạn VN dùng Windows loay hoay mãi: script đúng nhưng path sai dấu gạch. Đổi \ thành / là chạy.

Mẹo hiệu năng: đừng để statusline làm chậm phiên

Script chạy rất thường xuyên. Trên repo lớn, git status hay git diff có thể mất vài trăm mili-giây mỗi lần - nhân lên là cả phiên bị khựng nhẹ. Vài mẹo giữ statusline nhanh:

• Cache kết quả git ra file tạm theo session_id, refresh mỗi ~5 giây thay vì gọi git mỗi lần. Dùng session_id làm khoá cache - không dùng $$/PID vì nó đổi mỗi lần script chạy, cache sẽ vô dụng.
• Giữ output ngắn - một dòng, vài field. Dòng dài vừa chậm vừa khó đọc.
• Dùng refreshInterval cho dữ liệu theo thời gian (đồng hồ, rate limit) thay vì tự tính lại nặng nề.
• Đọc COLUMNS/LINES để canh bề rộng, cắt bớt khi terminal hẹp.

Quy tắc chung: nếu script chạy quá ~300ms là bạn sẽ cảm nhận được độ trễ. Cache và cắt gọn là hai đòn bẩy lớn nhất.

Lỗi thường gặp & cách khắc phục

Để soi lỗi, chạy claude --debug và xem exit code + stderr của script. Ngoài ra, một số emulator (ví dụ Terminal.app) không hỗ trợ link OSC 8, nên nếu bạn nhúng hyperlink vào statusline thì nó có thể không bấm được - đây là giới hạn của terminal, không phải lỗi script.

Ngại sửa script? Dùng visual status line builder

Không phải ai cũng muốn viết bash hay PowerShell chỉ để có một dòng trạng thái. Nếu bạn thuộc nhóm đó, một lựa chọn no-code là bộ kit AgentKit (giảm 20% qua link): desktop app của nó có trình dựng status line trực quan - kéo-thả field (model, context, cost, git…) thay vì code tay - cùng chỗ quản lý license, skill và MCP. Với người ngại terminal, đây là cách dựng statusline mà không chạm vào settings.json.

Nói thẳng: /statusline và các script ở trên là hoàn toàn miễn phí và đủ dùng cho hầu hết mọi người - trình dựng trực quan chỉ tiện hơn nếu bạn muốn no-code hoặc quản lý cả bộ skill/agent trong một chỗ. Muốn tìm hiểu kỹ trước khi quyết, đọc bài AgentKit là gì và có đáng dùng không (review).

Câu hỏi thường gặp (FAQ)

Statusline có tốn token không?

Không. Statusline chạy một script local trên máy bạn, không gọi API Claude nên không tiêu tốn token. Bạn hiển thị bao nhiêu thông tin cũng không ảnh hưởng chi phí phiên.

Dùng được trên Windows không?

Được. Bạn có thể chạy script .sh qua Git Bash, hoặc viết .ps1 gọi bằng powershell -NoProfile -File. Lưu ý viết đường dẫn bằng dấu / để tránh bẫy backslash.

Vì sao statusline không hiện?

Nguyên nhân phổ biến nhất là quên chmod +x trên script. Ngoài ra: script in ra stderr thay vì stdout, chưa chấp nhận workspace trust, bật disableAllHooks, hoặc path sai dấu gạch trên Windows. Chạy claude --debug để xem lỗi.

/statusline khác sửa settings.json thế nào?

Lệnh /statusline để Claude Code tự sinh script và tự cấu hình theo mô tả tiếng Anh của bạn - nhanh, hợp người mới. Sửa settings.json tay cho bạn toàn quyền kiểm soát nội dung và định dạng. Nhiều người dùng /statusline để có bản nháp rồi chỉnh file tay.

Hiện % context để làm gì?

Để chủ động quản lý hội thoại. Khi context sắp đầy, bạn tự /compact hoặc tách việc thay vì bị Claude Code nén bất ngờ giữa lúc đang làm - vốn dễ làm mất mạch ngữ cảnh.

Có config sẵn không cần code không?

Có. Nhanh nhất là dùng /statusline để Claude tự viết. Nếu muốn giao diện kéo-thả hoàn toàn không code, trình dựng status line trực quan trong desktop app của AgentKit là một lựa chọn no-code.

Kết luận + bước tiếp theo

Bạn không cần một script hoành tráng. Một dòng đơn giản hiện model + % context đã đủ tăng năng suất rõ rệt; cứ nâng dần khi thấy thiếu. Bắt đầu bằng /statusline, rồi mở file ra chỉnh theo ý mình. Đọc thêm Claude Code cheat sheet để gom các lệnh hay dùng, và hướng dẫn viết CLAUDE.md để Claude Code hiểu dự án của bạn hơn. Nếu mới bắt đầu, quay lại Claude Code là gì.