claude-statusline

You're mid-session, deep in a refactor, and Claude stops responding. Was that the rate limit? How much context is left? You scroll up trying to remember which model you're on. The built-in status bar says "claude-sonnet-4-6" and nothing else.

This replaces it with everything you actually need to see at a glance. The essentials — model, thinking effort, git branch, rate limits, context — sit together on the top row; anything optional (session meta, live speed, cost) drops to a second row only when you enable it:

claude-sonnet-4-6  │  🧠 high  │  📂 myrepo  🌿 main ~+  │  5h:42% 🔥 [1h20m]  │  7d:8% 🍃 [3d4h]  │  ctx: [████░░░░░░] 38%
💨 142↓ 87↑/s  │  style:learning  │  🆔 a1b2c3  │  v2.6.0  │  $1.23

Rate limits, context window fullness, thinking effort, git branch — color-coded and updated every turn. Each row is a continuous, pipe-separated group rendered flush-left; when a row is wider than your terminal it wraps onto another line rather than truncating. See Layout & width.

Nerd Font mode:

Emoji mode:

What each segment tells you

Layout & width

The statusline renders as up to two rows, split by importance rather than by alignment:

• Row 1 — the core. Model, thinking effort, fast-mode badge, git repo/branch, the 5h / 7d / per-model rate limits, the context bar (with compaction counter), and the >200k warning. Everything you almost always want.
• Row 2 — the extras. Token speed, session duration, CWD, output style, session ID, version, extra usage, session cost. Each is opt-in, and the whole row is suppressed when none are enabled — so a lean config is a single line with no trailing blank.

Within a row, segments are a continuous group separated by │ and rendered flush-left. There's no left/right spread: the first segment starts at column zero and the rest follow.

When a row is wider than your terminal, it wraps onto another line at a │ boundary rather than truncating at the edge — so nothing important falls off-screen, it just flows downward. (A single segment wider than the whole terminal still takes its own line; there's nothing smaller to break on.)

Width is detected automatically in this order: COLS (config) → $COLUMNS → tput cols → 80. If wrapping happens too early or too late, pin it explicitly in .statusline.conf:

COLS=160

Install

bash <(curl -fsSL https://raw.githubusercontent.com/Flagrare/claude-statusline/main/install.sh)

The installer checks for jq (the only hard dependency), offers to install it if missing, asks whether you want emoji or Nerd Font icons, and wires up ~/.claude/settings.json. Restart Claude Code after installing.

Files are placed in ~/.claude/statusline/ and slash commands in ~/.claude/commands/. No git clone required.

Icon modes

Four rendering modes, switchable at any time without restarting:

Switch via slash command in Claude Code (cycles emoji → nerd → unicode → ascii → emoji with no arg):

/statusline-icons          # cycle to next mode
/statusline-icons nerd     # set explicitly
/statusline-icons emoji
/statusline-icons unicode
/statusline-icons ascii

The change takes effect on the next status bar refresh.

Per-model usage (opt-in)

Claude Code's statusline JSON only exposes the combined 7-day rate limit. But on Pro/Max plans Anthropic enforces a separate Sonnet weekly cap (and an Opus weekly cap on Max) — visible in /usage but not in the status bar. This package fills that gap.

Enable with:

/statusline-sonnet        # toggle
/statusline-sonnet on
/statusline-sonnet off

Once enabled you'll see extra segments:

... │ 7d:96% 🔥 [4d15h] │ sonnet:12% 🍃 [11h13m] │ ...

How it works

A small background poller (usage-poller.sh) calls https://api.anthropic.com/api/oauth/usage every ~5 minutes using the OAuth token Claude Code stores for its own /usage command — the same endpoint, no third parties. The response is cached at ~/.claude/.statusline-usage-cache.json and the statusline reads from the cache on every render.

The Opus segment only appears for users whose plan exposes a separate Opus quota; for everyone else only sonnet: shows.

macOS keychain prompt

The first time the poller runs, macOS will show:

claude-statusline wants to use your confidential information stored in 'Claude Code-credentials'.

Click Always Allow so you don't see it again. The token never leaves your machine except in the request to api.anthropic.com.

When it does nothing

• API plan users — the endpoint returns null for these fields, so no extra segments render.
• Free plan users — same as above.
• Token expired — the poller silently waits; Claude Code refreshes the keychain entry on its next API call and the next poll picks it up.

JSONL signals (opt-in)

Three extra segments are derived from the current session's transcript JSONL under ~/.claude/projects/<encoded-cwd>/. All three default to off and have their own toggle.

All three are pure local reads — no network calls. Token speed and session duration cost one bounded read (head -1 + tail -200) of the JSONL on each render; compaction maintains a tiny per-session state file under ~/.claude/.statusline-state/.

Slash commands

Sixteen Claude Code slash commands are available after install:

Requirements

Update

/statusline-update

Or manually: bash <(curl -fsSL https://raw.githubusercontent.com/Flagrare/claude-statusline/main/update.sh)

Uninstall

bash <(curl -fsSL https://raw.githubusercontent.com/Flagrare/claude-statusline/main/uninstall.sh)

This removes the statusLine key from ~/.claude/settings.json, deletes ~/.claude/statusline/, and removes the slash command files.

License

MIT