Claude Code Statusbar

A configurable statusbar for Claude Code that keeps you informed without breaking your flow.

● Claude Opus 4.7  5hr:███░░░░░░░ 31%  ctx:████░░░░░░ 42%  Code/myproject   main !?

Why?

Claude Code doesn't show you how close you are to hitting rate limits or running out of context window — two things that directly affect your session. You find out when it's too late: a rate limit error kills your momentum, or context gets compacted and Claude loses track of what you were doing.

This statusbar gives you a persistent, at-a-glance view of:

• Rate limits — so you can pace yourself or wrap up before you're throttled
• Context window — so you know when to /compact or start a new session
• Model, directory, branch — so you always know where you are
• Git status indicators — modified, staged, untracked, ahead/behind, and more
• VPN indicator (optional, macOS) — see at a glance whether your VPN is connected

It's configurable — choose which segments to show, customize labels and bar styles, display as "used" or "remaining", and pick your own color scheme.

Install

npx github:ashbrener/claude-code-statusbar

Restart Claude Code to see your statusbar.

Configure

Option 1: Inside Claude Code (recommended)

The installer also drops a /statusbar skill into ~/.claude/skills/. After restarting Claude Code, just type:

/statusbar

…to install, configure, reset, or uninstall interactively.

Option 2: From the terminal

npx github:ashbrener/claude-code-statusbar configure

You can choose:

Option	Choices
Segments	vpn, model, rate, context, directory, branch, thinking_stars (default set) plus opt-in thinking (mid-bar dot anchor) — pick which to show and in what order
Bar style	██░░ (default), ■■□□, ●●○○, ##--, or custom characters
Bar width	Number of characters (default: 10)
Directory	Relative to ~/ (default), absolute, or strip a custom prefix
Display mode	used (24% consumed) or remaining (76% available)
Color ramp	same (brightens in gauge color) or red (shifts to yellow/red)
Labels	Rename gauges — e.g. ctx → window, or override rate label
Thresholds	When bars change intensity (default: 50%/80%)

Configuration is saved to ~/.claude/statusbar-config.json. Without a config file, the default style is used.

Example configs

Minimal — model + context only:

{
  "segments": ["model", "context"]
}

Dots with tight thresholds:

{
  "segments": ["model", "rate", "context", "branch"],
  "bar": { "filled": "●", "empty": "○", "width": 8 },
  "thresholds": { "warning": 40, "critical": 70 }
}

Everything including the opt-in dot anchor + wide bars:

{
  "segments": ["model", "rate", "context", "thinking", "directory", "branch", "thinking_stars"],
  "bar": { "filled": "█", "empty": "░", "width": 15 }
}

No thinking indicator (opt out):

{
  "segments": ["model", "rate", "context", "directory", "branch"]
}

What it shows

Segment	Source	Default Color
VPN	macOS scutil --nc list (◉ connected / ○ disconnected)	Green
Model	model.display_name, prefixed with ●	Cyan
Rate limit	Auto-detected window (five_hour→5hr, etc.)	Magenta
Context window	context_window.used_percentage	Blue
Directory	workspace.current_dir relative to $HOME	Dim
Git branch	Current branch with Nerd Font glyph + dirty-state indicators	Green
Thinking (stars)	1–5 asterisks indicating thinking-budget tier	Yellow ramp (see below)

Colors shift at configurable thresholds (default 50% yellow, 80% red).

Thinking-budget indicator

Claude Code triggers extended thinking when your prompt contains specific keywords. The statusbar surfaces the tier of the most recent prompt as thinking_stars — 1–5 asterisks rendered after the branch segment. Count + color encode intensity at a glance:

Latest prompt contains	Tier	Stars	Color
(no thinking keyword)	normal	*	Dim yellow
think	think	**	Bright yellow
think hard / think harder / think more	hard	***	Bright yellow
think really hard / think very hard / think a lot	high	****	Bright yellow
ultrathink / megathink	ultra	*****	Bold bright yellow

The tier is read fresh on every statusbar refresh by parsing the latest last-prompt event in the session transcript. No persistent state — each turn's keyword is reflected immediately.

Note: Until claude-code#23929 lands, Claude Code's statusLine JSON contract doesn't expose thinking budget directly — this segment works by parsing the transcript file path Claude Code already provides (transcript_path).

Optional: thinking (dot) segment

An additional thinking segment renders a single colored · (magenta ramp) at any chosen position in the bar — useful if you want the indicator anchored mid-bar instead of (or alongside) the right-edge stars. Opt-in via config:

{
  "segments": ["model", "rate", "context", "thinking", "directory", "branch", "thinking_stars"]
}

Git status indicators

When the working tree is dirty, the branch segment appends indicators:

Symbol	Meaning
+	Staged changes
!	Modified (unstaged)
?	Untracked files
✘	Deleted
×	Merge conflicts
⚑	Stashed changes
⇡	Ahead of upstream
⇣	Behind upstream
⇕	Diverged (both ahead and behind)

Example: main !+⇡ means you're on main with modified files, staged changes, and unpushed commits.

The branch glyph `` requires a Nerd Font. If you don't have one installed, edit scripts/statusbar.sh and swap it for `ᚦ` or `⎇`.

Uninstall

npx github:ashbrener/claude-code-statusbar uninstall

Uninstall restores your previous statusbar configuration if one existed before install.

How it works

The installer copies a bash script to ~/.claude/statusbar-command.sh and adds the statusLine config to ~/.claude/settings.json. Claude Code runs the script on each render, piping session JSON to stdin.

The script reads an optional ~/.claude/statusbar-config.json for customization, falling back to sensible defaults.

License

MIT