claude-status 0.4.2

Beautiful, informative status line for Claude Code — zero dependencies, cross-platform

claude-status

Zero-dependency status line for Claude Code. One command. Every metric. All platforms.

Line 1:  [████████░░░░░░░░░░░░] │ in:245K out:18K │ cache:41% │ $0.73 │ burn:37K/min
Line 2:  5h:34% 7d:18% ~2h │ (200K) │ 12m05s │ +247 -38 │ ⎇ myapp/feat/statusline │ ✦ refactor auth │ Opus │ effort:high │ v0.4.2 │ CC:2.1.92 │ 15:30

30-Second Setup

pip install claude-status
claude-status --setup

The setup wizard walks you through theme selection, budget configuration, and installs everything automatically. Restart Claude Code and you're done.

Why claude-status?

• Zero dependencies — pure Python stdlib. No psutil, no colorama, no compilation. Installs in under 2 seconds
• Every metric that matters — 27+ data points including burn rate (tokens/min), rate limit tracking, and effort level
• Rate limit awareness — see your 5-hour and 7-day API usage at a glance with color-coded warnings and reset countdown
• Responsive layout — automatically adapts to your terminal width (full/compact/narrow)
• 8 built-in themes — default, minimal, powerline, nord, tokyo-night, gruvbox, rose-pine, focus
• Budget monitoring — set a daily spend limit, get color-coded warnings as you approach it
• Session analytics — tool call count and today's session count at a glance
• Cross-platform — tested on Windows, macOS, and Linux across Python 3.8–3.14 (21 CI jobs)
• Interactive setup — --setup wizard walks you through theme selection and budget config
• Clean uninstall — --uninstall restores your previous configuration

Features

Line 1 — Metrics at a Glance

Feature	What You See	Why It Matters
Context Bar	[████████░░░░░░░░░░░░]	Green/yellow/red adaptive — know your context budget instantly
Token Counts	in:245K out:18K	Human-readable (K/M) — no squinting at raw numbers
Cache Efficiency	cache:41%	See how much prompt cache is saving you
Cost	$0.73	Session cost in real-time — cents for small, dollars for large
Budget	$0.73/$10	Color-coded daily budget tracker (green/yellow/red)
Burn Rate	burn:37K/min	Tokens/min consumption — unique to claude-status
Rate Limits	5h:34% 7d:18% ~2h	API usage limits with reset countdown (Pro/Max only)
Context Size	(200K)	Know if you're on 200K or 1M context
Context Warning	!CTX	Bold red alert at 85%+ context usage

Line 2 — Session Context

Feature	What You See	Why It Matters
Duration	12m05s	Wall-clock session time
API Latency	api:5m12s	Time spent in API calls
Lines Changed	+247 -38	Git-diff style — green additions, red removals
Git Branch	⎇ myapp/feat/statusline	Project name + branch, color-coded
Git Stash	stash:2	Number of stashed changes
Git Sync	sync:+2/-1	Commits ahead/behind remote
Git Worktree	gwt	Indicator when inside a native git worktree
Tool Calls	tools:42	Number of tool calls in current session
Sessions Today	sessions:3	How many sessions you've started today
Session Name	✦ refactor auth	Custom session name (via --name or /rename)
Vim Mode	NORMAL	Blue for NORMAL, green for INSERT
Agent	[Explore]	Shows which subagent is active
Worktree	wt:fix/bug-123	Claude Code worktree branch indicator
Model	Opus	Active model name
Output Style	style:explanatory	Active output style when set
Added Dirs	dirs:+2	Extra directories added via /add-dir
Effort Level	effort:high	Thinking effort (shown when non-default)
Version	v0.4.2	claude-status version
CC Version	CC:2.1.92	Claude Code application version
Clock	15:30	Current time

Themes

8 built-in themes to match your terminal aesthetic. Preview all live with claude-status --demo.

default — full detail, clean separators

[████████░░░░░░░░░░░░] │ in:245K out:18K │ cache:41% │ $0.73 │ burn:37K/min
5h:34% 7d:18% ~2h │ (200K) │ 12m05s │ +247 -38 │ ⎇ myapp/feat/statusline │ ✦ refactor auth │ Opus │ effort:high │ v0.4.2 │ CC:2.1.92 │ 15:30

minimal — just the essentials

●●●●●●●●·············· in:245K out:18K $0.73 5h:34% 7d:18%
12m05s ⎇ feat/statusline sessions:3 Opus 15:30

powerline — Nerd Font separators

████████░░░░░░░░░░░░  in:245K out:18K  cache:41%  $0.73  burn:37K/min
5h:34% 7d:18% ~2h  (200K)  12m05s  +247 -38  ⎇ myapp/feat/statusline  ✦ refactor auth  Opus  effort:high  v0.4.2  CC:2.1.92  15:30

focus — single line, minimal footprint

[████████░░░░] │ $0.73 │ 5h:34% 7d:18% ~2h │ ⎇ main │ effort:high │ 15:30

nord — cool blue tones

tokyo-night — purple and blue accents

gruvbox — warm retro palette

rose-pine — soft muted pinks

Installation

pip (recommended)

pip install claude-status
claude-status --setup

pipx (isolated — no venv pollution)

pipx install claude-status
claude-status --setup

uvx (fast, modern)

uvx claude-status --setup

From source (contributors)

git clone https://github.com/mkalkere/claude-statusline.git
cd claude-statusline
pip install -e .
claude-status --setup

What --setup does

Walks you through theme selection with a compact preview, optional budget configuration, and writes the statusLine entry to ~/.claude/settings.json. Preserves all your existing settings.

Command not found? Ensure your Python scripts directory is in PATH. Fallback: python -m claude_statusline --setup

CLI Reference

Command	Description
claude-status --setup	Interactive setup wizard (recommended for first use)
claude-status --install	Auto-configure Claude Code settings
claude-status --install --theme nord	Install with a specific theme
claude-status --uninstall	Remove from Claude Code settings (restores previous config)
claude-status --demo	Preview all 8 themes with sample data
claude-status --doctor	Diagnostics: Python version, OS, terminal, current settings
claude-status --version	Show version
claude-status --help	Show usage

Budget Monitoring

Set a daily spending limit to get color-coded warnings as you approach it:

claude-status --setup  # interactive wizard sets this up for you

Or manually create ~/.claude/claude-status-budget.json:

{
  "daily_budget_usd": 10.00,
  "compaction_threshold_pct": 62
}

Budget thresholds:

• Green: under 70% of budget
• Yellow: 70–90% of budget
• Red (bold): 90%+ of budget

Compaction threshold: When set, the context bar scales relative to the compaction point instead of the full context window. At 62%, the bar shows 100% when you reach 62% of the context window — the point where compaction triggers.

Periodic Updates

By default, the status line updates after each assistant message. Add refreshInterval to your config for periodic updates — this keeps the clock, session count, and rate limit countdown current:

{
  "statusLine": {
    "type": "command",
    "command": "claude-status --theme default",
    "refreshInterval": 10
  }
}

This runs the status line every 10 seconds in addition to the standard update triggers.

Responsive Layout

The status line automatically adapts to your terminal width:

• 120+ columns: full detail (all sections)
• 80–119 columns: compact (drops extras like git stash, version, clock, rate limits)
• Under 80 columns: narrow (essentials only — bar, tokens, cost, duration, branch)

Manual Configuration

Add to ~/.claude/settings.json:

{
  "statusLine": {
    "type": "command",
    "command": "claude-status",
    "refreshInterval": 10
  }
}

With a theme:

{
  "statusLine": {
    "type": "command",
    "command": "claude-status --theme focus",
    "refreshInterval": 10
  }
}

How It Works

Claude Code pipes session JSON to your statusLine command via stdin on every render cycle (and every refreshInterval seconds if configured). claude-status parses it, formats 27+ metrics across up to 2 lines, and prints to stdout. No daemon, no database, no background process — just a pure stdin-to-stdout pipe that runs in milliseconds.

FAQ

Does this work on Windows? Yes! Fully tested on Windows 11, macOS, and Linux across Python 3.8–3.14.

Can I customize the colors? Yes — use --theme custom with a ~/.claude/claude-status-theme.json file. Override any color or layout from the built-in themes.

How does budget monitoring work? Create ~/.claude/claude-status-budget.json with {"daily_budget_usd": 10.00}. The cost indicator turns yellow at 70% and red at 90% of your daily limit.

What is burn rate? Tokens consumed per minute. Helps you gauge how fast you're using context in a session.

Do I need a Pro/Max subscription for rate limit tracking? Yes. The rate_limits field is only included in the Claude Code JSON payload for Pro/Max subscribers. The section is automatically hidden for other users — no configuration needed.

How often does the status line update? By default, after each assistant message. Add "refreshInterval": 10 to your statusLine config for periodic updates every 10 seconds — recommended for keeping the clock and rate limit countdown current.

Can I use a single-line layout? Yes — use the focus theme: claude-status --install --theme focus. It shows only the essentials on one line.

Why is only Line 1 showing / Line 2 is missing? This is a known Claude Code rendering limitation where long Line 1 output causes Line 2 to be silently dropped. We've optimized all multi-line theme layouts to keep Line 1 short, but if you still see this, try the focus theme (claude-status --install --theme focus) for a guaranteed single-line display, or widen your terminal to 130+ columns.

Does it add any latency to Claude Code? No. It runs as a pure stdin-to-stdout pipe in single-digit milliseconds. No daemon, no network calls, no background processes.

Why does the session count seem low on Windows with WSL? Windows and WSL have separate ~/.claude/ directories, so sessions are counted independently. The status line shows sessions from the platform it's running on.

Troubleshooting

If claude-status doesn't appear after installation:

1. Run claude-status --doctor to check your setup
2. Verify ~/.claude/settings.json contains the statusLine entry
3. Ensure your Python scripts directory is in your PATH
4. Try python -m claude_statusline --setup as a fallback
5. Restart Claude Code after any configuration change

Uninstall

claude-status --uninstall

This removes the statusLine entry from your settings and restores your previous configuration if a backup exists. Then:

pip uninstall claude-status

Contributing

See CONTRIBUTING.md.

License

MIT