How to Show Claude Code Usage Limits in Your Statusline

Running /usage every time you want to check your Claude Code limits? There's a better way.

I created a script that displays my usage limits directly in my statusline, and it's been a game-changer. No more manual checks, no more guessing if I'm about to hit my limits.

Let me show you exactly how I built this.

What I Wanted to Achieve

Before diving into the code, here's what I wanted:

• See my 5-hour and 7-day usage limits at a glance
• Update automatically without manual intervention
• Display the data directly in my terminal statusline

Basically, I wanted this information always visible while coding:

Usage limits displayed directly in the statusline

Pretty clean, right?

The Investigation Process

Here's where things got interesting. I needed to figure out how Claude Code fetches this data.

Finding the API Endpoint with Proxyman

I opened Proxyman (a fantastic HTTP debugging tool for macOS) and monitored the network traffic while Claude Code was running.

After filtering through the requests, I found exactly what I needed:

The API request captured in Proxyman

The endpoint: https://api.anthropic.com/api/oauth/usage

Here's what the request looks like:

GET https://api.anthropic.com/api/oauth/usage
Accept: application/json, text/plain, */*
Content-Type: application/json
User-Agent: claude-code/2.0.32
Authorization: Bearer sk-ant-oat01-...
anthropic-beta: oauth-2025-04-20
Accept-Encoding: gzip, compress, deflate, br
Host: api.anthropic.com

And the response:

{
  "five_hour": {
    "utilization": 6.0,
    "resets_at": "2025-11-04T04:59:59.943648+00:00"
  },
  "seven_day": {
    "utilization": 35.0,
    "resets_at": "2025-11-06T03:59:59.943679+00:00"
  },
  "seven_day_oauth_apps": null,
  "seven_day_opus": {
    "utilization": 0.0,
    "resets_at": null
  },
  "iguana_necktie": null
}

Perfect! Now I had the data structure and the endpoint.

Getting the API Token

The next challenge was finding where Claude Code stores the API token.

I asked Claude Code itself (meta, I know), and it pointed me to macOS Keychain. Claude Code stores credentials under the name "Claude Code-credentials".

Here's how to retrieve it:

security find-generic-password -s "Claude Code-credentials" -w

This returns a JSON object containing the OAuth tokens:

{
  "claudeAiOauth": {
    "accessToken": "sk-ant-oat01-...",
    "refreshToken": "...",
    "expiresAt": 1234567890,
    "scopes": ["..."],
    "subscriptionType": "pro"
  }
}

Now I had everything I needed to build the script.

Building the Script

Let me break down the TypeScript code that makes this work:

Type Definitions

First, I defined the types for the API response:

export interface UsageLimits {
  five_hour: {
    utilization: number;
    resets_at: string | null;
  } | null;
  seven_day: {
    utilization: number;
    resets_at: string | null;
  } | null;
}

interface Credentials {
  claudeAiOauth: {
    accessToken: string;
    refreshToken: string;
    expiresAt: number;
    scopes: string[];
    subscriptionType: string;
  };
}

Getting Credentials from Keychain

Here's the function to retrieve the access token:

export async function getCredentials(): Promise<string | null> {
  try {
    const result =
      await $`security find-generic-password -s "Claude Code-credentials" -w`
        .quiet()
        .text();
    const creds: Credentials = JSON.parse(result.trim());
    return creds.claudeAiOauth.accessToken;
  } catch {
    return null;
  }
}

This uses Bun's shell syntax ($) to execute the security command and parse the result.

Fetching Usage Data

Now the core function that calls the Anthropic API:

export async function fetchUsageLimits(
  token: string,
): Promise<UsageLimits | null> {
  try {
    const response = await fetch("https://api.anthropic.com/api/oauth/usage", {
      method: "GET",
      headers: {
        Accept: "application/json, text/plain, */*",
        "Content-Type": "application/json",
        "User-Agent": "claude-code/2.0.31",
        Authorization: `Bearer ${token}`,
        "anthropic-beta": "oauth-2025-04-20",
        "Accept-Encoding": "gzip, compress, deflate, br",
      },
    });

    if (!response.ok) {
      return null;
    }

    const data = await response.json();

    return {
      five_hour: data.five_hour || null,
      seven_day: data.seven_day || null,
    };
  } catch {
    return null;
  }
}

That's it! The core logic is simple:

1. Get the token from Keychain
2. Call the API with proper headers
3. Return the usage data

The Result

Now I can see my usage limits at all times without running any commands:

• No need to type /usage anymore
• Always aware of my API consumption
• Zero impact on my workflow

The statusline shows me exactly where I'm at with my limits, and it works perfectly.

Install It Yourself

Want the same setup? You can install it using:

pnpm dlx aiblueprint-cli claude-code statusline

This will set up the statusline script with usage limits display automatically.

Conclusion

This is exactly the kind of improvement that makes daily development smoother. Instead of context-switching to check limits, the information is always there.

The investigation process was fun - using Proxyman to reverse-engineer the API calls, discovering how Claude Code stores credentials in Keychain, and building the script.

If you're using Claude Code regularly, add this to your setup. It's one of those small changes that compounds over time.

What other Claude Code improvements would you like to see? Let me know on Twitter!