Claude Epic Status Line

Canonical version: 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.

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)

About Sébastien

Ready to get to the next level?