@ericcai/claude-statusline

A powerline-styled statusline for Claude Code — context gauge, git status, rate limits, and more.

Features

• Powerline-style segments with truecolor backgrounds and / dividers
• Context window gauge with color-coded percentage
• Git branch with dirty marker (falls back to worktree name)
• Pull request status badge (approved / changes requested / draft / open)
• Rate limit usage bars (current / weekly / extra)
• Effort level indicator
• Vim mode indicator
• Workspace path display

顯示的即時資訊

statusline 會即時顯示下列資訊，分為兩個區塊：主狀態列（來自 Claude Code stdin JSON）與 用量面板（來自 OAuth API，60 秒快取）。

主狀態列（第 1 行）

各欄位以 powerline 區段呈現，相鄰段以實心箭頭 銜接；當兩段底色相同時，自動降級為細線分隔。欄位依顯示順序如下（條件式欄位僅在符合條件時出現）：

| 欄位 | 範例 | 說明 | |------|------|------| | Vim mode | N | 僅在 vim mode 啟用時顯示於最左；I 插入（綠）／V 視覺（紫）／N 一般（灰） | | 模型名稱 | Opus 4.8 | 目前 Claude 模型，去除 Claude 前綴與 (...) 後綴（藍） | | Workspace | ericcai/.claude | 目前工作目錄；若為 project 子資料夾則顯示 project/sub/path（青） | | Git branch | main | 目前分支；有未提交變更時加橘色 *；無分支但有 worktree 時改顯示 worktree 名稱（黃） | | Repo | owner/name | 僅在「有 repo 資訊且無 PR」時顯示（天藍） | | PR | ✔ #1234 | 依 review state：✔ approved（綠）／✎ changes requested（橘）／⊘ draft（灰）／⌥ open（天藍） | | Context gauge | ▪▪▪▪▪▪▫▫▫▫ | 10 格長條，顯示剩餘 context 比例（>50% 綠、26–50% 黃、11–25% 橘、≤10% 紅） | | 剩餘百分比 | 62% | context window 剩餘百分比 | | Effort level | ◆ xhigh | 優先讀 stdin JSON 的 effort.level，否則 fallback ~/.claude/settings.json 的 effortLevel；xhigh/max ◆、high ◈（紫）、medium ◇、low ◌（灰） | | Output style | explanatory | 非 default 時才顯示（淡灰） |

用量面板（第 2 行起）

透過 https://api.anthropic.com/api/oauth/usage 取得，快取於 /tmp/claude/statusline-usage-cache.json（60 秒 TTL）。

| 欄位 | 範例 | 說明 | |------|------|------| | current | ●●●●○○○○○○ 45% ⟳ 4:59pm | 5 小時額度使用率 + 重置時間 | | weekly | ●●●●○○○○○○ 40% ⟳ apr 24, 7:59am | 7 天額度使用率 + 重置日期時間 | | extra | ○○○○○○○○○○ $0.00/$20.00 | 額外付費額度的已用金額／月上限（僅在 extra_usage.is_enabled=true 時顯示） | | resets | resets may 1 | extra 額度的下個月重置日（隨 extra 同時顯示） |

長條顏色依使用率遞增：綠 (<50%) → 橘 (50–69%) → 黃 (70–89%) → 紅 (≥90%)。

若 OAuth token 無法取得或 API 呼叫失敗，用量面板會靜默省略，不影響主狀態列顯示。

Prerequisites

• jq — JSON processor
• curl — HTTP client
• git — version control
• A Powerline / Nerd Font (e.g. MesloLGS NF, FiraCode Nerd Font) — required for the / dividers and the `` git glyph; without one they render as tofu boxes

Install

npx @ericcai/claude-statusline

Or install globally:

npm i -g @ericcai/claude-statusline
claude-statusline

Restart Claude Code after installation.

Uninstall

npx @ericcai/claude-statusline uninstall

What it does

1. Copies statusline.sh to ~/.claude/statusline.sh
2. Sets statusLine in ~/.claude/settings.json to run the script
3. Backs up any existing statusline.sh before overwriting

License

MIT