Claude Code Custom Statusline Generator (cc-statusline Pattern)

## What This Is / What Problem It Solves Claude Code runs in the terminal, but its default status information is sparse—you often can't tell 'which model is running right now, how much context is left, how much this session has already cost, or how long until my usage resets.' By the time context blows out or your quota runs dry, it's already too late to react. This recipe's approach: generate a **custom statusline** for your project that packs all of this live information into the single line at the bottom of the Claude Code interface, visible at all times. ## Why This Source Is Worth Using Distilled from chongdashu/cc-statusline (MIT license), which turns 'statusline generation' into a single interactive `npx` init: it asks you two preference questions, generates an optimized bash script, and writes it directly into Claude Code's `settings.json`—restart and it's live. Three design choices worth borrowing: (1) it pursues speed with **native shell execution**, so it doesn't slow down every refresh; (2) it hooks into `ccusage` for live spend and token burn rate, using a **file lock** to prevent multiple statuslines from triggering simultaneously and spawning a pile of redundant ccusage processes; (3) it has a fallback for systems without `jq` installed, so it doesn't just break outright. These three points are exactly where hand-rolling a statusline yourself is most likely to go wrong. ## How to Use It (Steps / Key Points) 1. **Choose scope**: decide whether to install it globally (`~/.claude/`, shared across all projects) or just for this project (`./.claude/`). 2. **Inject into settings.json**: add a `statusLine` block to `settings.json`—`type` set to `command`, `command` pointing to your `statusline.sh`, `padding` set to 0. Be sure to 'merge' into the existing config rather than overwriting the whole file. 3. **Understand the input**: on every refresh, Claude Code feeds the script a block of JSON via stdin containing fields like `model`, `workspace`, and `cost`. The script reads this JSON, parses it, and outputs a single-line string. 4. **Install jq**: advanced fields like the context percentage, token stats, and session timer all depend on `jq` to parse the JSON; without it, the script falls back to a basic mode. 5. **Hook up ccusage (optional)**: for live spend and burn rate, go through `npx ccusage` (no separate install needed), and make sure to add a file lock. 6. **Restart Claude Code** for changes to take effect. The fastest way to get started is to just run `npx @chongdashu/cc-statusline@latest init` and follow the interactive flow, then fine-tune which fields to display using this recipe's field list. ## When to Use It - You run long sessions often and want to keep an eye on context and spend at all times, to avoid running out unexpectedly. - You switch between multiple projects and want to confirm 'where am I, which model am I using' at a glance via branch / directory / model. - You want a reproducible, version-controllable team statusline setup (committing `statusline.sh` alongside `settings.json`). Not a fit: if you only use Claude Code occasionally and briefly and don't care about usage details, the default is enough—installing this would just be noise. 📎 Source: chongdashu/cc-statusline (author: Chong-U Lim / AIOriented, MIT license) — this piece is a Traditional Chinese adaptation; see the link above for the original.

填下面的欄位，上方 prompt 會即時替換 [方括號] 內容。填好後按「複製組好的 prompt」直接丟進工具。

# 任務：替本專案產生一條 Claude Code 自訂狀態列

你是一位熟悉 Claude Code 設定的工程助理。請依下列規格，為我的專案產生並安裝一條狀態列（statusline）。

## 1. 安裝範圍
- 安裝範圍：{{SCOPE}}（global 寫入 `~/.claude/`，或 project 寫入 `./.claude/`）
- 產生兩個檔案：`statusline.sh`（產生的腳本）與更新後的 `settings.json`

## 2. settings.json 設定區塊
在目標 `settings.json` 注入以下區塊（保留既有設定，不要整檔覆蓋）：

```json
{
  "statusLine": {
    "type": "command",
    "command": "{{STATUSLINE_PATH}}",
    "padding": 0
  }
}
```
（`{{STATUSLINE_PATH}}` 例如 `.claude/statusline.sh` 或絕對路徑）

## 3. 狀態列要顯示的欄位
依我勾選的項目產生（未勾選的不要塞，避免雜訊）：
- [ ] 目前工作目錄（家目錄縮成 `~`）
- [ ] Git 目前分支名
- [ ] 模型名稱 + Claude Code 版本
- [ ] Context 視窗用量（含進度條 / 百分比）
- [ ] 即時花費 + 燃燒率（burn rate，由 cost 與 duration 算）
- [ ] 距用量上限重置的倒數計時
- [ ] Token 用量 / 吞吐
- [ ] 目前 output style
要顯示的子集：{{FIELDS}}

## 4. 腳本如何讀輸入
Claude Code 會把一段 JSON 從 **stdin** 餵給這支腳本，至少含 `model`、`workspace`、`cost` 等欄位。腳本要：
1. 從 stdin 讀整段 JSON
2. 偵測系統有沒有 `jq`：
   - 有 `jq` → 用 `jq` 解析所有欄位（context %、token 統計、session timer 都要靠它）
   - 沒 `jq` → 走「基本 fallback 解析」，只輸出能穩定取得的欄位，並提示安裝 `jq`（macOS: `brew install jq`／Debian: `apt install jq`／Windows: `scoop install jq`）
3. 用原生 shell 執行求速度，輸出單行字串給 Claude Code 顯示

## 5. ccusage 即時統計（選用）
若要 cost / token 燃燒率，透過 `npx ccusage`（免另裝）取得；務必加 **檔案鎖**，避免同一時間多支狀態列同時觸發、生出多個 ccusage 行程。

## 6. 交付
- 產生 `statusline.sh`、設好可執行權限、印出它的完整內容
- 印出我該貼進 `settings.json` 的最終區塊
- 提醒我「重啟 Claude Code 才會生效」
- 若偵測不到 `jq`，明確告訴我哪些欄位會降級

參考做法：可直接用 `npx @chongdashu/cc-statusline@latest init` 一鍵互動產生，再依本規格微調。