{"id":30444458,"url":"https://github.com/chongdashu/cc-statusline","last_synced_at":"2025-08-23T10:05:04.861Z","repository":{"id":309767989,"uuid":"1037269918","full_name":"chongdashu/cc-statusline","owner":"chongdashu","description":"Transform your Claude Code experience with a beautiful, informative statusline","archived":false,"fork":false,"pushed_at":"2025-08-20T21:46:37.000Z","size":52385,"stargazers_count":64,"open_issues_count":3,"forks_count":8,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-08-20T23:21:13.241Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/chongdashu.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}},"created_at":"2025-08-13T10:16:03.000Z","updated_at":"2025-08-20T22:13:02.000Z","dependencies_parsed_at":"2025-08-13T19:09:24.043Z","dependency_job_id":"4172abe3-70b7-4f61-b915-9f74669bef71","html_url":"https://github.com/chongdashu/cc-statusline","commit_stats":null,"previous_names":["chongdashu/cc-statusline"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/chongdashu/cc-statusline","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chongdashu%2Fcc-statusline","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chongdashu%2Fcc-statusline/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chongdashu%2Fcc-statusline/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chongdashu%2Fcc-statusline/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chongdashu","download_url":"https://codeload.github.com/chongdashu/cc-statusline/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chongdashu%2Fcc-statusline/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271746515,"owners_count":24813568,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-23T02:00:09.327Z","response_time":69,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":[],"created_at":"2025-08-23T10:02:16.912Z","updated_at":"2025-08-23T10:05:04.848Z","avatar_url":"https://github.com/chongdashu.png","language":"TypeScript","funding_links":[],"categories":["Usage Tracker"],"sub_categories":[],"readme":"# cc-statusline\n\n\u003cdiv align=\"center\"\u003e\n\n**A beautiful, informative statusline for Claude Code**\n\n\u003cimg src=\"docs/images/cc-statusline.png\" alt=\"cc-statusline in action\" width=\"600\"\u003e\n\n*Real-time directory, git branch, model info, costs, and session time tracking*\n\n[![npm version](https://badge.fury.io/js/@chongdashu%2Fcc-statusline.svg)](https://www.npmjs.com/package/@chongdashu/cc-statusline)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Node.js](https://img.shields.io/badge/Node.js-16%2B-green.svg)](https://nodejs.org/)\n\n\u003c/div\u003e\n\n## ⚡ Quick Start\n\n**One command. Two questions. Custom statusline.**\n\n```bash\nnpx @chongdashu/cc-statusline@latest init\n```\n\nThat's it! Answer 2 simple questions, restart Claude Code, and enjoy your new statusline.\n\n## 🎯 Simple Setup\n\n\u003cimg src=\"docs/images/cc-statusline-init.gif\" alt=\"Demo of cc-statusline setup\" width=\"500\"\u003e\n\n## ✨ What You Get\n\nEnhance your Claude Code terminal with useful information:\n\n- **📁 Directory Display** - Current folder with `~` abbreviation\n- **🌿 Git Integration** - Current branch name  \n- **🤖 Model Info** - Shows which Claude model you're using plus Claude Code version\n- **🧠 Context Usage** - Real-time context window usage with progress bars\n- **💰 Cost Tracking** - Live cost monitoring with burn rates via ccusage\n- **⌛ Session Timer** - Time remaining until usage limit resets\n- **📊 Token Analytics** - Token consumption and burn rate metrics\n- **🎨 Color Support** - 256-color palette for Claude Code terminals\n- **⚡ Fast Execution** - Optimized bash script with \u003c100ms execution time\n\n## 🎛️ Features Overview\n\n### 🔥 Default Features (All Pre-selected in v1.2.2+)\n| Feature | Description | Example |\n|---------|-------------|---------|\n| 📁 **Directory** | Current working directory | `~/my-project` |\n| 🌿 **Git Branch** | Active git branch | `feature/statusline` |\n| 🤖 **Model** | Claude model name \u0026 version | `Sonnet 4` |\n| 📟 **Claude Code** | Claude Code version | `v1.0.85` |\n| 🎨 **Output Style** | Current output style setting | `default` |\n| 🧠 **Context** | Remaining context with progress bar | `83% [========--]` |\n| 💰 **Cost** | Live costs with highlighted burn rate | `$49.00 ($16.55/h)` |\n| ⌛ **Session** | Time until reset with progress | `3h 7m until reset at 01:00 (37%) [===-------]` |\n\n### 🚀 Power Features (Also Pre-selected)\n| Feature | Description | Example |\n|---------|-------------|---------|\n| 📊 **Tokens** | Token consumption with burn rate | `14638846 tok (279900 tpm)` |\n\n### 🎨 Example Outputs\n\n**New 3-Line Modern Layout (v1.2.2+):**\n```\n📁 ~/Projects/cc-statusline  🌿 feature/context-usage-output-styles  🤖 Sonnet 4  📟 v1.0.85  🎨 default\n🧠 Context Remaining: 83% [========--]  ⌛ 3h 7m until reset at 01:00 (37%) [===-------]\n💰 $49.00 ($16.55/h)  📊 14638846 tok (279900 tpm)\n```\n\n**Compact Mode:**\n```\n📁 ~/my-app  🌿 main  🤖 Claude Sonnet  📟 v1.0.85\n🧠 Context Remaining: 95% [=========-]\n💰 $2.48 ($12.50/h)\n```\n\n## 🛠️ Advanced Usage\n\n### Preview Your Statusline\nTest your statusline before restarting Claude Code:\n\n```bash\ncc-statusline preview .claude/statusline.sh\n```\n\n**What preview does:**\n1. 📄 **Loads** your actual statusline script\n2. 🧪 **Runs** it with realistic mock data  \n3. 📊 **Shows** exactly what the output will look like\n4. ⚡ **Reports** performance metrics and functionality\n\n### Custom Installation\n```bash\n# Generate to custom location\ncc-statusline init --output ./my-statusline.sh\n\n# Skip auto-installation (manual setup)\ncc-statusline init --no-install\n\n# Global installation for convenience\nnpm install -g @chongdashu/cc-statusline\n```\n\n## 🔧 How It Works\n\n### How It Works\n\n1. **🎯 Configuration** - Two questions configure your preferences\n2. **🏗️ Generation** - Creates optimized bash script tailored to your needs  \n3. **⚙️ Installation** - Integrates with Claude Code settings\n4. **🔄 Updates** - Connects to ccusage for live usage statistics\n\n### Technical Architecture\n\n- **⚡ Bash-First** - Native shell execution for maximum speed\n- **🎨 Claude Code Optimized** - Forces colors for Claude Code terminals (respects NO_COLOR)\n- **🌍 Environment Respect** - Honors `NO_COLOR` and other terminal conventions\n- **📦 Zero Dependencies** - Self-contained script with graceful fallbacks\n- **🔒 Secure** - No network requests except ccusage integration\n\n## 📋 Requirements\n\n### ✅ Required (You Already Have These!)\n- **Claude Code** - The tool you're already using\n- **jq** - JSON processing (pre-installed on most systems)\n\n### 🎁 Optional Enhancements\n- **git** - For branch display (you probably have this)\n- **ccusage** - For usage stats (works via `npx` - no install needed)\n\n### Quick Compatibility Check\n```bash\ncommand -v jq \u0026\u0026 echo \"✅ Ready to go!\"\n```\n\n## 📂 File Structure\n\nAfter installation, you'll have a clean setup:\n\n```\n.claude/\n├── statusline.sh    # 🎯 Your generated statusline script\n└── settings.json    # ⚙️ Auto-updated Claude Code configuration\n```\n\n### Manual Configuration (Backup Plan)\n\nIf auto-configuration fails, simply add this to `.claude/settings.json`:\n\n```json\n{\n  \"statusLine\": {\n    \"type\": \"command\",\n    \"command\": \".claude/statusline.sh\",\n    \"padding\": 0\n  }\n}\n```\n\n## 🔧 Troubleshooting\n\n### 🚫 Statusline Not Showing\n1. **Restart Claude Code** after installation\n2. **Verify settings** - Check `.claude/settings.json` contains the configuration above\n3. **Check permissions** - Ensure script is executable: `chmod +x .claude/statusline.sh`\n\n### 🐌 Performance Issues\n- **Test performance**: `cc-statusline preview .claude/statusline.sh`\n- **Optimize features**: Disable heavy features if execution \u003e 500ms\n- **Disable ccusage**: Remove usage tracking if not needed\n\n### 🧩 Missing Features\n- **Install jq**: `brew install jq` (macOS) or `apt install jq` (Ubuntu)\n- **ccusage setup**: Works automatically via `npx ccusage@latest`\n- **Git not found**: Install git for branch display\n- **Context not showing**: Ensure you're in an active Claude Code session with context usage\n- **Colors not working**: Check that NO_COLOR environment variable is not set\n\n## 🚀 Performance\n\n| Metric | Target | Typical |\n|--------|--------|---------|\n| **Execution Time** | \u003c100ms | 45-80ms |\n| **Memory Usage** | \u003c5MB | ~2MB |\n| **CPU Impact** | Negligible | \u003c1% |\n| **Dependencies** | Minimal | jq only |\n\n*Benchmarked on macOS with all features enabled*\n\n## 🤝 Contributing\n\nContributions are welcome!\n\n**Quick Start:**\n```bash\ngit clone https://github.com/chongdashu/cc-statusline\ncd cc-statusline\nnpm install \u0026\u0026 npm run build\n```\n\n**Contribution Areas:**\n- 🐛 **Bug Fixes** - Help make it more robust\n- ✨ **New Features** - Add support for more runtimes/features  \n- 📚 **Documentation** - Improve guides and examples\n- 🧪 **Testing** - Add test coverage and edge cases\n\nSee our [Contributing Guide](CONTRIBUTING.md) for detailed information.\n\n## 🧪 Testing\n\n### Locking Mechanism Tests\n\nThe ccusage integration includes a robust file-based locking mechanism to prevent concurrent process spawning. Test this functionality:\n\n**Single Test:**\n```bash\necho '{}' | ./test/test-statusline-with-lock.sh\n```\n\n**Concurrent Test:**\n```bash\n./test/test-concurrent-locking.sh\n```\n\n**Manual Concurrent Test:**\n```bash\n# Spawn 10 concurrent processes\nfor i in {1..10}; do \n  echo '{}' | ./test/test-statusline-with-lock.sh \u0026 \ndone\n```\n\n**Expected Behavior:**\n- ✅ Only 1 process runs ccusage at a time\n- ✅ Other processes skip gracefully (no pile-up)\n- ✅ Lock files are properly cleaned up\n- ✅ No hanging processes remain\n\n**Verification Commands:**\n```bash\n# Check for stale locks\nls /tmp/ccusage_statusline.* 2\u003e/dev/null || echo \"✅ No locks remain\"\n\n# Monitor running processes\nps aux | grep ccusage | grep -v grep\n```\n\n## 📊 Stats\n\n\u003cdiv align=\"center\"\u003e\n\n![GitHub stars](https://img.shields.io/github/stars/chongdashu/cc-statusline?style=social)\n![GitHub forks](https://img.shields.io/github/forks/chongdashu/cc-statusline?style=social)\n![npm downloads](https://img.shields.io/npm/dm/@chongdashu/cc-statusline)\n\n\u003c/div\u003e\n\n## 🔗 Related Projects\n\n- **[ccusage](https://github.com/ryoppippi/ccusage)** - Claude Code usage analytics (would not be possible with it!)\n- **[Claude Code](https://docs.anthropic.com/en/docs/claude-code)** - Official documentation\n\n## 👥 Contributors\n\nWe're grateful for all contributions that make cc-statusline better! \n\n- **[Jonathan Borgwing (@DevVig)](https://github.com/DevVig)** - Critical performance fix for infinite ccusage process spawning ([#4](https://github.com/chongdashu/cc-statusline/pull/4))\n\n### How to Contribute\n\nWant to see your name here? Check out our [Contributing Guide](CONTRIBUTING.md) and help make cc-statusline even better!\n\nWe welcome:\n- 🐛 Bug fixes and performance improvements\n- ✨ New features and enhancements  \n- 📚 Documentation improvements\n- 🧪 Test coverage and quality assurance\n\n## 📝 Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for detailed release history.\n\n## 📄 License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**Made by [Chong-U](https://github.com/chongdashu) @ [AIOriented](https://aioriented.dev)**\n\n\u003c/div\u003e","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchongdashu%2Fcc-statusline","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchongdashu%2Fcc-statusline","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchongdashu%2Fcc-statusline/lists"}