claude-statusline

Are you spending faster than the clock?

One bash script. Each limit bar shows two things: how much you have used, and how much time has passed. If usage is ahead of time, drop an effort level. If it is behind, you can raise it. Your folder, branch, model and context window sit on the same line, under the prompt.

See it in motion → alp82.github.io/claude-statusline

---

Install

Paste this into Claude Code. Claude installs the script, updates the settings, and checks the result.

Install the statusline from https://github.com/alp82/claude-statusline for me.
Run: curl -fsSL https://alp82.github.io/claude-statusline/install.sh | bash
Then check that bash, jq and curl are present, confirm ~/.claude/settings.json
points statusLine at ~/.claude/statusline.sh, and tell me what to do next.

Claude reads the installer before it runs it and tells you what changed. Paste it again to upgrade.

Or run the installer yourself

The same script without the agent:

curl -fsSL https://alp82.github.io/claude-statusline/install.sh | bash

It puts statusline.sh into ~/.claude/, makes it executable, and points settings.json at it. It copies anything it replaces to <file>.bak first. Run it again to upgrade. --no-settings installs the script only. --help lists all options.

Or install it by hand

One file, nothing else:

curl -fsSL https://raw.githubusercontent.com/alp82/claude-statusline/main/statusline.sh \
  -o ~/.claude/statusline.sh
chmod +x ~/.claude/statusline.sh

Then add this to ~/.claude/settings.json:

{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh"
  }
}

Uninstall

The same prompt in reverse:

Uninstall the statusline from https://github.com/alp82/claude-statusline for me.
Run: curl -fsSL https://alp82.github.io/claude-statusline/install.sh | bash -s -- --uninstall
Then confirm ~/.claude/statusline.sh is gone and ~/.claude/settings.json no longer
has a statusLine entry, and show me which .bak files it left behind.

Or run it yourself

curl -fsSL https://alp82.github.io/claude-statusline/install.sh | bash -s -- --uninstall

It removes ~/.claude/statusline.sh, the statusLine entry in settings.json, and the cache under ~/.claude/cache/. It backs up the script and settings.json as .bak first. It changes nothing else, and it leaves the entry alone if it points at another statusline. --no-settings removes the script only.

What it shows

Left to right:

• dir ⎇ branch — the directory name and the git branch. In a linked git worktree the glyph is an amber ⎇+:

  claude-statusline ⎇ main          ← the main checkout
  claude-statusline-fix ⎇+ fix/bar  ← a linked worktree
  

• ★ Model — the active model's display name

• Ctx — how full the context window is, 0–100%, and the token count in thousands

• 5h / 7d — the 5-hour and 7-day rate-limit windows: usage, elapsed time, and ↻ the time until the reset

• Fable — the same for the Fable weekly quota. It resets with the 7-day window, so it shows no ↻ of its own

How to read it

Usage against time

The top half of each bar shows usage. The bottom half shows elapsed time.

If usage is ahead of time, you run out before the window resets. Drop an effort level to slow the spend. The loop above shows this: high effort until usage passes the clock, then low effort, and the clock catches up again. If usage is behind, you have quota to spare and can raise the effort.

Colors

The bar color compares usage with elapsed time:

• 🟩 quota to spare: raise model or effort
• 🟨 on pace: keep as is
• 🟥 runs out early: lower model or effort

The number color shows usage: 🟩 under 50% · 🟨 50–80% · 🟥 over 80%

Context window

The bar turns yellow at 25% and red at 50%. The thresholds are lower than on the limit bars, because a full context window stops you at once. The bar fills in eighths of a character, so it moves before the number changes.

When a window resets

When a 5-hour window ends, both halves drop to zero and the countdown restarts at 5h0m. The top half stays green here, because usage trails the clock the whole time.

The Fable window

Fable has its own weekly quota. It refills only at the weekly reset, so the blue half tells you how long the wait is. It resets with the 7-day window, so it shows no ↻ of its own.

Claude Code does not send this value. The script reads it from ~/.claude.json and refreshes it from the API in the background, at most every ten minutes.

On macOS the refresh reads the OAuth token from the Keychain, because Claude Code stores it there instead of in ~/.claude/.credentials.json. The first read can open a Keychain dialog. Click Always Allow once and it stops asking. To skip the Keychain, set CLAUDE_STATUSLINE_NO_KEYCHAIN=1. The Fable bar then uses only the CLI's own cache.

Requirements

• bash
• jq — parses the statusline JSON from stdin
• curl — only for refreshing the Fable weekly quota

How it works

Claude Code sends JSON to the script on stdin (docs). Everything except the Fable window comes from that payload. For the Fable quota the script reads the CLI's cached copy in ~/.claude.json. When that copy is stale, it calls /api/oauth/usage in the background, at most every ten minutes.

License

MIT