Claude Code Statusline — Displaying Rate Limits and Building Custom Scripts

Visualize Your Usage with Claude Code's Statusline

When working in Claude Code for extended sessions, one question inevitably comes up: "How much of my rate limit have I used?" For Pro and Max plan subscribers, Claude enforces rolling 5-hour and 7-day usage windows, and hitting those limits mid-task can be frustrating.

Since Claude Code v2.1.80, the statusline feature now exposes a rate_limits field, letting you monitor your usage percentage and reset times in real time. This guide walks you through setting up the statusline, building custom scripts, and leveraging community tools to stay on top of your usage.

For a broader look at all Claude Code settings, check out our Claude Code settings.json Complete Guide.

What Is the Statusline?

The statusline is an information bar displayed at the bottom of your Claude Code terminal interface. By default, it shows the active model and token counts, but you can extend it with custom commands to display virtually anything.

Common information you can show includes:

Model name: The currently active model (Sonnet 4.6, Opus 4.6, etc.)
Token usage: Input/output token counts for the current session
rate_limits: 5-hour and 7-day window usage percentages and reset times
Git info: Current branch name and repository status
Custom data: Anything your script outputs

Basic Setup: Adding a Statusline to settings.json

Configure the statusline in your user settings at ~/.claude/settings.json:

{
  "statusLine": {
    "type": "command",
    "command": "echo 'Hello from statusline'"
  }
}

Adding this simple configuration causes Claude Code to run your command and display its output in the status bar.

Settings File Locations

Scope	Path	Purpose
User settings	`~/.claude/settings.json`	Personal customization
Project settings	`.claude/settings.json`	Project-specific config
Enterprise	`~/.claude/settings.d/*.json`	Organization policy distribution

The statusline is typically configured at the user level.

Working with the rate_limits Field

Starting with v2.1.80, Claude Code passes a rate_limits object to your statusline script via standard input as JSON. Here's the structure:

{
  "rate_limits": {
    "five_hour": {
      "used_percentage": 42.5,
      "resets_at": 1711540800
    },
    "seven_day": {
      "used_percentage": 15.3,
      "resets_at": 1712059200
    }
  }
}

Field Reference

five_hour.used_percentage: Usage within the 5-hour rolling window (0–100)
five_hour.resets_at: Reset timestamp (Unix epoch seconds)
seven_day.used_percentage: Usage within the 7-day window (0–100)
seven_day.resets_at: Reset timestamp (Unix epoch seconds)

This field is only available for Claude.ai subscribers (Pro/Max) and appears after the first API response in a session. It won't show up when using API keys directly.

Building Custom Statusline Scripts

Simple Bash Script

Let's start with a straightforward Bash script that displays rate limit information:

#!/bin/bash
# ~/.claude/statusline.sh
# Custom statusline script for Claude Code
 
# Read JSON data from stdin
INPUT=$(cat)
 
# Extract rate_limits with jq
FIVE_HOUR=$(echo "$INPUT" | jq -r '.rate_limits.five_hour.used_percentage // "N/A"')
SEVEN_DAY=$(echo "$INPUT" | jq -r '.rate_limits.seven_day.used_percentage // "N/A"')
MODEL=$(echo "$INPUT" | jq -r '.model // "unknown"')
 
# Convert reset time to human-readable format
RESETS_AT=$(echo "$INPUT" | jq -r '.rate_limits.five_hour.resets_at // 0')
if [ "$RESETS_AT" != "0" ] && [ "$RESETS_AT" != "null" ]; then
  RESET_TIME=$(date -d "@$RESETS_AT" '+%H:%M' 2>/dev/null || date -r "$RESETS_AT" '+%H:%M' 2>/dev/null)
else
  RESET_TIME="--:--"
fi
 
# Output the formatted statusline
echo "${MODEL} | 5h: ${FIVE_HOUR}% | 7d: ${SEVEN_DAY}% | Reset: ${RESET_TIME}"

Make it executable and register it in your settings:

chmod +x ~/.claude/statusline.sh

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

Node.js for a Richer Display

For more sophisticated formatting, a Node.js script gives you greater flexibility:

#!/usr/bin/env node
// ~/.claude/statusline.mjs
// Statusline with progress bars
 
import { createInterface } from 'readline';
 
const rl = createInterface({ input: process.stdin });
let data = '';
 
rl.on('line', (line) => { data += line; });
rl.on('close', () => {
  try {
    const info = JSON.parse(data);
    const parts = [];
 
    // Shortened model name
    const model = info.model || 'unknown';
    const shortModel = model.replace('claude-', '').replace('-4-6', '4.6');
    parts.push(shortModel);
 
    // Rate limits with progress bars
    if (info.rate_limits) {
      const fiveHour = info.rate_limits.five_hour;
      const sevenDay = info.rate_limits.seven_day;
 
      if (fiveHour) {
        const bar = makeBar(fiveHour.used_percentage);
        parts.push(`5h ${bar} ${fiveHour.used_percentage.toFixed(0)}%`);
      }
      if (sevenDay) {
        const bar = makeBar(sevenDay.used_percentage);
        parts.push(`7d ${bar} ${sevenDay.used_percentage.toFixed(0)}%`);
      }
    }
 
    // Token usage
    if (info.tokens) {
      const total = info.tokens.input + info.tokens.output;
      parts.push(`${(total / 1000).toFixed(1)}k tok`);
    }
 
    console.log(parts.join(' | '));
  } catch {
    console.log('statusline error');
  }
});
 
function makeBar(percentage) {
  const filled = Math.round(percentage / 10);
  const empty = 10 - filled;
  return '[' + '='.repeat(filled) + '-'.repeat(empty) + ']';
}

Expected output looks like this:

sonnet4.6 | 5h [====------] 42% | 7d [==--------] 15% | 12.3k tok

Quick Inline Configuration

If you prefer not to create a separate script file, you can use an inline command directly in settings.json:

{
  "statusLine": {
    "type": "command",
    "command": "jq -r '\"\\(.model // \"?\") | 5h: \\(.rate_limits.five_hour.used_percentage // 0 | round)% | 7d: \\(.rate_limits.seven_day.used_percentage // 0 | round)%\"'"
  }
}

This is great for quick experimentation, though external scripts are better suited for complex logic.

Community Tools Worth Exploring

The Claude Code community has built several polished statusline tools:

claude-powerline

Inspired by Vim's Powerline, this tool offers themed, color-coded statusline displays with rich customization options.

# Install
npm install -g claude-powerline
 
# Register in settings.json
# "command": "claude-powerline"

ccusage

A usage analytics and visualization tool that includes statusline integration for tracking your Claude Code consumption over time.

# Install
npm install -g ccusage
 
# See https://ccusage.com/guide/statusline for statusline setup

ClaudeCodeStatusLine (Rust)

A performant Rust-based tool by Daniel Barreto that displays model, tokens, rate_limits, and git information in real time.

# Install via cargo
cargo install --git https://github.com/daniel3303/ClaudeCodeStatusLine

For general strategies on managing rate limits, see our Rate Limits Best Practices guide.

What to Do When Approaching Rate Limits

When your statusline shows usage climbing, here are practical strategies to stay productive:

1. Switch Models

Switching from Opus 4.6 to Sonnet 4.6 reduces rate limit consumption. Most coding tasks work perfectly well with Sonnet.

# Switch model mid-session
/model sonnet

2. Adjust Effort Levels

Use the --effort flag to control response depth. For simple queries, lower effort means fewer tokens consumed.

claude --effort low "What's the return type of this function?"

3. Split Long Sessions

Extended sessions accumulate context, increasing token consumption per request. Starting fresh sessions periodically helps manage your rate limit budget more effectively.

For deeper optimization techniques, see Mastering Claude Code's Effort Settings.

Looking back

Claude Code's statusline is a small configuration change that delivers a significant improvement to your development workflow. Real-time rate_limits visibility helps you plan your work sessions, avoid unexpected interruptions, and make informed decisions about model selection and effort levels.

Start with a simple inline command, graduate to a Bash or Node.js script as your needs grow, and explore community tools when you want a polished, ready-made solution. The key is making your usage data visible so you can code with confidence.