llms.txt · diff

git:20261012.46336d9 to git:20261012.f4837dc

4 added, 4 removed. Audit A to A.

# claude-status

> Zero-dependency status line for Claude Code. Pure Python stdlib. 27+ metrics. 8 themes. All platforms.

## Install

```

pip install claude-status

claude-status --install

```

`--install` auto-configures `~/.claude/settings.json`. Restart Claude Code to see the status line.

## Update

```

pip install -U claude-status

```

No re-install needed — Claude Code re-runs the installed binary on every render.

## Uninstall

```

claude-status --uninstall # restore previous settings.json

pip uninstall claude-status

```

## What It Does

Displays real-time session metrics in Claude Code's terminal status bar. Reads JSON from stdin (piped by Claude Code), formats 27+ data points across up to 2 lines, outputs ANSI-colored text to stdout. No daemon, no network calls, no background processes. Each render runs in single-digit milliseconds.

## CLI Commands

- `claude-status --install` — non-interactive install (use in scripts/agents)

- `claude-status --install --theme NAME` — install with specific theme

- `claude-status --setup` — interactive setup wizard (theme + budget)

- `claude-status --uninstall` — remove from settings, restore previous config

- `claude-status --print-config` — show current installation state (machine-readable)

- `claude-status --doctor` — run diagnostics

- `claude-status --demo` — preview all 8 themes

- `claude-status --version` — show version

- `claude-status --theme NAME` — use theme for this render only

## Themes

default, minimal, powerline, nord, tokyo-night, gruvbox, rose-pine, focus (single-line)

Custom themes: `~/.claude/claude-status-theme.json`

## Metrics Displayed

Line 1: context bar, tokens (in/out), cache %, cost, budget, burn rate, rate limits (5h/7d with countdown), context size, context warning

Line 2: duration, API latency, tokens/sec, lines changed, git branch, git extras (stash/sync), git state (merge/rebase/conflict), commit age, tool calls, sessions today, session name, vim mode, agent, worktree, model, output style, added dirs, git worktree, effort level (low/high/xhigh/max), version, CC version, clock

Opt-in sections (added to a custom theme's line list, not in the built-in themes): cost rate (`~$3.6/hr` projected session cost per hour), context tokens (`ctx:412K/1M` absolute context usage), cache age (time since the last assistant turn; warns once the prompt cache has gone cold), cache hit (`hit:91% miss:2` session prompt-cache hit ratio and misses), thinking, pull request (with review state), cost breakdown (largest non-base `cost.by_category` entry).

## Per-Subagent Status Rows

claude-status also serves Claude Code's `subagentStatusLine` hook from the same binary, rendering a row per running subagent in the agent panel: `[Explore] [###.....] 41% - 23s - Sonnet 5` (task name, per-task context bar and percentage, elapsed time, model). Enable with `"subagentStatusLine": {"type": "command", "command": "claude-status --subagent"}` alongside the existing `statusLine` entry, or answer the prompt in `claude-status --setup`. Per-task model and context fields require Claude Code v2.1.205+; on older versions rows show `[name] 23s`. Output is JSONL (`{"id": ..., "content": ...}`) and every error path emits nothing, so a malformed payload can never corrupt the panel.

## Effort Levels

Recognized values: `low`, `medium`, `high`, `xhigh`, `max`. The `medium` default is hidden (no `effort:` indicator). `xhigh` and `max` are Opus 4.7 / top-tier — `xhigh` was introduced in Claude Code v2.1.111 (2026-04); `max` is the top of the scale. Other models silently fall back to `high` per Anthropic's docs. Renders as `effort:xhigh` / `effort:max` (bright magenta by default; per-theme `effort_xhigh` and `effort_max` color keys).

**Source priority (v0.5.8+)**: stdin JSON `effort.level` (Claude Code v2.1.119+) is preferred over `~/.claude/settings.json`'s `effortLevel` key. Stdin updates within one render cycle of `/effort xhigh`; the file read has a 30s cache and is used only as a fallback for older Claude Code versions.

## Configuration Files

- `~/.claude/settings.json` — statusLine config (type, command, refreshInterval)

- - `~/.claude/claude-status-budget.json` — daily_budget_usd, compaction_threshold_pct, clickable_links, disabled_sections

+ - `~/.claude/claude-status-budget.json` — daily_budget_usd, compaction_threshold_pct, clickable_links, disabled_sections, spill_overflow (true/false: whether sections that do not fit on one line may move up to a line with room)

- `~/.claude/claude-status-theme.json` — custom theme overrides

## StatusLine JSON Fields (from Claude Code stdin)

model.id, model.display_name, cwd, workspace.current_dir, workspace.project_dir, workspace.added_dirs, workspace.git_worktree, cost.total_cost_usd, cost.total_duration_ms, cost.total_api_duration_ms, cost.total_lines_added, cost.total_lines_removed, context_window.used_percentage, context_window.remaining_percentage, context_window.context_window_size, context_window.current_usage.*, exceeds_200k_tokens, rate_limits.five_hour.used_percentage, rate_limits.five_hour.resets_at, rate_limits.seven_day.used_percentage, rate_limits.seven_day.resets_at, session_id, session_name, transcript_path, version, output_style.name, vim.mode, agent.name, worktree.name, worktree.path, worktree.branch, effort.level (v2.1.119+), thinking.enabled (v2.1.119+), prompt_cache.ttl, prompt_cache.expires_at, prompt_cache.warm, prompt_cache.hit_ratio, prompt_cache.misses, prompt_cache.caching_observed (v2.1.251+)

## Architecture

- cli.py (entry point, normalization, two-stage layout, rendering) → bar.py (progress bar) + colors.py (ANSI + NO_COLOR) + formatters.py (tokens, cost, duration, speed) + git.py (branch, stash, sync, state, commit age with 5s cache) + sessions.py (session count, tool count, budget, effort with 10-30s cache) + themes.py (8 built-in + custom)

+ cli.py (entry point, normalization, staged layout, rendering) → bar.py (progress bar) + colors.py (ANSI + NO_COLOR) + formatters.py (tokens, cost, duration, speed) + git.py (branch, stash, sync, state, commit age with 5s cache) + sessions.py (session count, tool count, budget, effort with 10-30s cache) + themes.py (8 built-in + custom)

## Key Design Decisions

- Zero external dependencies (pure Python stdlib only — no pip packages)

- Never crash — degrade gracefully on any malformed input (try/except defense-in-depth around `render()`)

- File-based caching with TTLs (5s-60s) to avoid subprocess overhead on every render

- - **Two-stage responsive layout** (v0.5.4+): coarse pre-filter by terminal-width bucket (150+/100-149/<100 cols) skips expensive sections on narrow terminals; precise post-render fit then measures actual visible width (stripping ANSI/OSC 8) and drops sections in priority order until each line fits the terminal width minus a confidence-scaled safety margin (v0.15.0+: zero when the width is pinned via `CLAUDE_STATUSLINE_WIDTH`, small when a probe measured it, larger when it had to be guessed — Claude Code renders the status line inside a padded panel, so the usable row is narrower than the reported terminal width)

+ - **Staged responsive layout** (v0.5.4+): coarse pre-filter by terminal-width bucket (150+/100-149/<100 cols) skips expensive sections on narrow terminals; precise post-render fit then measures actual visible width (stripping ANSI/OSC 8) and drops sections in priority order until each line fits the terminal width minus a confidence-scaled safety margin (v0.15.0+: zero when the width is pinned via `CLAUDE_STATUSLINE_WIDTH`, small when a probe measured it, larger when it had to be guessed — Claude Code renders the status line inside a padded panel, so the usable row is narrower than the reported terminal width). A third stage (v0.17.0+) shows sections that did not fit on Line 2 at the end of Line 1 when it has room: only at 160+ columns, on Claude Code 2.1.141+ with a detected width, for the six full themes (off for minimal, focus and custom themes unless the theme file sets `"spill": true`); `"spill_overflow": false` in claude-status-budget.json turns it off.

- All numeric fields use `_first()` helper (not `or`) to preserve zero values

- OSC 8 clickable links disabled by default (Claude Code's Ink TUI miscounts them)

## Workarounds for Upstream Bugs

- - **Ink truncation** (anthropics/claude-code#28750; per-line case fixed upstream in Claude Code 2.1.141 via #58028): Claude Code's TUI uses `<Text wrap="truncate">` on the statusline. On releases before 2.1.141, when Line 1 overflows the terminal width, Line 2 is silently dropped; on every release an over-wide line is cut mid-section. Our two-stage layout (above) measures actual rendered width and shrinks until we fit.

+ - **Ink truncation** (anthropics/claude-code#28750; per-line case fixed upstream in Claude Code 2.1.141 via #58028): Claude Code's TUI uses `<Text wrap="truncate">` on the statusline. On releases before 2.1.141, when Line 1 overflows the terminal width, Line 2 is silently dropped; on every release an over-wide line is cut mid-section. Our staged layout (above) measures actual rendered width and shrinks until we fit.

- **Terminal width hidden from subprocess** (anthropics/claude-code#22115, closed as completed): the statusLine command is spawned with stdin piped and no TTY, so `tput cols` and language-level detection cannot see the terminal. Current Claude Code releases set `COLUMNS` and `LINES` for the command; older ones set nothing. v0.5.7+ walks a fallback chain (stdin `terminal.columns` → `COLUMNS` env → shutil → `os.get_terminal_size(fd)` → process-tree walk for a TTY-owning ancestor (Linux) → `stty size < /dev/tty` → `tput cols 2>/dev/tty`) to recover the real width and avoid trimming sections users have room for.

- **rate_limits epoch-timestamp** (anthropics/claude-code#52326, open): on a fresh 5h/7d window, `rate_limits.X.used_percentage` returns the `resets_at` epoch timestamp (~1.7e9) instead of 0/null. v0.5.7+ guards against this — any value above 100 is treated as "no data yet" and the section is hidden.

## Testing

stdlib unittest only. 350+ tests. CI: 21-job matrix (3 OS x 7 Python versions: 3.8-3.14).

```

python -m unittest discover tests/

```

## Links

- PyPI: https://pypi.org/project/claude-status/

- Repository: https://github.com/mkalkere/claude-statusline

- Issues: https://github.com/mkalkere/claude-statusline/issues

- Changelog: https://github.com/mkalkere/claude-statusline/blob/main/CHANGELOG.md

- Architecture: https://github.com/mkalkere/claude-statusline/blob/main/ARCHITECTURE.md

- Agent install guide: https://github.com/mkalkere/claude-statusline/blob/main/AGENTS.md