Content
# cc-statusline
**English · [繁體中文](./README.zh-TW.md)**
A comprehensive statusline dashboard for Claude Code. See everything at a glance — no slash commands needed.
## What it shows
| Section | Info |
|---------|------|
| **session summary** | Auto-generated whole-session summary (Claude rewrites it every ~10 messages with built-in compression so it stays under ~120 chars) |
| **directory** | Current working directory + `+added -removed lines` |
| **repo + branch** | `owner/repo` (parsed from `git remote`) + branch + `(N changed)` |
| **cost** | `cost $TOTAL (<window>) · $SESSION (this session)` — all-session spend rendered as parallel parenthetical annotations. Window defaults to all time; set `aggWindowDays` in `~/.claude/cc-statusline-rows.json` for a rolling view (e.g. `7` / `30` / `90`). |
| **model** | Active model name + effort level with 5-tier color ladder (`low` dim / `medium` green / `high` yellow / `xhigh` orange / `max` red) |
| **duration** | Active session time — sum of every turn's wall-clock duration (UserPromptSubmit → Stop). Inter-turn idle is naturally excluded, no idle threshold needed. Shares the model row area visually but toggles independently (`/cc-statusline:rows hide duration`). |
| **tokens / context / compact** | `tokens TOTAL (SESSION this session)` (same all+session dual display as cost) · context window % · compact count (`compact 1 time` / `compact N times`) |
| **5h-quota** | Color-coded bar (green → yellow → red) + auto-rolling `resets Xh Ym` countdown. Auto-zeros when `resets_at` passes real-world time (payload is stale until next message). |
| **7d-quota** | Color-coded bar + auto-rolling `resets Xd Yh` countdown with same rollover behavior |
| **agents** | Subagents that ran in this session — `critic ✓ 5m ago`, parallel runs collapse to `critic ○×3` (running) or `critic ✓×2 5m ago` (done) |
| **memory** | Which CLAUDE.md scopes are loaded (global / project / rules) |
| **mcp** | MCP server health probed via `claude mcp list` — count of active + each unhealthy server with its state (`✘ failed`, `△ needs auth`) |
| **edited** | Recently edited files in this session, newest first (long names front-truncated with `…`) |
| **history** | Right column showing the last messages (▶ you, ◀ Claude), grows to fill terminal width |
## Install
### Option A — plugin install (recommended)
```
claude plugin marketplace add NYCU-Chung/cc-statusline
claude plugin install cc-statusline@cc-statusline
```
Hooks are registered automatically (via the plugin's own `hooks/hooks.json`), so you can **skip the Hook wiring section below**.
Then add the `statusLine` block to `~/.claude/settings.json` — Claude Code doesn't allow plugins to set this for you:
```json
{
"statusLine": {
"type": "command",
"command": "node ${CLAUDE_PLUGIN_ROOT}/statusline.js",
"refreshInterval": 30
}
}
```
### Option B — manual install (for hacking on the script)
Pick the block that matches your shell. **`~` is expanded by bash/zsh before `git` sees it, but PowerShell and cmd don't expand it** — using `~` there makes `git clone` create a literal `~` folder (reported in [#6](https://github.com/NYCU-Chung/cc-statusline/issues/6)). Use `$HOME` / `%USERPROFILE%` instead.
**bash / zsh / Git Bash on Windows**
```bash
git clone https://github.com/NYCU-Chung/cc-statusline ~/cc-statusline
mkdir -p ~/.claude/hooks
cp ~/cc-statusline/statusline.js ~/.claude/statusline.js
cp ~/cc-statusline/hooks/*.js ~/.claude/hooks/
```
**PowerShell**
```powershell
git clone https://github.com/NYCU-Chung/cc-statusline "$HOME/cc-statusline"
New-Item -ItemType Directory -Force "$HOME/.claude/hooks" | Out-Null
Copy-Item "$HOME/cc-statusline/statusline.js" "$HOME/.claude/statusline.js"
Copy-Item "$HOME/cc-statusline/hooks/*.js" "$HOME/.claude/hooks/"
```
**Windows cmd**
```cmd
git clone https://github.com/NYCU-Chung/cc-statusline "%USERPROFILE%\cc-statusline"
mkdir "%USERPROFILE%\.claude\hooks" 2>nul
copy "%USERPROFILE%\cc-statusline\statusline.js" "%USERPROFILE%\.claude\statusline.js"
copy "%USERPROFILE%\cc-statusline\hooks\*.js" "%USERPROFILE%\.claude\hooks\"
```
Then add this `statusLine` block to `~/.claude/settings.json`:
```json
{
"statusLine": {
"type": "command",
"command": "node ~/.claude/statusline.js",
"refreshInterval": 30
}
}
```
### Hook wiring (Option B only — plugin install does this automatically)
Add these to your `~/.claude/settings.json` hooks section to enable all statusline features:
```json
{
"hooks": {
"SubagentStart": [{ "matcher": ".*", "hooks": [{ "type": "command", "command": "node ~/.claude/hooks/subagent-tracker.js" }] }],
"SubagentStop": [{ "matcher": ".*", "hooks": [{ "type": "command", "command": "node ~/.claude/hooks/subagent-tracker.js" }] }],
"PreCompact": [{ "matcher": ".*", "hooks": [{ "type": "command", "command": "node ~/.claude/hooks/compact-monitor.js" }] }],
"UserPromptSubmit": [{ "hooks": [
{ "type": "command", "command": "node ~/.claude/hooks/message-tracker.js" },
{ "type": "command", "command": "node ~/.claude/hooks/summary-updater.js" },
{ "type": "command", "command": "node ~/.claude/hooks/active-time-tracker.js" }
]}],
"Stop": [{ "matcher": ".*", "hooks": [
{ "type": "command", "command": "node ~/.claude/hooks/message-tracker.js" },
{ "type": "command", "command": "node ~/.claude/hooks/active-time-tracker.js" }
]}],
"PostToolUse": [{ "matcher": "Write|Edit", "hooks": [
{ "type": "command", "command": "node ~/.claude/hooks/file-tracker.js" }
]}]
}
}
```
## What each hook does
| Hook | Event | Purpose |
|------|-------|---------|
| `subagent-tracker.js` | SubagentStart / SubagentStop | Tracks which agents are running or finished, including concurrent invocations |
| `compact-monitor.js` | PreCompact | Counts how many times context was compacted |
| `file-tracker.js` | PostToolUse (Write/Edit) | Records recently edited files |
| `message-tracker.js` | UserPromptSubmit / Stop | Caches recent messages for the history column |
| `summary-updater.js` | UserPromptSubmit | Every ~10 messages, asks Claude to rewrite the whole-session summary with compression rules |
| `active-time-tracker.js` | UserPromptSubmit / Stop | Maintains active session time (sum of turn durations) — bootstraps from transcript on first run, then accumulates per turn |
| `mcp-status-refresh.js` | _(not a Claude Code hook event)_ | Background script auto-spawned by `statusline.js` when the MCP cache is stale. Probes `claude mcp list` and writes `~/.claude/mcp-status-cache.json`. Lives in `hooks/` only because that's where the install steps copy it; it's never invoked via the hooks settings entries. |
| `mcp-status-refresh.js` | (none — auto-spawned) | Statusline launches this in the background each render to refresh `~/.claude/mcp-status-cache.json` from `claude mcp list`. Self-skips if cache is fresh (<90s). |
## How it survives resets and multi-session
**Delta-based cost / lines / tokens.** Claude Code occasionally resets `cost.total_cost_usd` etc. mid-session (context compaction, auto-recovery, etc.). The statusline tracks deltas in `~/.claude/cc-statusline/cum-<sid>.json` — when the payload value drops, only the baseline is reset; the cumulative total never goes backward. (Active session time follows a separate path — see "Per-feature state isolation" below.)
**Defensive per-session keying via transcript filename.** Every per-session tmp file (cum, messages, summary, agents, files, compact count) is keyed by `path.basename(transcript_path)` rather than the runtime `session_id` payload, falling back to `session_id` only when no transcript is present. The transcript filename is the canonical UUID of the logical session and is invariant for its lifetime, so this keying stays correct even if `session_id` semantics ever shift. (Empirically on the current Claude Code build, `session_id` and the transcript filename UUID are already identical — the choice is preventive, not a bug fix.)
**Active session time, hook-driven.** The `duration` row is the sum of (`Stop` timestamp − `UserPromptSubmit` timestamp) for every turn, maintained by `hooks/active-time-tracker.js`. The first run on a session bootstraps from the transcript JSONL by replaying user→assistant timestamp pairs. Because every slice is bounded by an open turn, idle time outside turns is naturally excluded — no threshold, no heuristic.
**Persistent state lives under `~/.claude/cc-statusline/`, not `tmpdir`.** All per-session accumulation files (`cum`, `active`, `summary`, `msgs`, `msgcount`, `agents`, `files`, `compacts`) sit under a dedicated dir in the user's `~/.claude/` rather than `os.tmpdir()`. The OS treats tmpdir as throwaway — Windows Storage Sense clears it on a 30-day cycle, `cleanmgr` / antivirus on whim, `/tmp` resets on Linux reboot — which was the root cause behind every cost-loss and active-time-reset story. Only true ephemeral caches (resolved terminal width, `.tmp` rename staging) belong in tmpdir. Existing tmpdir files are migrated automatically on the first render after upgrade.
**Per-feature state isolation (cost-loss fix).** Active session time lives in its own state file (`active-<sid>.json`), independent from the cum file (`cum-<sid>.json`) that tracks cost / lines / tokens. The cum file is **owned exclusively by `statusline.js`** — no hook ever writes to it. This invariant matters because earlier versions had hooks that wrote partial cum files (containing only their own fields), which made the next statusline render's fallback path reset accumulated `cost.total` to 0. Splitting state per writer eliminates the failure mode entirely; the cum read path was also hardened so a missing field never resets `total`.
**Width is user-set, not auto-detected.** Width auto-detection inside the statusline hook is essentially impossible: stdio is a pipe so `process.stdout.columns` is undefined, `$COLUMNS` is unset, `tput cols` returns 80, PowerShell-spawned subprocesses report their own hidden-window width, and `/dev/tty` is not accessible. The upstream request to expose the actual width was [closed as not planned](https://github.com/anthropics/claude-code/issues/5430). The statusline does try the cheap signals (`process.stdout.columns`, `$COLUMNS`) on the off-chance Anthropic ever fixes the contract, but otherwise falls back to a conservative `120`-column box. **Set `statuslineWidth` in `~/.claude/cc-statusline-rows.json` to your terminal's actual column count** (run `tput cols` in a normal shell to measure). `statuslineWidthOffset` (default 4) reserves a few columns on the right for Claude Code's own padding.
**Three-layer durability for cum files.** On top of the persistent location, every cum write now goes through a stability pipeline: (1) **monotonic invariant** — read the on-disk file right before write and never let in-memory `cost.total` (or `add` / `rm` / `tok`) drop below the stored value, since these accumulators are monotonic by definition; (2) **single-step backup** — the previous content is atomically copied to `cum-<sid>.bak.json` before each write, so a corrupted file can be hand-recovered; (3) **audit log** — significant cost changes (≥ \$0.01) append one JSON line each to `~/.claude/cc-statusline/audit.log` with timestamp, sid, before / after / delta. The log rotates to `audit.log.1` at ~1 MB.
**Cross-session quota aggregation.** Quotas are global across all your Claude Code sessions, but each session's payload only reflects its own cached observation. The statusline writes a snapshot to `~/.claude/rate-limit-snapshots.json` on every render and aggregates across sessions: it picks the snapshot with the latest live `resets_at` (most recent API observation) and shows MAX `used_percentage` from that group. All sessions converge on the same displayed %.
**All-time cost + tokens by default, rolling-window optional.** The `cost $TOTAL (all time) · $SESSION (this session)` and `tokens TOTAL (SESSION this session)` figures aggregate across `cum-*.json` files in `~/.claude/cc-statusline/` filtered to the canonical 24-hex session-id shape (so stray test fixtures can't poison the number). Set `aggWindowDays` in `~/.claude/cc-statusline-rows.json` to `7` / `30` / `90` etc. for a rolling view; the previous 30-day default existed only to mirror tmpdir's eviction interval and is no longer needed now that state lives outside tmpdir.
**Time-based rate-limit rollover.** Claude Code's `rate_limits.*.resets_at` is frozen at the moment of the last API response. If the user leaves the session idle past a reset boundary, the payload says "87% used" even though the window has rolled over to 0%. The statusline checks `resets_at` against real time — past expiry, it auto-zeros the bar and computes the countdown against the next rolling 5h/7d boundary.
**Auto session rename for `/resume` picker.** Claude Code's transcript JSONL supports a `{"type":"custom-title","customTitle":"..."}` entry that drives the `/resume` picker's display name. `summary-updater.js` injects the current summary (first 40 chars) as a custom-title entry every time it writes, so each session gets a meaningful name instead of a UUID — no more guessing which hash is which.
**Whole-session summary with compression.** The summary is meant to capture the entire session arc, not the latest topic. The summary-updater prompt enforces a 120-char cap with explicit compression rules (merge related sub-topics, drop the least-significant older item) so new topics displace less-significant old ones rather than the most-recent work being truncated.
## Customize which rows you see
Don't want every row? Use the `/cc-statusline:rows` slash command (shipped with the plugin; saves to `~/.claude/cc-statusline-rows.json`):
```
/cc-statusline:rows — show current state
/cc-statusline:rows off — master switch: hide statusline entirely
/cc-statusline:rows on — master switch: re-enable
/cc-statusline:rows hide agents edited — turn listed rows off
/cc-statusline:rows show agents — turn listed rows on
/cc-statusline:rows only cost quota — enable listed, disable rest
/cc-statusline:rows toggle history — flip listed rows
/cc-statusline:rows reset — all on
```
12 row keys: `summary`, `dir`, `repo`, `model`, `duration`, `cost`, `usage`, `quota`, `agents`, `memory_mcp`, `edited`, `history`.
The layout auto-collapses when cells go empty — hide an entire column and the split layout merges into full-width rows; hide the whole split block and the top border fuses with the next section (no redundant horizontal lines).
### Configuration knobs
`~/.claude/cc-statusline-rows.json` also accepts these non-row settings (full reference in `commands/rows.md`):
| key | default | what it does |
|-----|---------|--------------|
| `summaryInterval` | `10` | UserPromptSubmit events between session-summary nudges |
| `aggWindowDays` | `0` (all time) | rolling window for cross-session cost / tokens aggregate; e.g. `7` / `30` / `90` |
| `statuslineWidth` | _(auto, fallback `120`)_ | hard-set box width in columns — measure with `tput cols` from a normal shell |
| `statuslineWidthOffset` | `4` | columns reserved on the right for Claude Code's own padding |
## Without hooks
The statusline works without the hooks — you just won't see agents, edited files, message history, compact count, session summary, or active session time. Quotas, cost, model, git, tokens, memory, and MCP all work from the built-in statusline JSON payload + the auto-spawned MCP refresher.
## Known limitations
- Claude Code does not pass terminal width to statusline commands ([issue #5430, closed as not planned](https://github.com/anthropics/claude-code/issues/5430)) and `process.stdout.columns` / `tput cols` / `$COLUMNS` are all unreliable inside the hook. The statusline defaults to a conservative 120-column box; **set `statuslineWidth` in `~/.claude/cc-statusline-rows.json` to your terminal's actual column count** (run `tput cols` in a normal shell to measure). `statuslineWidthOffset` (default 4) reserves columns on the right for Claude Code's own padding.
- MCP server state shown by the statusline comes from `claude mcp list` (a fresh probe at refresh time). Claude Code's `/mcp` UI shows the running session's cached state. The two can disagree if a server's connection has changed since the session started — the statusline reflects the latest probe, the UI reflects the session's view.
- `claude mcp list` does not expose all built-in bridges (e.g. `claude-in-chrome`), so the statusline's MCP count can be lower than what `/mcp` shows.
- Claude Code does not currently expose live MCP state in the statusline JSON payload ([issue #5511](https://github.com/anthropics/claude-code/issues/5511)) — once it does, the auto-spawned refresher won't be needed.
## License
MIT
