{"id":36964166,"url":"https://github.com/shrwnsan/claude-statusline","last_synced_at":"2026-02-11T08:52:29.362Z","repository":{"id":326487344,"uuid":"1102449138","full_name":"shrwnsan/claude-statusline","owner":"shrwnsan","description":"Simple statusline for Claude Code with project-branch, git indicators, and context usage. Optimized for speed with bun. Just the essentials, none of the bloat.","archived":false,"fork":false,"pushed_at":"2026-02-06T06:48:11.000Z","size":292,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-06T12:07:20.241Z","etag":null,"topics":["bun","claude-code","cli","cli-tools","command-line","cross-platform","developer-tools","development-tools","devtools","git","git-status","lightweight","productivity","sandbox-detection","security-focused","shell-script","statusline","terminal","terminal-app","unix"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/shrwnsan.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-11-23T13:39:15.000Z","updated_at":"2026-02-06T06:48:15.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/shrwnsan/claude-statusline","commit_stats":null,"previous_names":["shrwnsan/claude-statusline"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/shrwnsan/claude-statusline","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shrwnsan%2Fclaude-statusline","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shrwnsan%2Fclaude-statusline/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shrwnsan%2Fclaude-statusline/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shrwnsan%2Fclaude-statusline/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shrwnsan","download_url":"https://codeload.github.com/shrwnsan/claude-statusline/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shrwnsan%2Fclaude-statusline/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29330671,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-11T06:13:03.264Z","status":"ssl_error","status_checked_at":"2026-02-11T06:12:55.843Z","response_time":97,"last_error":"SSL_read: 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":["bun","claude-code","cli","cli-tools","command-line","cross-platform","developer-tools","development-tools","devtools","git","git-status","lightweight","productivity","sandbox-detection","security-focused","shell-script","statusline","terminal","terminal-app","unix"],"created_at":"2026-01-13T19:21:54.273Z","updated_at":"2026-02-11T08:52:29.328Z","avatar_url":"https://github.com/shrwnsan.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Claude Code Statusline\n\nSimple statusline for Claude Code with project-branch, git indicators, and context usage. Optimized for speed with bun. Just the essentials, none of the bloat.\n\n![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)\n![Version](https://img.shields.io/badge/version-2.1.4-green.svg)\n![TypeScript](https://img.shields.io/badge/language-TypeScript-3178C6.svg)\n![Node](https://img.shields.io/badge/node-%3E%3D22.6.0-brightgreen.svg)\n![Bun](https://img.shields.io/badge/runtime-Bun-black.svg)\n\n![Demo](https://github.com/user-attachments/assets/8716dc4e-83da-410b-88f2-c47de7dd5930)\n\n## Quick Start\n\n### Installation\n\n```bash\n# Bun install (recommended - 5x faster than Node.js)\nbun install -g claude-statusline\n\n# Or npm install (works well too)\nnpm install -g claude-statusline\n\n# Or pnpm/yarn\npnpm add -g claude-statusline\nyarn global add claude-statusline\n```\n\n\n### Claude Code Configuration\n\n#### Standard Configuration (Node.js Runtime)\nAdd to your `~/.claude/settings.json`:\n\n```json\n{\n  \"statusLine\": {\n    \"type\": \"command\",\n    \"command\": \"claude-statusline\"\n  }\n}\n```\n\n#### ⚡ Performance-Optimized Configuration (Bun Runtime)\nFor maximum performance (~5ms response time), explicitly use the Bun runtime:\n\n```json\n{\n  \"statusLine\": {\n    \"type\": \"command\",\n    \"command\": \"bun claude-statusline\"\n  }\n}\n```\n\n\u003e **Why specify \"bun claude-statusline\"?**\n\u003e Even when installed with `bun install -g`, the executable's shebang defaults to Node.js. Using \"bun claude-statusline\" ensures you get the full Bun performance benefits.\n\n### Usage\n\nThe statusline automatically displays when Claude Code is active and updates based on your git status and environment.\n\n### Default Configuration\n\nclaude-statusline works out-of-the-box with these defaults:\n- `envContext`: false (environment versions NOT shown)\n- `truncate`: false (basic truncation at terminal width - 10)\n- `noEmoji`: false (Nerd Font symbols preferred, ASCII fallback)\n- `noGitStatus`: false (git status shown)\n- `noContextWindow`: false (context window usage shown)\n- `noSoftWrap`: false (soft wrapping enabled when truncate=true, set to true to disable)\n- `rightMargin`: 15 (prevents bleeding into Claude Code telemetry)\n- `cacheTTL`: 300 (5-minute cache for environment info)\n- `maxLength`: 1000 (maximum input length for security)\n\nTo see environment versions in your statusline, create a configuration file with:\n```json\n{\"envContext\": true}\n```\n*See the [🎛️ Configuration](#-configuration) section below for how to create and manage config files*\n\n## ⚡ Performance\n\n🚀 **claude-statusline is lightning fast**\n\n- **With Bun runtime**: ~5ms response time (5x faster)\n- **With Node.js runtime**: ~28ms response time (still instant)\n- **Installation**: 19KB (tiny single-file bundle)\n\n### Real-world experience\n```bash\n# Install instantly\nbun install -g claude-statusline  # Downloads 19KB in \u003c1 second\n\n# Add to Claude Code settings for maximum performance\n# ~/.claude/settings.json\n{\n  \"statusLine\": {\n    \"type\": \"command\",\n    \"command\": \"bun claude-statusline\"\n  }\n}\n\n# Enjoy instant git status updates! (~5ms with Bun vs ~28ms with Node.js)\n```\n\n**Performance Comparison:**\n- With `bun claude-statusline`: ~5ms ⚡\n- With `claude-statusline` (Node.js): ~28ms ✅\n- Both work perfectly - choose based on your preference\n\n### Why so fast?\n- ✅ Native git commands (no slow libraries)\n- ✅ Optimized for Bun runtime\n- ✅ Smart caching (8-hour environment cache)\n- ✅ Single-file bundle (no module resolution overhead)\n\n**Fun fact**: We started with a fast bash script (~60ms), accidentally made it slower with TypeScript (~327ms), then optimized it to be 12x faster than the original (~5ms with Bun)!\n\n*See [Performance Guide](docs/guide-03-performance.md) for the full optimization story*\n\n## Features\n\n### Git Status Indicators\n\n- **Stashed**: ⚑ (stashed changes)\n- **Deleted**: ✘ (files deleted)\n- **Modified**: ! (unstaged changes)\n- **Staged**: + (added to staging area)\n- **Untracked**: ? (new files not tracked)\n- **Renamed**: » (files moved/renamed)\n- **Conflicts**: × (merge conflicts)\n- **Diverged**: ⇕ (both ahead and behind upstream)\n- **Ahead**: ⇡ (commits ahead of upstream)\n- **Behind**: ⇣ (commits behind upstream)\n\n### Context Window Usage (Beta Feature)\n\n**⚠️ Beta Feature:** Context window usage display is currently in beta. The calculation follows the official Claude Code documentation but may show different values compared to Claude Code's built-in `/context` command.\n\nAutomatically displays context window usage percentage when available (requires Claude Code to send context window data):\n\n```\nclaude-statusline @ main [$!] *Opus #27% (ASCII version)\n```\n\nShows percentage of context window consumed in the current conversation. The symbol varies by mode:\n- **Nerd Font**: ⚡︎ (lightning bolt)\n- **ASCII**: # (hash symbol)\n\n**Important Notes:**\n- Calculation follows [official Claude Code documentation](https://code.claude.com/docs/en/statusline#context-window-usage)\n- May differ from `/context` command due to different data sources or calculation methods\n- Only shows when Claude Code provides context window data\n- Can be disabled with `\"noContextWindow\": true` or `CLAUDE_CODE_STATUSLINE_NO_CONTEXT_WINDOW=1`\n\n**Known Discrepancy:**\nSome users have noted differences between the statusline percentage and `/context` command output. This appears to be a difference in how Claude Code internally calculates context usage versus what's provided through the statusline API.\n\n### Environment Context\n\nWhen enabled with `\"envContext\": true`, shows development tool versions:\n\n```\nclaude-statusline @ main [$!A] *Claude Sonnet 4.5 Node22.17.1 Py3.13.5 Docker28.3.3 (ASCII version)\n```\n\n*Example shows ASCII mode for universal compatibility. With Nerd Fonts enabled, ASCII symbols are replaced with icons/emojis.*\n\nSupported tools:\n- **Node.js**: `node --version` (cached 5 minutes)\n- **Python**: `python3 --version` or `python --version` (cached 5 minutes)\n- **Docker**: `docker --version` (cached 30 minutes)\n\n### Smart Width Management\n\nTwo modes available:\n\n1. **Basic Mode** (default):\n   - Simple truncation at `terminal width - 10` characters\n   - Always single-line\n   - Fast and predictable\n\n2. **Smart Truncation Mode** (`CLAUDE_CODE_STATUSLINE_TRUNCATE=1`):\n   - 15-character right margin prevents bleeding into Claude Code telemetry\n   - Branch prioritization: Branch names preserved over project names\n   - Progressive truncation: Project → Branch → Indicators (if absolutely necessary)\n   - Optional soft-wrapping: Can wrap model/environment info to preserve more context\n   - Responsive design: Adapts to terminal width from 60-200+ characters\n   - Disable soft-wrapping with `\"noSoftWrap\": true` to force single-line\n\n### Width Breakpoints\n\n| Width | Experience | Statusline Behavior |\n|-------|------------|-------------------|\n| **\u003c 60** | Poor | Aggressive truncation |\n| **60-79** | Acceptable | Smart truncation, branch preserved |\n| **80-99** | Good | Ideal balance, minimal truncation |\n| **100-119** | Excellent | Usually no truncation needed |\n| **120+** | Perfect | No constraints, optimal UX |\n\n## Icon Reference \u0026 Nerd Font Support\n\n**Nerd Font Support (Optional):** Automatically detects Nerd Fonts and falls back to ASCII equivalents.\n\nFor enhanced visual icons, install Nerd Fonts:\n- **macOS:** `font-jetbrains-mono-nerd-font` via Homebrew\n- **Cross-platform:** Download from [nerdfonts.com](https://nerdfonts.com/)\n\n### Icon Comparison\n\n![Icon Comparison Reference](https://github.com/user-attachments/assets/4190fd65-c425-4da7-8659-a7c7a6f15bc0)\n\n### ASCII Mode Display\n\n| Use Case | Default Symbol | ASCII Fallback | Notes |\n|----------|---------------|---------------|-------|\n| **Git Repository** | `@` | `@` | Always ASCII |\n| **Stashed Files** | `⚑` | `$` | ASCII when `\"noEmoji\": true` |\n| **Staged Changes** | `+` | `+` | Always ASCII |\n| **Modified Files** | `!` | `!` | Always ASCII |\n| **Untracked Files** | `?` | `?` | Always ASCII |\n| **Renamed Files** | `»` | `\u003e` | ASCII when `\"noEmoji\": true` |\n| **Deleted Files** | `✘` | `X` | ASCII when `\"noEmoji\": true` |\n| **Merge Conflicts** | `×` | `C` | ASCII when `\"noEmoji\": true` |\n| **Ahead/Behind** | `⇡⇣` | `A/B` | ASCII when `\"noEmoji\": true` |\n| **Diverged** | `⇕` | `D` | ASCII when `\"noEmoji\": true` |\n| **Claude Model** | `🤖` | `*` | ASCII when `\"noEmoji\": true` |\n| **Context Window** | `⚡︎` | `#` | ASCII when `\"noEmoji\": true` |\n\n*Note: Examples show ASCII-compatible symbols. Full statusline with Nerd Fonts shows additional symbols: $X!+?\u003eCADAB*\n\n### 🎛️ Configuration\n\n**📖 [Complete Configuration Guide](./docs/guide-01-configuration.md)**\n\nConfigure with JSON/YAML files:\n\n```bash\n# Quick setup with minimal example\ncp .claude-statusline.json.example.min ~/.claude/claude-statusline.json\n\n# Or complete example with all options\ncp .claude-statusline.json.example ~/.claude/claude-statusline.json\n\n# Edit your configuration\nnano ~/.claude/claude-statusline.json\n```\n\n**Configuration search order:**\n1. `./claude-statusline.json` or `./claude-statusline.yaml` (project-level)\n2. Parent directories (searches up the tree)\n3. `~/.claude/claude-statusline.{json,yaml}` (global) ← **Recommended**\n4. Environment variables (legacy v1.0 support)\n\n*Only JSON and YAML formats are supported. First configuration file found is used.*\n\n## Examples (ASCII)\n\n### Default Behavior\n```bash\n# Basic truncation (default) - truncated at terminal width minus 10 chars\nclaude-statusline @ main [$!A] *Claude Sonnet 4.5 #27%\n\n# With environment context enabled\n# Set \"envContext\": true in config file\nclaude-statusline @ main [$!A] *Claude Sonnet 4.5 Node22.17.1 Py3.13.5 Docker28.3.3 #27%\n```\n\n### ASCII Mode (Fallback)\n```bash\n# With \"noEmoji\": true in config file\nclaude-statusline @ main [$!A] *Claude Sonnet 4.5\n```\n\n## Documentation\n\n📚 **Complete documentation available in the [`docs/`](./docs) directory:**\n\n- **[Configuration Guide](./docs/guide-01-configuration.md)** - Complete configuration options and examples\n- **[Migration Guide](./docs/MIGRATION.md)** - Migrating from bash v1.0 to TypeScript v2.0\n- **[Feature Comparison](./docs/FEATURE_COMPARISON.md)** - Detailed comparison between versions\n- **[Documentation Index](./docs/README.md)** - Overview of all documentation\n\n## Security\n\nEnhanced security with input validation and type safety:\n- **Input Validation**: Comprehensive validation for all inputs\n- **Command Injection Prevention**: Sanitized shell command execution\n- **Path Traversal Protection**: Comprehensive path validation\n- **Type Safety**: TypeScript compile-time and runtime validation\n\n## Dependencies\n\n- **Required**: Node.js \u003e= 22.6.0 or Bun \u003e= 1.0.0, Git (for status parsing)\n- **Runtime**: yaml, zod\n- **Development**: TypeScript, ESLint, Prettier\n\n## Troubleshooting\n\n**Common Issues:**\n- **Build failures**: `npm install \u0026\u0026 npm run build`\n- **Performance issues**: Clear cache `rm -rf /tmp/.claude-statusline-cache/`\n- **Symbol display**: Force ASCII mode with `\"noEmoji\": true` in config\n\n## ❓ Frequently Asked Questions\n\n### Performance\n**Q: Is it really fast enough for real-time use?**\nA: Yes! With Bun it runs in ~5ms, which is instantaneous for human perception. Even with Node.js it's only ~28ms.\n\n**Q: Why do some benchmarks show ~136ms?**\nA: Those include system startup overhead. The actual execution time is much faster (~5ms with Bun). What matters is that it feels instant to users.\n\n**Q: Should I use Bun or Node.js?**\nA: Use Bun if you can - it's 5x faster (~5ms vs ~28ms). Configure it as \"bun claude-statusline\" in your settings.json to get the performance benefits. Node.js is still plenty fast for daily use.\n\n### Installation\n**Q: Why is the download only 19KB?**\nA: We use esbuild to bundle everything into a single optimized file. No downloading 500+ files!\n\n**Q: Do I need Node.js installed?**\nA: Yes, or Bun. We recommend Bun for best performance, but Node.js works perfectly fine.\n\n### Configuration\n**Q: How do I see Node/Python versions?**\nA: Create `~/.claude/claude-statusline.json` with `{\"envContext\": true}`.\n\n**Q: Can I customize the symbols?**\nA: Yes! Set `\"noEmoji\": true` for ASCII mode, or use Nerd Fonts for emoji icons.\n\n## Contributing\n\nSee our [Contributing Guidelines](./CONTRIBUTING.md) for development setup and pull requests.\n\n## Changelog\n\nView [CHANGELOG.md](./CHANGELOG.md) for detailed version history and updates.\n\n## License\n\nApache License 2.0 - see [LICENSE](LICENSE) file for details.\n\n## 📦 Legacy: Bash v1.0\n\n\u003e **Note:** Version 2.0 (TypeScript) is recommended for all users. Bash v1.0 is maintained for legacy environments only.\n\nFor environments where Node.js/npm is not available:\n\n```bash\ncurl -L -o claude-statusline.sh https://github.com/shrwnsan/claude-statusline/releases/download/v1.0.0/claude-statusline.sh\nchmod +x claude-statusline.sh\n```\n\n**Limitations of v1.0:**\n- Unix/Linux only (no Windows support)\n- No configuration files\n- No npm distribution\n- Basic width detection only\n\nSee [Feature Comparison](./docs/FEATURE_COMPARISON.md) for details.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshrwnsan%2Fclaude-statusline","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshrwnsan%2Fclaude-statusline","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshrwnsan%2Fclaude-statusline/lists"}