claude-code-statusline-alansauce

claude-code-statusline-alansauce

An adaptive statusline for Claude Code that shows everything you need at a glance. Renders 2 lines on wide terminals, 4 lines on narrow ones.

What it shows

Line 1 - Identity, Context, and Config

alan:~/Codin/Tools/claude-code-statusline-alansauce [Opus 4.6 (1M context)] ctx:5% 48k/1000k

Component	Example	Description
User	alan	System username from $USER. Bold cyan.
Working directory	~/Codin/Tools/...	Project path with $HOME abbreviated to ~.
Model	[Opus 4.6 (1M context)]	Active Claude model. Yellow brackets.
Context usage %	ctx:5%	Context window consumed. Green (<50%), yellow (50-79%), bold red (80%+).
Context tokens	48k/1000k	Current tokens vs. window size. Includes input, output, cache creation, and cache read. Rounded up to nearest thousand.

On wide terminals, config counts appear on line 1. On narrow terminals they get their own line:

Component	Example	Description
CLAUDE.md count	1 CLAUDE.md	Files detected across all scopes: ~/.claude/CLAUDE.md, ./CLAUDE.md, ./CLAUDE.local.md, ./.claude/CLAUDE.md, ./.claude/CLAUDE.local.md.
Rules count	4 Rules	Total .md files in ~/.claude/rules/ (global) and ./.claude/rules/ (project).
MCPs count	2 MCPs	Enabled MCP servers. Counts keys in mcpServers from ~/.claude.json (user) and ./.mcp.json (project), minus any listed in disabledMcpServers or disabledMcpjsonServers.
Hooks count	1 Hooks	Hook event types from ~/.claude/settings.json, ./.claude/settings.json, and ./.claude/settings.local.json.

Line 2 - Usage Limits, Session, and Git

5hr: 11% (resets 2h 52m) | weekly: 67% (resets 1d 6h) | Session:2m34s | (main)

Component	Example	Description
5-hour usage	5hr: 11% (resets 2h 52m)	Rolling 5-hour rate limit utilization from the Anthropic OAuth API. Blue. Shows "N/A" for API key users.
Weekly usage	weekly: 67% (resets 1d 6h)	Rolling 7-day rate limit utilization. Magenta. Shows "N/A" for API key users.
Session duration	Session:2m34s	Time since session start. Uses total_duration_ms when available, falls back to transcript file birth time. Green.
Git branch	(main)	Current branch, "detached", or "(not a git repo)". Yellow.
Git file status	[Committed:2,Staged:5,Edited:36]	Bracketed file change summary. Only non-zero categories appear. Hidden when clean.

Git status categories:

Label	What it means
Committed:N	Files staged in the index (git diff --cached)
Staged:N	Tracked files modified but not staged (git diff)
Edited:N	Untracked files not in .gitignore (git ls-files --others)

Adaptive Layout

The statusline measures its content against terminal width. When everything fits, it renders 2 lines. When the terminal is narrow, it expands to 4 lines to avoid truncation.

API Caching

Usage API responses are cached in /tmp/claude/statusline-usage-cache.json with a 5-minute TTL. Writes are atomic (mktemp + mv). If the API fails (429, timeout), the statusline falls back to stale cache with a [cached] indicator.

Installation

Manual Installation

1. Clone this repo:

   git clone https://github.com/weihaog1/claude-code-statusline-alansauce.git ~/.claude/plugins/claude-code-statusline-alansauce
   

2. Add to ~/.claude/settings.json:

   {
     "statusLine": {
       "type": "command",
       "command": "bash ~/.claude/plugins/claude-code-statusline-alansauce/statusline.sh",
       "padding": 0
     }
   }
   

3. Restart Claude Code.

Dependencies

• bash (4.0+)
• jq - JSON parsing
• curl - usage API
• git - branch/status display
• bc - context percentage color thresholds

Installing jq

Platform	Command
macOS	brew install jq
Debian/Ubuntu	sudo apt install jq
Fedora	sudo dnf install jq
Arch	sudo pacman -S jq

Platform Support

Currently macOS-only. Credentials are read from the macOS Keychain via the security command.

License

MIT