Claude Code Statusline

A custom statusline script for Claude Code on macOS and Linux that displays useful session and API usage information.

Screenshot

What It Displays

• Repository name - Current project directory name
• Model - Active Claude model and effort level (e.g., "Opus (medium)")
• Context window - Visual progress bar with percentage
• Session tokens - Total tokens used this session (formatted as K/M)
• Usage remaining - 5-hour and 7-day quota left (color-coded: green >40% left, yellow 11-40%, red ≤10%)
• Git branch - Current branch name

Requirements

• macOS or Linux
• jq - Install with brew install jq (macOS) or sudo apt install jq (Debian/Ubuntu)
• Claude Code with OAuth authentication

Installation

With AI Agent

Copy and paste this prompt into Claude Code:

Install the statusline from https://github.com/inspiretelapps/claude-code-statusline
into ~/.claude/statusline-command.sh, wire it up in ~/.claude/settings.json, make
sure jq is installed, and show me a test render.

Manual Install

1. Copy the script to your Claude directory:

mkdir -p ~/.claude
curl -o ~/.claude/statusline-command.sh https://github.com/inspiretelapps/claude-code-statusline/main/statusline-command.sh
chmod +x ~/.claude/statusline-command.sh

2. Add to your Claude Code settings (~/.claude/settings.json):

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

3. Restart Claude Code to see the statusline.

How It Works

The script receives JSON on stdin from Claude Code containing:

• Workspace info (project directory)
• Model info and effort level
• Context window usage and size
• Session token counts
• Rate limit usage (Claude Code v2.1+)

On Claude Code v2.1+ the rate limits come straight from that stdin JSON, so no network call is needed. On older versions the script falls back to fetching usage from Anthropic's OAuth endpoint, with a 60-second cache in ~/.claude/cache/ to avoid excessive API calls.

That fallback reads whichever credential store the platform uses — the login Keychain on macOS, or ~/.claude/.credentials.json on Linux. Both hold the same claudeAiOauth.accessToken value, so one code path covers both.

If no usage figures are available from either source, the Left: segment is omitted rather than shown as 100%.

Why there is no token refresh

OAuth access tokens expire after roughly 8 hours, so an earlier attempt at this (branch fix/token-refresh-and-keychain-lookup) refreshed them against platform.claude.com. That approach was deliberately dropped:

• It is near-dead code. On Claude Code v2.1+ the rate limits arrive over stdin and fetch_usage never runs at all.
• No negative cache. A refresh failure isn't cached, so every subsequent render re-POSTs to the OAuth endpoint — and the statusline renders constantly. Testing this reliably returned HTTP 429 rate_limit_error.
• Refresh-token rotation can break your login. If the server rotates the refresh token, either the script writes it back to the credential store (racing Claude Code's own refresh, risking a corrupted live login) or it doesn't (leaving Claude Code holding a stale token). Neither is worth a cosmetic statusline segment.

An expired token simply means the usage segments are omitted until Claude Code refreshes its own credentials, which it does on its own schedule.