A Better Claude Code CLI Experience

If you're using Claude Code regularly, you've probably noticed the default CLI experience is pretty minimal. You get your conversation, but not much visibility into what's happening under the hood.

I wrote a small bash script that dramatically improves this by adding a rich statusline. Here's what mine looks like:

[Sonnet 4.5] Context: 0% | 5h: 8% → 3h22m | 7d: 6% → 5d23h | main

At a glance, I can see:

• Which model I'm using - Sonnet 4.5, Opus, Haiku, etc.
• Context window usage - How much of my 200K token budget I've used (color-coded: green/yellow/red)
• API rate limits - Both the 5-hour and 7-day rolling windows, with time until reset
• Current git branch - Always visible so I remember where I'm working

Why This Matters

When you're orchestrating multiple AI conversations throughout the day, these details matter:

API limits - The 5-hour window resets on a rolling basis. Knowing I'm at 8% with 3h22m until reset helps me decide whether to continue a conversation or switch to a different model/account.

Context usage - When you're at 85% context, you know the next big feature request might blow the window. Time to start fresh or summarize.

Git branch awareness - I can't count how many times I've started work in Claude only to realize later I'm on the wrong branch. Now it's right there.

Installation

The script is a Claude Code statusline hook. You can grab it from my GitHub Gist.

Requirements:

• jq (for JSON parsing) - install with brew install jq
• curl (for API requests) - built into macOS
• git (optional, for branch display) - built into macOS
• macOS (uses Keychain for OAuth tokens - would need tweaking for Linux)

Setup steps:

1. Download the script and save it to ~/.claude/statusline.sh
2. Make it executable: chmod +x ~/.claude/statusline.sh
3. Restart Claude Code - it will automatically pick up the statusline script

That's it! Claude Code automatically detects and runs ~/.claude/statusline.sh if it exists.

For more details on statusline hooks, see the official Claude Code documentation.

The script caches API usage data for 60 seconds to avoid rate limiting. Colors adjust automatically based on usage thresholds (green < 60%, yellow < 80%, red ≥ 80%).

The Details

The script does a few clever things:

1. OAuth token extraction - Pulls your Claude Code credentials from macOS Keychain to authenticate API requests
2. Smart caching - Fetches usage data from Anthropic's API but caches it locally to avoid hammering the endpoint
3. Human-readable time - Converts ISO timestamps to relative time ("3h22m", "5d23h")
4. Color coding - Uses ANSI escape codes to visually highlight high usage

It's about 230 lines of well-commented bash that just works.

Should You Use It?

If you're a casual Claude Code user who opens it once a week, probably not worth the setup.

But if you're like me—running multiple sessions daily, working across projects, orchestrating agent workflows—this little script has become indispensable. It's one of those quality-of-life improvements that seems minor until you try working without it.

Check out the full script on GitHub. Feel free to adapt it to your needs.

The Script

–Jeremy