claude-statusline

A rich statusline for Claude Code — pure bash, no Node.js required.

English · 한국어

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

  Fable 5 high ✦ │ ctx 14% ● ○ ○ ○ ○ 143.5K/1M │ oss-qraft (main) │ PR #42 ✓ │ $50.07 · 2h 3m · ~$24/hr +1036 -49
  Smart   ● ● ● ● ● ● ● ● ● ● ● 119% used  143.5K/120K zone
  Session ● ● ● ● ● ● ● ● ○ ○  83% left  Resets in 1h 27m
  Weekly  ● ● ● ● ● ● ● ● ○ ○  83% left  Resets in 3d 23h
  Sonnet  ● ● ● ● ● ● ● ● ● ○  95% 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 + badges (⚡ fast mode, effort level, ✦ thinking, ◑ output style, ⛭ agent), context % with mini-bar and token count (143.5K/1M, marked ⚠200k+ past the premium threshold), project, git branch + dirty + ↑ahead ↓behind, PR # + review state (clickable), session cost · duration · ~$/hr burn rate, lines +/-, optional session name
Compaction Warning	Red warning when context exceeds critical threshold
Smart Zone	How much of the ~120k-token span the model still reasons sharply over has been used — the number a 1M window hides. Gauge + % used + tokens/zone
Rate Limits	Session (5h) / Weekly (7d) / per-model buckets (Opus, Sonnet, Fable, … auto-detected) / Extra usage — 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

Header badges

Badge	Meaning
`⚡fast`	Fast mode enabled
`high`	Reasoning effort level (low/medium/high/max)
`✦`	Extended thinking enabled
`◑explanatory`	Active output style (only when not `default`)
`⛭security-reviewer`	Active agent (during `--agent` sessions)
`⚠200k+`	Past the 200k premium long-context billing threshold (>200k-window models only)
`PR #42 ✓`	Open PR — ✓ approved · ● pending · ✗ changes requested · ◌ draft
`+1036 -49`	Lines added/removed this session

Badges only appear when the data exists — e.g. ⚡fast shows only with fast mode on, PR #42 only while a PR is open.

Per-model rate limit buckets

Model-specific weekly buckets are auto-detected from the OAuth usage API — whatever buckets Anthropic reports for your plan show up automatically, so new models appear without a script update. They are ordered by model capability (most capable first, Fable > Opus > Sonnet > Haiku), and buckets the API reports as null (inactive for your plan) are hidden. An Extra gauge appears when extra usage credits are enabled on your account.

Note: which buckets exist depends on your plan and usage. A bucket only appears once that model has tracked usage — most accounts see just one (e.g. Sonnet, as above); Opus shows once you've used Opus. When more than one is active they sort by capability, and any new model Anthropic adds appears automatically — no update needed.

Color coding

	Green	Yellow	Red
Context	< 30%	30–70%	> 70%
Rate limit	> 50% left	20–50% left	< 20% left

Installation

Plugin (recommended)

/plugin marketplace add JungHoonGhae/claude-statusline
/plugin install claude-statusline@claude-statusline

Auto-setup on every session start — scripts stay up to date with the plugin.

Shell

curl -fsSL https://raw.githubusercontent.com/JungHoonGhae/claude-statusline/main/install-remote.sh | bash

Other methods

Clone & install

git clone https://github.com/JungHoonGhae/claude-statusline.git
cd claude-statusline
bash install.sh

Manual

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
cp statusline.conf.example ~/.claude/statusline.conf

Add to ~/.claude/settings.json:

{
  "statusLine": {
    "type": "command",
    "command": "bash ~/.claude/statusline-command.sh"
  }
}

Prerequisites

jq and curl — the installers auto-install these via your package manager (brew / apt / dnf / yum / pacman / apk)

The token cost section is pure bash + jq (no Node.js). It reads Claude Code's local transcripts directly and prices them with per-model rates from LiteLLM's pricing database — fetched once a day via curl and cached. Offline or without curl, a built-in price table keeps the section working.

If a dependency goes missing later (e.g. after a container restart), the statusline shows an install hint instead of silently hiding the section.

Configuration

Edit ~/.claude/statusline.conf to customize:

# Toggle sections
SHOW_RATE_LIMITS=true
SHOW_TOOLS=true
SHOW_AGENTS=true
SHOW_CCUSAGE=true

# Header extras
SHOW_CONTEXT_BAR=true
SHOW_BURN_RATE=true
SHOW_GIT_AHEAD=true
SHOW_LINKS=true
SHOW_SESSION_NAME=false

# Context thresholds
CONTEXT_WARN_PCT=30       # Yellow warning
CONTEXT_CRIT_PCT=70       # Red + compaction warning
SMART_ZONE_TOKENS=120000  # Size of the "Smart" row's zone (0 = hide the row)

# Budget alert (0 = disabled)
DAILY_BUDGET=0

Option	Default	Description
`SHOW_RATE_LIMITS`	`true`	Session/weekly/per-model rate limit bars
`SHOW_TOOLS`	`true`	Tool activity from transcript
`SHOW_AGENTS`	`true`	Agent activity from transcript
`SHOW_CCUSAGE`	`true`	Daily/monthly token cost stats
`SHOW_CONTEXT_BAR`	`true`	Small 5-dot gauge next to ctx %
`SHOW_BURN_RATE`	`true`	~$/hr spend rate in the header
`SHOW_GIT_AHEAD`	`true`	↑ahead ↓behind vs upstream
`SHOW_LINKS`	`true`	Clickable PR link (OSC 8; auto-off in tmux)
`SHOW_SESSION_NAME`	`false`	Show the `/rename` session name in the header
`CONTEXT_WARN_PCT`	`30`	Context % threshold for yellow
`CONTEXT_CRIT_PCT`	`70`	Context % threshold for red + compaction warning
`SMART_ZONE_TOKENS`	`120000`	Smart-zone size for the `Smart` row — the span the model still reasons sharply over, far below a 1M window (`0` = hide the row)
`DAILY_BUDGET`	`0`	Daily budget alert in USD (0 = disabled)

Every option can be set in the conf file or as an environment variable (the conf file takes precedence). The statusline also auto-compacts its layout on narrow terminals using $COLUMNS.

See statusline.conf.example for a fully commented template.

vs claude-hud

	claude-statusline	claude-hud
Type	Pure bash scripts	Node.js/TypeScript plugin
Install	Plugin marketplace, one-liner `curl`, or copy 2 files	Plugin marketplace
Dependencies	`jq` only	Node.js 18+
Rate limits	stdin + OAuth API (model-specific + extra usage)	stdin only
Token costs	Daily/monthly (transcripts + LiteLLM pricing)	—
Budget alert	Configurable daily limit	—
Compaction warning	Context threshold alert	—
Configuration	Simple KEY=value conf file	JSON config + `/configure` command
Platform	macOS, Linux, Windows (Git Bash/WSL)	Cross-platform

How it works

Claude Code stdin (JSON)
  ├── model, effort, thinking, fast_mode, context_window, cost, pr, transcript_path
  └── rate_limits (v2.1.6+)     ← Session/Weekly from stdin
          │
statusline.sh
  ├── stdin rate_limits            Primary source
  ├── OAuth API (cached 2m)        Fallback + per-model buckets (auto-detected) + extra usage
  ├── git CLI                      Branch & dirty state (stdin no longer carries .git)
  ├── Transcript JSONL parsing     Tool & agent activity
  └── ccusage-cache.sh (bg, 10m)  Token cost aggregation (bash+jq, LiteLLM pricing)
          │
stdout → Claude Code displays

Data	Source	Cache
Context / model / effort / PR / cost	stdin (native)	—
Session & Weekly limits	stdin `rate_limits`	—
Per-model limits (Opus/Sonnet/Fable/…), extra usage	OAuth API	2 min
Git branch & dirty state	`git` CLI (stdin fallback)	—
Tool & agent activity	Transcript JSONL	—
Token costs	Transcript JSONL + LiteLLM pricing	10 min (background)

Troubleshooting

Statusline goes blank after a Docker/devcontainer restart

A container restart resets the container filesystem to the image — only mounted volumes (e.g. ~/.claude) survive. If jq was installed inside the running container, it disappears and the statusline stops rendering. Bake the dependencies into your image:

# Debian/Ubuntu
RUN apt-get update && apt-get install -y jq curl git
# Alpine
RUN apk add --no-cache jq curl git bash

Since v1.2.2 the statusline shows claude-statusline: jq not found instead of silently going blank.

Token cost section missing

The Today/Yesterday/Last 30 Days section needs jq and Claude Code's local transcripts under ~/.claude/projects. When it can't run, the statusline shows a dim ✗ ccusage: ... hint with the reason. The cache refreshes in the background, so the section can take one ~10s refresh cycle to appear after install. Pricing is fetched from LiteLLM via curl and cached for a day; without curl (or offline) a built-in price table is used instead.

Platform support

Works on macOS, Linux, and Windows (Git Bash / WSL).

macOS: OAuth token from Keychain (security command)
Linux: OAuth token from ~/.claude/.credentials.json or GNOME Keyring (secret-tool)
Windows: OAuth token from ~/.claude/.credentials.json or %APPDATA%/Claude/credentials.json

Changelog

See CHANGELOG.md for the full version history. Recent highlights:

1.5.0 — premium long-context ⚠200k+ marker, output-style and agent badges, Korean README
1.4.1 — responsive 3-tier layout ($COLUMNS-aware), idle label for unused buckets, accurate screenshot
1.4.0 — header extras: context bar, ~$/hr burn rate, git ↑ahead ↓behind, clickable PR link
1.3.0 — auto-install dependencies, surface every silent failure, capability-ordered model buckets
1.2.x — auto-detected per-model rate buckets, ccusage v18 compatibility
1.1.0 — v2.1.x stdin support: model badges, context tokens, PR badge, lines +/-

Contributing

Contributions are welcome! See CONTRIBUTING.md for how to test changes and the project guidelines. By participating you agree to the Code of Conduct. To report a security issue, see the Security Policy.

Credits

Inspired by jarrodwatts/claude-hud. Token cost tracking inspired by ryoppippi/ccusage; per-model pricing from LiteLLM.

Support

If this helped your workflow, consider buying me a coffee.

License

MIT

Name		Name	Last commit message	Last commit date
.claude-plugin		.claude-plugin
.github		.github
hooks		hooks
scripts		scripts
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.ko.md		README.ko.md
README.md		README.md
SECURITY.md		SECURITY.md
ccusage-cache.sh		ccusage-cache.sh
install-remote.sh		install-remote.sh
install.sh		install.sh
screenshot.png		screenshot.png
statusline.conf.example		statusline.conf.example
statusline.sh		statusline.sh

Navigation Menu

Repository files navigation

claude-statusline

Why?

What it shows

Header badges

Per-model rate limit buckets

Color coding

Installation

Plugin (recommended)

Shell

Clone & install

Manual

Prerequisites

Configuration

vs claude-hud

How it works

Troubleshooting

Statusline goes blank after a Docker/devcontainer restart

Token cost section missing

Platform support

Changelog

Contributing

Credits

Support

License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

claude-statusline

Why?

What it shows

Header badges

Per-model rate limit buckets

Color coding

Installation

Plugin (recommended)

Shell

Clone & install

Manual

Prerequisites

Configuration

vs claude-hud

How it works

Troubleshooting

Statusline goes blank after a Docker/devcontainer restart

Token cost section missing

Platform support

Changelog

Contributing

Credits

Support

License

About

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages