claude-statusline
A rich statusline for Claude Code — pure bash, no Node.js required.
Install · Features · Config · How it works · vs claude-hud
Why?
The default Claude Code statusline only shows the model name and cost. You don't know:
- How much context you've used until compaction hits
- How close you are to rate limits
- What tools/agents are running in the background
- How much you've spent today, this week, or this month
Even on Max plan where cost isn't a concern, tracking your token usage helps you understand your usage patterns and optimize your workflow.
This statusline fixes all of that.
What it shows
Opus 4.6 (1M context) │ ctx 44% │ oss-qraft (main) │ $50.07 · 2h 3m
Session ● ● ● ● ● ● ● ● ○ ○ 83% left Resets in 1h 27m
Weekly ● ● ● ● ● ● ● ● ○ ○ 83% left Resets in 3d 23h
Sonnet ● ● ● ● ● ● ● ● ● ● 100% left Resets in 4d 15h
✓ Bash×40 ✓ Edit×19 ✓ Read×12 ✓ Write×11 ✓ Grep×2
◐ Explore Explore current Qraft codebase
─────────────────────────────────────────────
Today $227.00 · 264.5M tokens
Yesterday $101.77 · 111.7M tokens
Last 30 Days $3449.66 · 3.9B tokens
| Section | Details |
|---|---|
| Header | Model, context % (color-coded), project, git branch, session cost & duration |
| Compaction Warning | Red warning when context exceeds critical threshold |
| Rate Limits | Session (5h) / Weekly (7d) / Opus / Sonnet — gauge bar + % left + reset time |
| Tool Activity | Running tools, completed tool counts, active agents |
| Token Costs | Today / Yesterday / Last 30 days — cost & token count |
| Budget Alert | Red warning when daily spending exceeds configured limit |
Color coding
| Green | Yellow | Red | |
|---|---|---|---|
| Context | < 30% | 30–70% | > 70% |
| Rate limit | > 50% left | 20–50% left | < 20% left |
Installation
Plugin install (recommended)
/plugin marketplace add JungHoonGhae/claude-statusline
/plugin install claude-statusline@claude-statusline
Auto-setup on every session start — no manual config needed.
One-liner install
curl -fsSL https://raw.githubusercontent.com/JungHoonGhae/claude-statusline/main/install-remote.sh | bash
Clone & install
git clone https://github.com/JungHoonGhae/claude-statusline.git
cd claude-statusline
bash install.sh
Manual install
# 1. Copy scripts
cp statusline.sh ~/.claude/statusline-command.sh
cp ccusage-cache.sh ~/.claude/ccusage-cache.sh
chmod +x ~/.claude/statusline-command.sh ~/.claude/ccusage-cache.sh
# 2. Copy default config
cp statusline.conf.example ~/.claude/statusline.conf
Add to ~/.claude/settings.json:
{
"statusLine": {
"type": "command",
"command": "bash ~/.claude/statusline-command.sh"
}
}
Restart Claude Code.
Prerequisites
- jq —
brew install jq(macOS) /sudo apt install jq(Linux) - curl — pre-installed on most systems
- ccusage (optional) —
npm install -g ccusagefor token cost tracking
Configuration
Edit ~/.claude/statusline.conf to customize:
# Toggle sections
SHOW_RATE_LIMITS=true
SHOW_TOOLS=true
SHOW_AGENTS=true
SHOW_CCUSAGE=true
# Context thresholds
CONTEXT_WARN_PCT=30 # Yellow warning
CONTEXT_CRIT_PCT=70 # Red + compaction warning
# Budget alert (0 = disabled)
DAILY_BUDGET=0