Claude Epic Status Line

This is a note from my public notes. View the 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.

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
• 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)
• 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 toggles, 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. 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).

Requirements

• jq, curl, git — plain bash, Linux and macOS (bash 3.2+, BSD or GNU userland)

References

• https://github.com/dsebastien/claude-epic-status-line
• https://github.com/dsebastien/claude-epic-status-line/releases/tag/v2.0.0
• Inspired by https://github.com/kamranahmedse/claude-statusline

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?