ccline

A feature-rich statusline for Claude Code that helps you track session health, manage quota, and avoid burning through your Max plan.

What you get

Line 1 — Identity & Project

O4.7 1M ◉ xhigh 🛡 plan | 📂 really-app (main*) 📝+147 -38 | @code-reviewer | ⎇ feat-x | → src/features/search

• Compact model name with effort level — the full ladder is rendered distinctly:

  | effort | glyph | color | notes | |--------|-------|---------|--------------------------------------------| | low | ◔ | dim | minimal reasoning | | medium | ◑ | white | | | high | ● | magenta | | | xhigh | ◉ | red | default on Opus 4.7 (v2.1.117+) | | max | ⚡ | red | deepest reasoning, session-only by default |

  The badge reflects the live session effort — including mid-session /effort changes — read from the input JSON's effort.level, falling back to the saved settings.json default.

• Permission mode badge — 🛡 plan, ✎ auto (acceptEdits), or ⚡ bypass (bypassPermissions). Hidden in default mode.

• Output-style badge (e.g., ◎ Learning) when not default

• Vim mode indicator ([N] / [I]) when vim mode is on

• Project root with git branch and dirty indicator (single git status call)

• Lines changed this session

• Subagent name (@code-reviewer) and worktree (⎇ feat-x) when active

• ⚠ 200k+ flag when the latest response crosses the fixed 200k-token threshold (long-context 2× pricing on 1M models — not a downgrade; the flag is independent of context-window size)

• Current working directory (relative to project, fish-style abbreviation if outside)

Line 2 — Session Health

#84 turns | ⏱ 2h14m | 72% 720k/1m ctx compact soon | $12.41 | api 66%

• Real user-turn counter (yellow at 30, red at 50 — tool results no longer inflate the count)
• Session duration (cross-platform — uses birthtime on macOS/Linux with mtime fallback on filesystems that don't track it)
• Context window usage with compact soon / compacting… / ⛔ blocked warnings matching Claude Code's actual autocompact thresholds (20k / 13k / 3k below the context limit)
• Running session cost (yellow at $5, red at $10)
• API-latency ratio — what fraction of total wall time was spent waiting on the model

Lines 3+ — Quota & Rate Limits

current ●●●●●●●○○○  68% resets 3:42pm  🔥 PEAK til 8pm
weekly  ●●●●●●●●○○  81% resets apr 3, 7:00pm  ~22%/day ⚡
fable   ●●●●○○○○○○  46% resets apr 3, 7:00pm  ⚠ plan ends jul 7
extra   ●○○○○○○○○○  €0.95/€40.00 resets aug 1

• Rate limits read directly from Claude Code's input JSON (freshest data); OAuth API serves as a fallback when input is empty (cached 60s at ${TMPDIR:-/tmp}/claude-$UID/)
• Peak hour detection (05:00–11:00 PT) with local end time — only shows when active
• Weekly burn rate projection — green if on pace, yellow if tight, red if you'll hit the limit
• ⚡ burning fast on either window when you're tracking ahead of schedule
• Per-model weekly meters — Max plans cap each premium model's weekly usage separately from the overall weekly bucket. Any model the API scopes (weekly_scoped in limits[]) gets its own row labelled by name (e.g. fable, opus). Rendered only from fresh API data, so the row disappears cleanly when the API stops returning it (e.g. after a plan window ends) or is unreachable.
• Fable plan-window badge — while Fable is plan-included (through Jul 7, 2026), the fable row carries a ⚠ plan ends jul 7 reminder; afterward the scoped bucket leaves the API and the row disappears on its own, with usage shifting to the credit-based extra line.
• extra credit line follows the account's billing currency reported by the API ($/€/£/¥, else the ISO code) instead of assuming USD

Install

npx @abdallahaho/ccline@latest

This copies the statusline script to ~/.claude/statusline.sh and configures your ~/.claude/settings.json. Restart Claude Code to see it.

If you already have a custom statusline, it's backed up to statusline.sh.bak first.

Requirements

• bash, jq, curl, git
• Claude Code with an active Max/Pro subscription (for rate limit bars)

# macOS
brew install jq

# Ubuntu / Debian / WSL
sudo apt install jq curl git

# Windows (Git Bash / MSYS2)
pacman -S jq curl git
# or with Chocolatey from PowerShell:
choco install jq curl git

Windows notes

ccline runs under Git Bash, MSYS2, or WSL — it is a bash script, not a native PowerShell one. Make sure Claude Code itself is launched from one of those shells so that the statusline command resolves bash correctly. PowerShell users can point the statusLine entry at bash -c "$HOME/.claude/statusline.sh" but running Claude Code under Git Bash or WSL is simpler.

Uninstall

npx @abdallahaho/ccline@latest --uninstall

Restores your previous statusline if a backup exists, or removes it and cleans up settings.json.

How it works

Claude Code pipes a JSON blob to the statusline script on every render. The script does a single jq parse via eval, then pulls rate limits directly from that blob when present — that data is always fresher than anything we could re-fetch. If the input JSON doesn't carry rate_limits (rare — only the very first render after launch), we fall back to the OAuth usage API, cached for 60s at ${TMPDIR:-/tmp}/claude-$UID/statusline-usage-cache.json with 0700 perms.

Autocompact thresholds (compact soon / compacting… / ⛔ blocked) mirror src/services/compact/autoCompact.ts in the Claude Code source: 20k / 13k / 3k below the model's context window.

The OAuth token (only needed for the API fallback and the extra line) is resolved from (in order):

1. $CLAUDE_CODE_OAUTH_TOKEN environment variable
2. macOS Keychain
3. ~/.claude/.credentials.json (works on every platform)
4. Linux secret-tool

For a line-by-line walkthrough of the script, see how-it-works.md. For contribution and release guidelines, see CLAUDE.md.

Credits

Heavily inspired by kamranahmedse/claude-statusline by Kamran Ahmed.

License

MIT