llms.txt git:20260510.9f3010bA

Immutable. This exact content never changes and is served at /api/v1/blob/3e5669821335aeb1.

# 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

## 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-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+, not currently rendered)

## 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)

## 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
- 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, closed without fix): Claude Code's TUI uses `<Text wrap="truncate">` on the statusline. When Line 1 overflows the terminal width, Line 2 is silently dropped. Our two-stage layout (above) measures actual rendered width and shrinks until we fit.
- **Terminal width hidden from subprocess** (anthropics/claude-code#22115, open): the statusLine command is spawned with stdin piped, no TTY, no `COLUMNS` env — so naive width detection always returns the fallback. v0.5.7+ walks a fallback chain (stdin `terminal.columns` → `COLUMNS` env → shutil → `os.get_terminal_size(fd)` → `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