# Claude Epic Status Line Claude Epic Status Line is a feature-rich status line script for [[Claude Code]]. It replaces the default status bar with a color-coded display: one line of session info plus a rate-limit dashboard. Design principle: dim when healthy, colored when it needs attention. v2.0.0 (August 2026) was a complete redesign; v2.1.0 (September 2026) added the numbers a percentage cannot express. ![[Claude Epic Status Line - Video.mp4]] ![[Claude Epic Status Line - Picture.png]] ## Features - **Model name** — shortened, colored by model family (Opus/Sonnet/Haiku/Fable each get a hue) - **Context usage** with token counts (`38% (76k/200k)`); one escalation scale everywhere: yellow ≥70%, orange ≥80% (steady bold `⚠` — the auto-compact cue), red ≥90%; separate `⚠200k+` alert - **Per-turn cost** (`48k/turn`) and turn count (`88t`) — what the next message costs before you type a character, on *absolute* token thresholds rather than a percentage - **Pace projection** (`⇢ 94%`) on the 5-hour and 7-day rows — where the window lands at the current burn rate - **Context hint line** naming the right command: `/compact` for a full window, `/clear` for a merely expensive session - **Git status** with staged (`S:2`), unstaged (`U:1`), untracked (`A:3`) counts, ahead/behind arrows (`⇡2⇣1`), worktree marker (`⎇wt`) - **Session cost** (thresholded, currency-convertible), **duration**, **lines changed** (`+156/-23`) - **Effort level** (`● high`) plus badges: subagent name, fast mode, thinking, vim, non-default output style - **Rate-limit dashboard** — `█░` bars with reset times for the 5-hour window, 7-day window, **per-model weekly limits** (parsed from an undocumented usage-API `limits[]` array — numbers Claude Code's own UI doesn't display), and extra-usage credits (only when enabled). Every row switches on its own - **Configuration system** — zero-config by default; `~/.config/claude-epic-status-line/config.sh` + `CESL_*` env overrides for thresholds, palette, model hues, bar width, glyph sets (`unicode`/`nerd`/`ascii`), per-segment and per-row toggles, `NO_COLOR`, cache TTL, currency - **`explain` subcommand** — dumps raw stdin JSON, parsed values, cache state, and effective config for debugging ## How it works Claude Code pipes a JSON payload to the script on every refresh; the payload (model, context, cost, effort, rate limits — Claude Code ≥ 2.1.140) is parsed in a single `jq` call. The usage API is contacted only for enrichment (extra credits, per-model limits) with the OAuth token (env, credentials file, `secret-tool`, or macOS Keychain), per-user caching, and a single-flight lock across concurrent sessions. Turning off both API-backed rows skips token resolution and the request entirely. Warm render ≈ 60 ms. Hardened through a four-round adversarial review (Claude + GPT reviewers, 34 findings fixed: terminal-escape injection, token exposure on argv, overflow/octal arithmetic, cache races, macOS portability). The pace projection needs no state and no extra call: a rolling window opened at `resets_at` minus its own length, so the elapsed fraction — and therefore the burn rate — falls out of the stdin payload. It stays silent unless the pace actually overruns. ## Why per-turn cost, not percentage The API is stateless: every turn re-sends the whole conversation before you type a character. So the running cost is the context size, not the prompt length, and a one-word reply costs exactly what a complex request costs. A percentage cannot express this — 486k of a 1M window reads as a comfortable 49% full while re-sending 48k tokens every turn. The practical consequence is that `/clear` between unrelated tasks is the biggest available lever, and it is free: several short sessions move far less context than one long one, for identical work. ## Requirements - `jq`, `curl`, `git` — plain bash, Linux and macOS (bash 3.2+, BSD or GNU userland) ## References - Documentation: https://dsebastien.github.io/claude-epic-status-line/ - Source code: https://github.com/dsebastien/claude-epic-status-line - v2.1.0 release: https://github.com/dsebastien/claude-epic-status-line/releases/tag/v2.1.0 - v2.0.0 release: https://github.com/dsebastien/claude-epic-status-line/releases/tag/v2.0.0 - Inspired by https://github.com/kamranahmedse/claude-statusline - Per-turn cost and the actionable hint prompted by https://github.com/Field-Logic-Ltd/ClaudeStatsBar ## Related - [[Claude Code]] - [[CShip]] — alternative statusline; fewer built-in opinions, Starship-style TOML config and passthrough - [[Command Line Interface (CLI)]]