claude-status

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

Try it now — no install, no config change:

uvx claude-status --demo    # or: pipx run claude-status --demo

Line 1:  [████████░░░░░░░░░░░░] │ in:412K out:18K │ cache:46% │ $0.73 │ burn:66K/min │ 5h:34% 7d:18% ~2h00m │ (1M) │ tools:42 │ sessions:3 │ v0.17.0 │ CC:2.1.197 │ 15:30
Line 2:  12m05s │ api:5m12s │ speed:2.6K/s │ +247 -38 │ ⎇ myapp/feat/statusline │ last:5m00s │ ✦ refactor auth │ Sonnet 5 │ style:explanatory │ dirs:+1 │ effort:high

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 — 30+ 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), and on wide terminals moves sections that don't fit on Line 2 into the room left on Line 1 instead of hiding them
• NO_COLOR / FORCE_COLOR support — respects terminal color standards
• Clickable git branch (opt-in) — OSC 8 links open repo in browser in iTerm2, Kitty, WezTerm. Off by default because Claude Code's TUI doesn't understand OSC 8 and would drop Line 2. Enable with "clickable_links": true.
• Per-section toggle — disable any section via config without a custom theme
• 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

The two tables below list each section under the line it belongs to. On a wide terminal, a Line 2 section that doesn't fit there can appear at the end of Line 1 instead — see Using the room on Line 1.

Line 1 — Metrics at a Glance

Line 2 — Session Context

Per-Subagent Status Rows (v0.13.0+)

When Claude Code runs subagents, its subagentStatusLine hook lets a command render each task's row in the agent panel. claude-status serves both hooks from one binary — add this next to your existing statusLine entry (same command, plus --subagent):

"subagentStatusLine": {"type": "command", "command": "claude-status --subagent"}

Each running task then renders as:

[Explore] [███░░░░░] 41% · 23s · Sonnet 5

— task name, context usage (bar + percentage, colored with the same 60/85% bands as the main context bar), elapsed time, and model. Segments degrade independently and drop in a fixed order (model → bar → elapsed) on narrow panels; finished tasks keep Claude Code's default rendering. Uses your --theme if you pass the same one as your statusLine command.

Version notes: the per-task model and context fields require Claude Code 2.1.205+ — on older versions rows show [name] 23s. The subagentStatusLine setting's own minimum version isn't documented upstream; if an older Claude Code warns about an unknown settings key, remove the entry.

Themes

8 built-in themes to match your terminal aesthetic. Preview all live with claude-status --demo. Screenshots below show each theme rendered with one fixed dark palette — themes select ANSI colors; your own terminal palette supplies the exact hues.

default — full detail, clean separators

minimal — just the essentials

powerline — Nerd Font separators

focus — single line, minimal footprint

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, an optional per-subagent status rows question (see below), 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

For Coding Agents (Claude Code, Cursor, Aider, Continue, …)

If you're a coding agent installing this on a user's behalf, use the non-interactive one-liner:

pip install -U claude-status && claude-status --install && claude-status --print-config

That installs the package, writes the statusLine entry to ~/.claude/settings.json (backing up any prior config), and prints the current install state in a deterministic key=value format you can parse to confirm success. The user must restart Claude Code for the new status line to appear.

For full agent recipes (themes, budget, verification, uninstall, troubleshooting), see AGENTS.md.

CLI Reference

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 in three steps (the third only on wide terminals — see Using the room on Line 1):

1. Coarse pre-filter picks an eligible section list by terminal width:

   • 150+ columns: full layout (all sections eligible)
   • 100–149 columns: compact (drops the heaviest extras up front so we don't pay rendering cost on terminals where they won't fit)
   • Under 100 columns: narrow (essentials only — bar, tokens, cost, duration, branch)

   On Claude Code 2.1.141 and later, when the width came from a real probe rather than a fallback guess, those two thresholds drop to 110 and 80 columns.

2. Precise width-aware fit then measures the actual rendered width of each line (stripping invisible ANSI/OSC 8 escapes) and drops sections in priority order until the line fits the terminal. This means a 180-col terminal sees rate_limits, speed, version, etc., even though the static compact bucket would have hidden them — and a 110-col terminal stays within bounds even with heavy data (long agent name, vim mode active, long branch + session name).

The bar, tokens, cost, branch, and !CTX warning are always preserved — even at extreme widths, the statusline keeps its core identity.

Using the room on Line 1

The two steps above work on each line separately, which used to leave Line 1 with dozens of unused columns while Line 2 dropped sections to fit. A third step now shows those sections in the room Line 1 has:

• A section that didn't fit on Line 2 moves up to the nearest line with room and is added at the end of it. That line's own sections keep their order and position; only the context warning (!CTX) stays behind the newcomers, so the alert is still the last thing on the line.
• Line 2 itself is left exactly as the fit produced it. Nothing ever moves down, no line is made wider than the fitted width, nothing appears twice, and no new line is created.
• The most important sections are placed first.
• Some sections never move, because away from their neighbours they stop meaning anything: the stash/sync counts, the merge/conflict indicator, the worktree chips and the commit age (which belong beside the branch), and the ones with no label of their own — lines changed (+247 -38), the session duration (12m05s), the vim mode and the agent name.

With the demo data at 170 columns this shows all 23 sections instead of 18: tools, sessions, the version, CC and the clock join the end of Line 1. A session whose Line 2 already fits — a short branch name, no session name, no extra directories — gains nothing, and nothing changes for it.

When it applies: terminals of 160 columns or more, on Claude Code 2.1.141 or later, when the width was actually detected rather than guessed. Narrower than that, Line 1's own width shifts by a few columns as token counts and countdowns change, and filling it to the edge would make sections come and go; on older Claude Code a Line 1 that overflows can cost you Line 2, so its spare room is left alone. If you pin the width with CLAUDE_STATUSLINE_WIDTH, lines are fitted to exactly that width with no margin, so Line 1 can now reach the last column.

Themes: on for default, powerline, nord, tokyo-night, gruvbox and rose-pine. Off for minimal and focus, which are sparse on purpose, and off for custom themes unless the theme file contains "spill": true.

To turn it off (or on for a theme that leaves it off), add this to ~/.claude/claude-status-budget.json — true or false, without quotes:

{
  "spill_overflow": false
}

A change to that file can take up to 30 seconds to show, because the file is cached. claude-status --doctor shows the value it read (and says so if it is being ignored), plus whether your terminal meets the width conditions.

Detecting your real terminal width

Claude Code spawns the statusLine command as a subprocess with stdin piped and no TTY, so tput cols and language-level width detection cannot see the terminal. Current Claude Code releases set the COLUMNS and LINES environment variables to the terminal dimensions before running the command (anthropics/claude-code#22115, closed as completed in May 2026); older releases did not. claude-status walks a fallback chain so it finds the real width on both: stdin terminal.columns → COLUMNS env → shutil.get_terminal_size → os.get_terminal_size(fd) → process-tree walk (find a TTY-owning ancestor process, Linux only) → stty size < /dev/tty → tput cols 2>/dev/tty. Run claude-status --doctor to see which signal won on your machine and which signals lied or fell through.

Claude Code 2.1.139+ regression handling. 2.1.139 (2026-05-11) shipped "hooks now run without terminal access," which closed the /dev/tty escape hatch and — more dangerously — caused tput cols to confidently return its terminfo default (80 for most TERM values) instead of failing. v0.6.0 added two specific defenses: a stub-detection heuristic that rejects tput cols == 80 when no earlier TTY probe succeeded (the 2.1.139 fingerprint), and a process-tree walk that reads the controlling terminal of an ancestor process on Linux. Without these, users on 2.1.139 with a 220-col terminal were silently rendering an 80-col layout.

Override when detection still gets it wrong. Set CLAUDE_STATUSLINE_WIDTH=N to force a specific layout width regardless of detection. Useful for headless CI, nested multiplexers where every probe lies, or when you want a narrower layout than your terminal actually offers (e.g. CLAUDE_STATUSLINE_WIDTH=120 on a 200-col terminal). Out-of-range or non-numeric values fall through silently — set it back to empty or unset it to restore auto-detection.

This design exists because Claude Code's TUI uses Ink <Text wrap="truncate"> on the statusline (anthropics/claude-code#28750, the per-line truncation case was fixed in 2.1.141 via #58028, and terminal width has been handed to the command via COLUMNS since #22115): if Line 1 overflows the terminal, Line 2 may be silently dropped on older Claude Code releases, and on any release a line wider than the panel is cut mid-section. Measuring our actual rendered width and dropping low-priority sections one at a time prevents this without sacrificing useful information on wider terminals.

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 chip renders day:$7.4/$10 — today's spend summed across all your sessions on this machine — turning yellow at 70% and red at 90% of your daily limit. Three things to know:

• Per machine. The total comes from local session records, so it will undercount your real bill if you also run Claude Code on another computer.
• Accumulates from the moment you upgrade to v0.12.0 — on the first day the total may miss sessions from earlier that morning.
• Prefer the old behavior? Versions before v0.12.0 compared only the current session's cost against the daily budget. If you calibrated your number as a per-session ceiling, set "budget_scope": "session" in the same config file to keep that comparison (the chip then renders without the day: prefix).

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 did tools, sessions, the version or the clock move to the end of Line 1? From v0.17.0, on terminals of 160 columns or more, a section that doesn't fit on Line 2 is shown in the room left on Line 1 instead of being hidden — see Using the room on Line 1. To keep every section on its own line, add "spill_overflow": false to ~/.claude/claude-status-budget.json.

Why is only Line 1 showing / Line 2 is missing or truncated? Claude Code's TUI uses Ink <Text wrap="truncate"> which silently drops or truncates lines that exceed the terminal width. Several things can trigger this, all fixed:

1. Line 1 visibly overflows — fixed in v0.4.2 and v0.5.1 by moving sections to Line 2.
2. OSC 8 clickable links add invisible escape bytes — fixed in v0.5.2 by disabling OSC 8 by default.
3. Line 2 grows past terminal width with heavy data — fixed in v0.5.4 with a width-aware adaptive layout that measures actual rendered width and drops low-priority sections one at a time until each line fits. The full-layout threshold is now 150 cols (down from 230 in v0.5.3), and the precise post-render fit handles overflow gracefully across the entire range.

Upgrade to the latest release (pip install -U claude-status). The status line auto-adapts to your terminal width — no configuration needed. If you want a single-line display regardless of width, switch to the focus theme (claude-status --install --theme focus). Originally tracked upstream at anthropics/claude-code#28750 (auto-closed in March without engagement); Claude Code 2.1.141 later fixed the per-line truncation case via #58028, and current releases pass the terminal width to the command (#22115, closed as completed). The adaptive layout is still what keeps each line inside the panel, and it is what protects older Claude Code releases from the dropped-line behaviour.

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

Why don't I see per-subagent rows? In likely order: (1) rows only exist while subagents are running — an idle session shows nothing, that's normal; (2) check ~/.claude/settings.json has the subagentStatusLine entry (claude-status --doctor reports its state); (3) your Claude Code version may predate the hook — the per-task model/context fields need 2.1.205+; (4) restart Claude Code after adding the entry; (5) probe the renderer directly: claude-status --subagent < payload.json with a captured payload prints the JSONL rows it would emit.

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