{"id":48911399,"url":"https://github.com/mkalkere/claude-statusline","last_synced_at":"2026-04-17T00:00:24.791Z","repository":{"id":344507369,"uuid":"1182052568","full_name":"mkalkere/claude-statusline","owner":"mkalkere","description":"Beautiful, informative status line for Claude Code. Zero dependencies, cross-platform. pip install claude-status","archived":false,"fork":false,"pushed_at":"2026-04-11T04:40:31.000Z","size":160,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-11T05:32:21.843Z","etag":null,"topics":["ai-tools","anthropic","claude","claude-code","claude-code-plugin","claude-code-skills","claude-code-statusline","cli","developer-tools","productivity","python","python-cli","status-bar","status-line","statusline","terminal","terminal-ui","zero-dependencies"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/claude-status/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mkalkere.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-15T01:12:18.000Z","updated_at":"2026-04-11T04:38:30.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mkalkere/claude-statusline","commit_stats":null,"previous_names":["mkalkere/claude-statusline"],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/mkalkere/claude-statusline","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkalkere%2Fclaude-statusline","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkalkere%2Fclaude-statusline/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkalkere%2Fclaude-statusline/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkalkere%2Fclaude-statusline/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mkalkere","download_url":"https://codeload.github.com/mkalkere/claude-statusline/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkalkere%2Fclaude-statusline/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31909235,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-16T18:22:33.417Z","status":"ssl_error","status_checked_at":"2026-04-16T18:21:47.142Z","response_time":69,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-tools","anthropic","claude","claude-code","claude-code-plugin","claude-code-skills","claude-code-statusline","cli","developer-tools","productivity","python","python-cli","status-bar","status-line","statusline","terminal","terminal-ui","zero-dependencies"],"created_at":"2026-04-17T00:00:24.082Z","updated_at":"2026-04-17T00:00:24.765Z","avatar_url":"https://github.com/mkalkere.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# claude-status\n\n\u003e **Zero-dependency status line for Claude Code. One command. Every metric. All platforms.**\n\n[![PyPI version](https://img.shields.io/pypi/v/claude-status)](https://pypi.org/project/claude-status/)\n[![Python 3.8–3.14](https://img.shields.io/pypi/pyversions/claude-status)](https://pypi.org/project/claude-status/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)\n[![CI](https://github.com/mkalkere/claude-statusline/actions/workflows/ci.yml/badge.svg)](https://github.com/mkalkere/claude-statusline/actions)\n[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey.svg)](https://pypi.org/project/claude-status/)\n[![Downloads](https://img.shields.io/pypi/dm/claude-status)](https://pypi.org/project/claude-status/)\n\n```\nLine 1:  [████████░░░░░░░░░░░░] │ in:245K out:18K │ cache:41% │ $0.73 │ burn:37K/min\nLine 2:  5h:34% 7d:18% ~2h │ (200K) │ 12m05s │ +247 -38 │ ⎇ myapp/feat/statusline │ ✦ refactor auth │ Opus │ effort:high │ v0.5.0 │ CC:2.1.92 │ 15:30\n```\n\n## 30-Second Setup\n\n```bash\npip install claude-status\nclaude-status --setup\n```\n\nThe setup wizard walks you through theme selection, budget configuration, and installs everything automatically. Restart Claude Code and you're done.\n\n## Why claude-status?\n\n- **Zero dependencies** — pure Python stdlib. No `psutil`, no `colorama`, no compilation. Installs in under 2 seconds\n- **Every metric that matters** — 30+ data points including burn rate (tokens/min), rate limit tracking, and effort level\n- **Rate limit awareness** — see your 5-hour and 7-day API usage at a glance with color-coded warnings and reset countdown\n- **Responsive layout** — automatically adapts to your terminal width (full/compact/narrow)\n- **NO_COLOR / FORCE_COLOR support** — respects terminal color standards\n- **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`.\n- **Per-section toggle** — disable any section via config without a custom theme\n- **8 built-in themes** — default, minimal, powerline, nord, tokyo-night, gruvbox, rose-pine, focus\n- **Budget monitoring** — set a daily spend limit, get color-coded warnings as you approach it\n- **Session analytics** — tool call count and today's session count at a glance\n- **Cross-platform** — tested on Windows, macOS, and Linux across Python 3.8–3.14 (21 CI jobs)\n- **Interactive setup** — `--setup` wizard walks you through theme selection and budget config\n- **Clean uninstall** — `--uninstall` restores your previous configuration\n\n## Features\n\n### Line 1 — Metrics at a Glance\n| Feature | What You See | Why It Matters |\n|---------|-------------|----------------|\n| Context Bar | `[████████░░░░░░░░░░░░]` | Green/yellow/red adaptive — know your context budget instantly |\n| Token Counts | `in:245K out:18K` | Human-readable (K/M) — no squinting at raw numbers |\n| Cache Efficiency | `cache:41%` | See how much prompt cache is saving you |\n| Cost | `$0.73` | Session cost in real-time — cents for small, dollars for large |\n| Budget | `$0.73/$10` | Color-coded daily budget tracker (green/yellow/red) |\n| Burn Rate | `burn:37K/min` | Tokens/min consumption — unique to claude-status |\n| Rate Limits | `5h:34% 7d:18% ~2h` | API usage limits with reset countdown (Pro/Max only) |\n| Context Size | `(200K)` | Know if you're on 200K or 1M context |\n| Context Warning | `!CTX` | Bold red alert at 85%+ context usage |\n\n### Line 2 — Session Context\n| Feature | What You See | Why It Matters |\n|---------|-------------|----------------|\n| Duration | `12m05s` | Wall-clock session time |\n| API Latency | `api:5m12s` | Time spent in API calls |\n| Lines Changed | `+247 -38` | Git-diff style — green additions, red removals |\n| Git Branch | `⎇ myapp/feat/statusline` | Project name + branch, color-coded |\n| Git Stash | `stash:2` | Number of stashed changes |\n| Git Sync | `sync:+2/-1` | Commits ahead/behind remote |\n| Git State | `merge` / `conflict` | Merge/rebase/conflict indicator |\n| Commit Age | `last:5m` | Time since last commit |\n| Token Speed | `speed:1.2K/s` | Token throughput (tokens/sec) |\n| Git Worktree | `gwt` | Indicator when inside a native git worktree |\n| Tool Calls | `tools:42` | Number of tool calls in current session |\n| Sessions Today | `sessions:3` | How many sessions you've started today |\n| Session Name | `✦ refactor auth` | Custom session name (via `--name` or `/rename`) |\n| Vim Mode | `NORMAL` | Blue for NORMAL, green for INSERT |\n| Agent | `[Explore]` | Shows which subagent is active |\n| Worktree | `wt:fix/bug-123` | Claude Code worktree branch indicator |\n| Model | `Opus` | Active model name |\n| Output Style | `style:explanatory` | Active output style when set |\n| Added Dirs | `dirs:+2` | Extra directories added via `/add-dir` |\n| Effort Level | `effort:high` | Thinking effort (shown when non-default) |\n| Version | `v0.5.0` | claude-status version |\n| CC Version | `CC:2.1.92` | Claude Code application version |\n| Clock | `15:30` | Current time |\n\n## Themes\n\n8 built-in themes to match your terminal aesthetic. Preview all live with `claude-status --demo`.\n\n### default — full detail, clean separators\n```\n[████████░░░░░░░░░░░░] │ in:245K out:18K │ cache:41% │ $0.73 │ burn:37K/min\n5h:34% 7d:18% ~2h │ (200K) │ 12m05s │ +247 -38 │ ⎇ myapp/feat/statusline │ ✦ refactor auth │ Opus │ effort:high │ v0.5.0 │ CC:2.1.92 │ 15:30\n```\n\n### minimal — just the essentials\n```\n●●●●●●●●·············· in:245K out:18K $0.73 5h:34% 7d:18%\n12m05s ⎇ feat/statusline sessions:3 Opus 15:30\n```\n\n### powerline — Nerd Font separators\n```\n████████░░░░░░░░░░░░  in:245K out:18K  cache:41%  $0.73  burn:37K/min\n5h:34% 7d:18% ~2h  (200K)  12m05s  +247 -38  ⎇ myapp/feat/statusline  ✦ refactor auth  Opus  effort:high  v0.5.0  CC:2.1.92  15:30\n```\n\n### focus — single line, minimal footprint\n```\n[████████░░░░] │ $0.73 │ 5h:34% 7d:18% ~2h │ ⎇ main │ effort:high │ 15:30\n```\n\n### nord — cool blue tones\n### tokyo-night — purple and blue accents\n### gruvbox — warm retro palette\n### rose-pine — soft muted pinks\n\n## Installation\n\n### pip (recommended)\n```bash\npip install claude-status\nclaude-status --setup\n```\n\n### pipx (isolated — no venv pollution)\n```bash\npipx install claude-status\nclaude-status --setup\n```\n\n### uvx (fast, modern)\n```bash\nuvx claude-status --setup\n```\n\n### From source (contributors)\n```bash\ngit clone https://github.com/mkalkere/claude-statusline.git\ncd claude-statusline\npip install -e .\nclaude-status --setup\n```\n\n### What `--setup` does\n\nWalks 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.\n\n\u003e **Command not found?** Ensure your Python scripts directory is in `PATH`.\n\u003e Fallback: `python -m claude_statusline --setup`\n\n## CLI Reference\n\n| Command | Description |\n|---------|-------------|\n| `claude-status --setup` | Interactive setup wizard (recommended for first use) |\n| `claude-status --install` | Auto-configure Claude Code settings |\n| `claude-status --install --theme nord` | Install with a specific theme |\n| `claude-status --uninstall` | Remove from Claude Code settings (restores previous config) |\n| `claude-status --demo` | Preview all 8 themes with sample data |\n| `claude-status --doctor` | Diagnostics: Python version, OS, terminal, current settings |\n| `claude-status --version` | Show version |\n| `claude-status --help` | Show usage |\n\n## Budget Monitoring\n\nSet a daily spending limit to get color-coded warnings as you approach it:\n\n```bash\nclaude-status --setup  # interactive wizard sets this up for you\n```\n\nOr manually create `~/.claude/claude-status-budget.json`:\n\n```json\n{\n  \"daily_budget_usd\": 10.00,\n  \"compaction_threshold_pct\": 62\n}\n```\n\n**Budget thresholds:**\n- **Green**: under 70% of budget\n- **Yellow**: 70–90% of budget\n- **Red (bold)**: 90%+ of budget\n\n**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.\n\n## Periodic Updates\n\nBy 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:\n\n```json\n{\n  \"statusLine\": {\n    \"type\": \"command\",\n    \"command\": \"claude-status --theme default\",\n    \"refreshInterval\": 10\n  }\n}\n```\n\nThis runs the status line every 10 seconds in addition to the standard update triggers.\n\n## Responsive Layout\n\nThe status line automatically adapts to your terminal width via a two-stage process:\n\n1. **Coarse pre-filter** picks an eligible section list by terminal width:\n   - **150+ columns**: full layout (all sections eligible)\n   - **100–149 columns**: compact (drops the heaviest extras up front so we don't pay rendering cost on terminals where they won't fit)\n   - **Under 100 columns**: narrow (essentials only — bar, tokens, cost, duration, branch)\n\n2. **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).\n\nThe bar, tokens, cost, branch, and `!CTX` warning are always preserved — even at extreme widths, the statusline keeps its core identity.\n\nThis design exists because Claude Code's TUI uses Ink `\u003cText wrap=\"truncate\"\u003e` on the statusline (anthropics/claude-code#28750, still unaddressed upstream): if Line 1 overflows the terminal, Line 2 is silently dropped. Measuring our actual rendered width and dropping low-priority sections one at a time prevents this without sacrificing useful information on wider terminals.\n\n## Manual Configuration\n\nAdd to `~/.claude/settings.json`:\n\n```json\n{\n  \"statusLine\": {\n    \"type\": \"command\",\n    \"command\": \"claude-status\",\n    \"refreshInterval\": 10\n  }\n}\n```\n\nWith a theme:\n\n```json\n{\n  \"statusLine\": {\n    \"type\": \"command\",\n    \"command\": \"claude-status --theme focus\",\n    \"refreshInterval\": 10\n  }\n}\n```\n\n## How It Works\n\nClaude 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.\n\n## FAQ\n\n**Does this work on Windows?**\nYes! Fully tested on Windows 11, macOS, and Linux across Python 3.8–3.14.\n\n**Can I customize the colors?**\nYes — use `--theme custom` with a `~/.claude/claude-status-theme.json` file. Override any color or layout from the built-in themes.\n\n**How does budget monitoring work?**\nCreate `~/.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.\n\n**What is burn rate?**\nTokens consumed per minute. Helps you gauge how fast you're using context in a session.\n\n**Do I need a Pro/Max subscription for rate limit tracking?**\nYes. 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.\n\n**How often does the status line update?**\nBy 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.\n\n**Can I use a single-line layout?**\nYes — use the `focus` theme: `claude-status --install --theme focus`. It shows only the essentials on one line.\n\n**Why is only Line 1 showing / Line 2 is missing or truncated?**\nClaude Code's TUI uses Ink `\u003cText wrap=\"truncate\"\u003e` which silently drops or truncates lines that exceed the terminal width. Several things can trigger this, all fixed:\n\n1. **Line 1 visibly overflows** — fixed in v0.4.2 and v0.5.1 by moving sections to Line 2.\n2. **OSC 8 clickable links add invisible escape bytes** — fixed in v0.5.2 by disabling OSC 8 by default.\n3. **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.\n\nUpgrade 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`). Tracked upstream at anthropics/claude-code#28750 (closed without a fix after 30 days of inactivity).\n\n**Does it add any latency to Claude Code?**\nNo. It runs as a pure stdin-to-stdout pipe in single-digit milliseconds. No daemon, no network calls, no background processes.\n\n**Why does the session count seem low on Windows with WSL?**\nWindows and WSL have separate `~/.claude/` directories, so sessions are counted independently. The status line shows sessions from the platform it's running on.\n\n## Troubleshooting\n\nIf claude-status doesn't appear after installation:\n\n1. Run `claude-status --doctor` to check your setup\n2. Verify `~/.claude/settings.json` contains the `statusLine` entry\n3. Ensure your Python scripts directory is in your `PATH`\n4. Try `python -m claude_statusline --setup` as a fallback\n5. Restart Claude Code after any configuration change\n\n## Uninstall\n\n```bash\nclaude-status --uninstall\n```\n\nThis removes the statusLine entry from your settings and restores your previous configuration if a backup exists. Then:\n\n```bash\npip uninstall claude-status\n```\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmkalkere%2Fclaude-statusline","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmkalkere%2Fclaude-statusline","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmkalkere%2Fclaude-statusline/lists"}