Claude Epic Status Line

A feature-rich status line for Claude Code that displays model info, context usage, git status, rate limits, session cost, and more — quiet when everything is healthy, loud exactly where something needs attention. Zero-config by default, deeply customizable when you want it (thresholds, palette, glyph sets, per-segment toggles).

📖 Full documentation — installation · usage · configuration · tips · troubleshooting

What it looks like

Watch the 90-second tour

Click to play, or watch it on the documentation site.

The status line itself

Features

Segment	Description
Model	Short model name (e.g., Opus 4.6 instead of Claude Opus 4.6)
Context	Usage percentage + token counts (e.g., 12% (42k/200k)) with color coding
Auto-compact warning	Steady bold ⚠ when context usage >= 80%
Directory	Truncated to last 2 path components
Git branch	Branch name with detailed status: staged (S:2), unstaged (U:1), untracked (A:3)
Git ahead/behind	⇡2⇣1 arrows showing commits ahead/behind upstream
Worktree	⎇wt indicator when running inside a git worktree
Session cost	$X.XX with configurable warn/critical thresholds and currency
Session duration	5m, 1h30m, etc.
Lines changed	+156/-23 cumulative lines added/removed
Per-turn cost	48k/turn — what the next message costs before you type (at the current model's cache-read rate), and 88t turns so far
Cold prompt cache	486k next turn (cache cold) — once the prompt cache has expired, the next message re-writes the whole context
Effort level	● high, ◑ medium, ◔ low (from the session itself)
Badges	Subagent name, fast mode, thinking, vim, non-default output style, ⚠200k+
Rate limits	█░ progress bars for 5-hour, 7-day, per-model, and extra usage with reset times
Pace projection	⇢ 94% — where the 5-hour / 7-day window lands at the current burn rate
Context hint	One line naming the right command: /compact for a full window, /clear for an expensive one

Color coding

One escalation scale drives every percentage-based segment (context, rate bars) — quiet when healthy, then:

• Yellow — ≥ 70% (CESL_WARN)
• Orange — ≥ 80% (CESL_HIGH); context also gains a steady bold ⚠
• Red — ≥ 90% (CESL_CRIT)

Session cost uses its own CESL_COST_WARN/CESL_COST_CRIT thresholds. The per-turn cost uses absolute token thresholds (CESL_CTX_WARN/CESL_CTX_HIGH) because a percentage of a 1M window says nothing about what a message costs — 486k reads as a comfortable 49% full while re-sending 48k tokens every turn at a 10% cache-read rate (24k on Opus 5.5). The model name is colored by model family (Opus, Sonnet, Haiku, Fable).

NO_COLOR and TERM=dumb are honored; CESL_COLOR=0/1 overrides the detection either way.

Requirements

• jq — JSON parsing
• curl — fetching rate limit data from the Anthropic API
• git — branch and worktree detection

Installation

Quick install

git clone https://github.com/dsebastien/claude-epic-status-line.git
cd claude-epic-status-line
bash install.sh

Manual install

1. Copy statusline.sh to ~/.claude/statusline-command.sh
2. Add this to your ~/.claude/settings.json:

{
  "statusLine": {
    "type": "command",
    "command": "bash '/home/YOUR_USER/.claude/statusline-command.sh'"
  }
}

3. Restart Claude Code.

Uninstall

bash uninstall.sh

Or manually remove the statusLine key from ~/.claude/settings.json and delete ~/.claude/statusline-command.sh.

Configuration

Everything is optional — with zero config the status line renders its default design. Settings layer as: script defaults < ~/.config/claude-epic-status-line/config.sh < CESL_* environment variables (environment wins).

This is the beginning of the README. Read the rest at the original. Read the full README ↗