@chongdashu/cc-statusline 1.3.0 โ†’ 1.3.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,311 +1,374 @@
1
- # cc-statusline
2
-
3
- <div align="center">
4
-
5
- **A beautiful, informative statusline for Claude Code**
6
-
7
- <img src="docs/images/cc-statusline.png" alt="cc-statusline in action" width="600">
8
-
9
- *Real-time directory, git branch, model info, costs, and session time tracking*
10
-
11
- [![npm version](https://badge.fury.io/js/@chongdashu%2Fcc-statusline.svg)](https://www.npmjs.com/package/@chongdashu/cc-statusline)
12
- [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
13
- [![Node.js](https://img.shields.io/badge/Node.js-16%2B-green.svg)](https://nodejs.org/)
14
-
15
- </div>
16
-
17
- ## โšก Quick Start
18
-
19
- **One command. Three questions. Custom statusline.**
20
-
21
- ```bash
22
- npx @chongdashu/cc-statusline@latest init
23
- ```
24
-
25
- That's it! Answer a few simple questions, restart Claude Code, and enjoy your new statusline.
26
-
27
- ### ๐Ÿ†• Installation Options (v1.2.4+)
28
- - **๐Ÿ  Global Installation** (`~/.claude/`) - Use across all your projects
29
- - **๐Ÿ“‚ Project Installation** (`./.claude/`) - Keep settings project-specific
30
-
31
- ### ๐Ÿ“ˆ What's New in v1.3.0
32
- - **๐Ÿ”ฅ Improved Burn Rate** - Now calculates $/hour directly from Claude Code data (no ccusage dependency)
33
- - **๐Ÿ“ Smart Logging** - Logs are created relative to statusline installation location
34
- - **โœจ Version Headers** - Generated statuslines now include the cc-statusline version
35
-
36
- ## ๐ŸŽฏ Simple Setup
37
-
38
- <img src="docs/images/cc-statusline-init.gif" alt="Demo of cc-statusline setup" width="500">
39
-
40
- ## โœจ What You Get
41
-
42
- Enhance your Claude Code terminal with useful information:
43
-
44
- - **๐Ÿ“ Directory Display** - Current folder with `~` abbreviation
45
- - **๐ŸŒฟ Git Integration** - Current branch name
46
- - **๐Ÿค– Model Info** - Shows which Claude model you're using plus Claude Code version
47
- - **๐Ÿง  Context Usage** - Real-time context window usage with progress bars
48
- - **๐Ÿ’ฐ Cost Tracking** - Live cost monitoring with burn rates via ccusage
49
- - **โŒ› Session Timer** - Time remaining until usage limit resets
50
- - **๐Ÿ“Š Token Analytics** - Token consumption and burn rate metrics
51
- - **๐ŸŽจ Color Support** - 256-color palette for Claude Code terminals
52
- - **โšก Fast Execution** - Optimized bash script with <100ms execution time
53
-
54
- ## ๐ŸŽ›๏ธ Features Overview
55
-
56
- ### ๐Ÿ”ฅ Default Features (All Pre-selected in v1.2.2+)
57
- | Feature | Description | Example |
58
- |---------|-------------|---------|
59
- | ๐Ÿ“ **Directory** | Current working directory | `~/my-project` |
60
- | ๐ŸŒฟ **Git Branch** | Active git branch | `feature/statusline` |
61
- | ๐Ÿค– **Model** | Claude model name & version | `Sonnet 4` |
62
- | ๐Ÿ“Ÿ **Claude Code** | Claude Code version | `v1.0.85` |
63
- | ๐ŸŽจ **Output Style** | Current output style setting | `default` |
64
- | ๐Ÿง  **Context** | Remaining context with progress bar | `83% [========--]` |
65
- | ๐Ÿ’ฐ **Cost** | Live costs with highlighted burn rate | `$49.00 ($16.55/h)` |
66
- | โŒ› **Session** | Time until reset with progress | `3h 7m until reset at 01:00 (37%) [===-------]` |
67
-
68
- ### ๐Ÿš€ Power Features (Also Pre-selected)
69
- | Feature | Description | Example |
70
- |---------|-------------|---------|
71
- | ๐Ÿ“Š **Tokens** | Token consumption with burn rate | `14638846 tok (279900 tpm)` |
72
-
73
- ### ๐ŸŽจ Example Outputs
74
-
75
- **New 3-Line Modern Layout (v1.2.2+):**
76
- ```
77
- ๐Ÿ“ ~/Projects/cc-statusline ๐ŸŒฟ feature/context-usage-output-styles ๐Ÿค– Sonnet 4 ๐Ÿ“Ÿ v1.0.85 ๐ŸŽจ default
78
- ๐Ÿง  Context Remaining: 83% [========--] โŒ› 3h 7m until reset at 01:00 (37%) [===-------]
79
- ๐Ÿ’ฐ $49.00 ($16.55/h) ๐Ÿ“Š 14638846 tok (279900 tpm)
80
- ```
81
-
82
- **Compact Mode:**
83
- ```
84
- ๐Ÿ“ ~/my-app ๐ŸŒฟ main ๐Ÿค– Claude Sonnet ๐Ÿ“Ÿ v1.0.85
85
- ๐Ÿง  Context Remaining: 95% [=========-]
86
- ๐Ÿ’ฐ $2.48 ($12.50/h)
87
- ```
88
-
89
- ## ๐Ÿ› ๏ธ Advanced Usage
90
-
91
- ### Preview Your Statusline
92
- Test your statusline before restarting Claude Code:
93
-
94
- ```bash
95
- cc-statusline preview .claude/statusline.sh
96
- ```
97
-
98
- **What preview does:**
99
- 1. ๐Ÿ“„ **Loads** your actual statusline script
100
- 2. ๐Ÿงช **Runs** it with realistic mock data
101
- 3. ๐Ÿ“Š **Shows** exactly what the output will look like
102
- 4. โšก **Reports** performance metrics and functionality
103
-
104
- ### Installation Safety Features (v1.2.4+)
105
- - ๐Ÿ”’ **Safe Updates** - Never overwrites existing statuslines without confirmation
106
- - ๐Ÿ›ก๏ธ **Settings Protection** - Preserves your existing settings.json configurations
107
- - โš ๏ธ **Conflict Detection** - Warns when other statuslines are configured
108
- - โœ… **Smart Defaults** - Project-level installation by default for safety
109
-
110
- ### Custom Installation
111
- ```bash
112
- # Generate to custom location
113
- cc-statusline init --output ./my-statusline.sh
114
-
115
- # Skip auto-installation (manual setup)
116
- cc-statusline init --no-install
117
-
118
- # Global installation for convenience
119
- npm install -g @chongdashu/cc-statusline
120
- ```
121
-
122
- ## ๐Ÿ”ง How It Works
123
-
124
- ### How It Works
125
-
126
- 1. **๐ŸŽฏ Configuration** - Two questions configure your preferences
127
- 2. **๐Ÿ—๏ธ Generation** - Creates optimized bash script tailored to your needs
128
- 3. **โš™๏ธ Installation** - Integrates with Claude Code settings
129
- 4. **๐Ÿ”„ Updates** - Connects to ccusage for live usage statistics
130
-
131
- ### Technical Architecture
132
-
133
- - **โšก Bash-First** - Native shell execution for maximum speed
134
- - **๐ŸŽจ Claude Code Optimized** - Forces colors for Claude Code terminals (respects NO_COLOR)
135
- - **๐ŸŒ Environment Respect** - Honors `NO_COLOR` and other terminal conventions
136
- - **๐Ÿ“ฆ Zero Dependencies** - Self-contained script with graceful fallbacks
137
- - **๐Ÿ”’ Secure** - No network requests except ccusage integration
138
-
139
- ## ๐Ÿ“‹ Requirements
140
-
141
- ### โœ… Required (You Already Have These!)
142
- - **Claude Code** - The tool you're already using
143
- - **jq** - JSON processing (pre-installed on most systems)
144
-
145
- ### ๐ŸŽ Optional Enhancements
146
- - **git** - For branch display (you probably have this)
147
- - **ccusage** - For usage stats (works via `npx` - no install needed)
148
-
149
- ### Quick Compatibility Check
150
- ```bash
151
- command -v jq && echo "โœ… Ready to go!"
152
- ```
153
-
154
- ## ๐Ÿ“‚ File Structure
155
-
156
- After installation, you'll have a clean setup:
157
-
158
- ```
159
- .claude/
160
- โ”œโ”€โ”€ statusline.sh # ๐ŸŽฏ Your generated statusline script
161
- โ””โ”€โ”€ settings.json # โš™๏ธ Auto-updated Claude Code configuration
162
- ```
163
-
164
- ### Manual Configuration (Backup Plan)
165
-
166
- If auto-configuration fails, simply add this to `.claude/settings.json`:
167
-
168
- ```json
169
- {
170
- "statusLine": {
171
- "type": "command",
172
- "command": ".claude/statusline.sh",
173
- "padding": 0
174
- }
175
- }
176
- ```
177
-
178
- ## ๐Ÿ”ง Troubleshooting
179
-
180
- ### ๐Ÿšซ Statusline Not Showing
181
- 1. **Restart Claude Code** after installation
182
- 2. **Verify settings** - Check `.claude/settings.json` contains the configuration above
183
- 3. **Check permissions** - Ensure script is executable: `chmod +x .claude/statusline.sh`
184
-
185
- ### ๐ŸŒ Performance Issues
186
- - **Test performance**: `cc-statusline preview .claude/statusline.sh`
187
- - **Optimize features**: Disable heavy features if execution > 500ms
188
- - **Disable ccusage**: Remove usage tracking if not needed
189
-
190
- ### ๐Ÿงฉ Missing Features
191
- - **Install jq**: `brew install jq` (macOS) or `apt install jq` (Ubuntu)
192
- - **ccusage setup**: Works automatically via `npx ccusage@latest`
193
- - **Git not found**: Install git for branch display
194
- - **Context not showing**: Ensure you're in an active Claude Code session with context usage
195
- - **Colors not working**: Check that NO_COLOR environment variable is not set
196
-
197
- ## ๐Ÿš€ Performance
198
-
199
- | Metric | Target | Typical |
200
- |--------|--------|---------|
201
- | **Execution Time** | <100ms | 45-80ms |
202
- | **Memory Usage** | <5MB | ~2MB |
203
- | **CPU Impact** | Negligible | <1% |
204
- | **Dependencies** | Minimal | jq only |
205
-
206
- *Benchmarked on macOS with all features enabled*
207
-
208
- ## ๐Ÿค Contributing
209
-
210
- Contributions are welcome!
211
-
212
- **Quick Start:**
213
- ```bash
214
- git clone https://github.com/chongdashu/cc-statusline
215
- cd cc-statusline
216
- npm install && npm run build
217
- ```
218
-
219
- **Contribution Areas:**
220
- - ๐Ÿ› **Bug Fixes** - Help make it more robust
221
- - โœจ **New Features** - Add support for more runtimes/features
222
- - ๐Ÿ“š **Documentation** - Improve guides and examples
223
- - ๐Ÿงช **Testing** - Add test coverage and edge cases
224
-
225
- See our [Contributing Guide](CONTRIBUTING.md) for detailed information.
226
-
227
- ## ๐Ÿงช Testing
228
-
229
- ### Locking Mechanism Tests
230
-
231
- The ccusage integration includes a robust file-based locking mechanism to prevent concurrent process spawning. Test this functionality:
232
-
233
- **Single Test:**
234
- ```bash
235
- echo '{}' | ./test/test-statusline-with-lock.sh
236
- ```
237
-
238
- **Concurrent Test:**
239
- ```bash
240
- ./test/test-concurrent-locking.sh
241
- ```
242
-
243
- **Manual Concurrent Test:**
244
- ```bash
245
- # Spawn 10 concurrent processes
246
- for i in {1..10}; do
247
- echo '{}' | ./test/test-statusline-with-lock.sh &
248
- done
249
- ```
250
-
251
- **Expected Behavior:**
252
- - โœ… Only 1 process runs ccusage at a time
253
- - โœ… Other processes skip gracefully (no pile-up)
254
- - โœ… Lock files are properly cleaned up
255
- - โœ… No hanging processes remain
256
-
257
- **Verification Commands:**
258
- ```bash
259
- # Check for stale locks
260
- ls /tmp/ccusage_statusline.* 2>/dev/null || echo "โœ… No locks remain"
261
-
262
- # Monitor running processes
263
- ps aux | grep ccusage | grep -v grep
264
- ```
265
-
266
- ## ๐Ÿ“Š Stats
267
-
268
- <div align="center">
269
-
270
- ![GitHub stars](https://img.shields.io/github/stars/chongdashu/cc-statusline?style=social)
271
- ![GitHub forks](https://img.shields.io/github/forks/chongdashu/cc-statusline?style=social)
272
- ![npm downloads](https://img.shields.io/npm/dm/@chongdashu/cc-statusline)
273
-
274
- </div>
275
-
276
- ## ๐Ÿ”— Related Projects
277
-
278
- - **[ccusage](https://github.com/ryoppippi/ccusage)** - Claude Code usage analytics (would not be possible with it!)
279
- - **[Claude Code](https://docs.anthropic.com/en/docs/claude-code)** - Official documentation
280
-
281
- ## ๐Ÿ‘ฅ Contributors
282
-
283
- We're grateful for all contributions that make cc-statusline better!
284
-
285
- - **[Jonathan Borgwing (@DevVig)](https://github.com/DevVig)** - Critical performance fix for infinite ccusage process spawning ([#4](https://github.com/chongdashu/cc-statusline/pull/4))
286
-
287
- ### How to Contribute
288
-
289
- Want to see your name here? Check out our [Contributing Guide](CONTRIBUTING.md) and help make cc-statusline even better!
290
-
291
- We welcome:
292
- - ๐Ÿ› Bug fixes and performance improvements
293
- - โœจ New features and enhancements
294
- - ๐Ÿ“š Documentation improvements
295
- - ๐Ÿงช Test coverage and quality assurance
296
-
297
- ## ๐Ÿ“ Changelog
298
-
299
- See [CHANGELOG.md](CHANGELOG.md) for detailed release history.
300
-
301
- ## ๐Ÿ“„ License
302
-
303
- MIT License - see [LICENSE](LICENSE) file for details.
304
-
305
- ---
306
-
307
- <div align="center">
308
-
309
- **Made by [Chong-U](https://github.com/chongdashu) @ [AIOriented](https://aioriented.dev)**
310
-
1
+ # cc-statusline
2
+
3
+ <div align="center">
4
+
5
+ **A beautiful, informative statusline for Claude Code**
6
+
7
+ <img src="docs/images/cc-statusline.png" alt="cc-statusline in action" width="600">
8
+
9
+ *Real-time directory, git branch, model info, costs, and session time tracking*
10
+
11
+ [![npm version](https://badge.fury.io/js/@chongdashu%2Fcc-statusline.svg)](https://www.npmjs.com/package/@chongdashu/cc-statusline)
12
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
13
+ [![Node.js](https://img.shields.io/badge/Node.js-16%2B-green.svg)](https://nodejs.org/)
14
+
15
+ </div>
16
+
17
+ ## โš ๏ธ IMPORTANT: Install jq First!
18
+
19
+ > **Without jq, your statusline will have LIMITED functionality:**
20
+ > - โŒ No context remaining percentage
21
+ > - โŒ No token statistics from ccusage
22
+ > - โŒ Slower performance
23
+ > - โŒ Less reliable JSON parsing
24
+
25
+ ### Install jq (takes 30 seconds):
26
+
27
+ #### macOS
28
+ ```bash
29
+ brew install jq
30
+ ```
31
+
32
+ #### Linux
33
+ ```bash
34
+ # Ubuntu/Debian
35
+ sudo apt-get install jq
36
+
37
+ # CentOS/RHEL
38
+ sudo yum install jq
39
+ ```
40
+
41
+ #### Windows 10/11 Users
42
+
43
+ **Option 1: Package Manager (Easiest)**
44
+ ```bash
45
+ # If you have Chocolatey
46
+ choco install jq
47
+
48
+ # If you have Scoop
49
+ scoop install jq
50
+ ```
51
+
52
+ **Option 2: Manual Download (No admin required)**
53
+ 1. Go to https://github.com/jqlang/jq/releases/latest
54
+ 2. Download the right file for your system:
55
+ - **64-bit Windows** (most common): Download `jq-windows-amd64.exe`
56
+ - **32-bit Windows** (older systems): Download `jq-windows-i386.exe`
57
+ 3. Rename the downloaded file to just `jq.exe`
58
+ 4. Move `jq.exe` to one of these locations:
59
+ - `C:\Windows\System32\` (requires admin) - works everywhere
60
+ - Or create `C:\tools\` and add it to your PATH
61
+ 5. **Add to PATH** (if not in System32):
62
+ - Press `Win + X`, select "System"
63
+ - Click "Advanced system settings"
64
+ - Click "Environment Variables"
65
+ - Under "User variables", select "Path" and click "Edit"
66
+ - Click "New" and add `C:\tools\` (or wherever you put jq.exe)
67
+ - Click OK on all windows
68
+ 6. **Test it**: Open a new Command Prompt or PowerShell and type `jq --version`
69
+
70
+ ๐Ÿ“ฆ **Direct downloads:** https://github.com/jqlang/jq/releases
71
+
72
+ ---
73
+
74
+ ## โšก Quick Start
75
+
76
+ **After installing jq, one command. Three questions. Custom statusline.**
77
+
78
+ ```bash
79
+ npx @chongdashu/cc-statusline@latest init
80
+ ```
81
+
82
+ That's it! Answer a few simple questions, restart Claude Code, and enjoy your new statusline.
83
+
84
+ ### ๐Ÿ“‹ Prerequisites
85
+ - **Node.js 16+** (required)
86
+ - **jq** (STRONGLY recommended) - Required for context tracking, token stats, and reliable performance
87
+
88
+ ### ๐Ÿ†• Installation Options (v1.2.4+)
89
+ - **๐Ÿ  Global Installation** (`~/.claude/`) - Use across all your projects
90
+ - **๐Ÿ“‚ Project Installation** (`./.claude/`) - Keep settings project-specific
91
+
92
+ ### ๐Ÿ“ˆ What's New in v1.3.0
93
+ - **๐Ÿ”ฅ Improved Burn Rate** - Now calculates $/hour directly from Claude Code data (no ccusage dependency)
94
+ - **๐Ÿ“ Smart Logging** - Logs are created relative to statusline installation location
95
+ - **โœจ Version Headers** - Generated statuslines now include the cc-statusline version
96
+
97
+ ## ๐ŸŽฏ Simple Setup
98
+
99
+ <img src="docs/images/cc-statusline-init.gif" alt="Demo of cc-statusline setup" width="500">
100
+
101
+ ## โœจ What You Get
102
+
103
+ โš ๏ธ **Note: Most features require jq to be installed!**
104
+
105
+ Enhance your Claude Code terminal with useful information:
106
+
107
+ - **๐Ÿ“ Directory Display** - Current folder with `~` abbreviation
108
+ - **๐ŸŒฟ Git Integration** - Current branch name
109
+ - **๐Ÿค– Model Info** - Shows which Claude model you're using plus Claude Code version
110
+ - **๐Ÿง  Context Usage** - Real-time context window usage with progress bars **(requires jq)**
111
+ - **๐Ÿ’ฐ Cost Tracking** - Live cost monitoring with burn rates via ccusage **(partial without jq)**
112
+ - **โŒ› Session Timer** - Time remaining until usage limit resets **(requires jq)**
113
+ - **๐Ÿ“Š Token Analytics** - Token consumption and burn rate metrics **(requires jq)**
114
+ - **๐ŸŽจ Color Support** - 256-color palette for Claude Code terminals
115
+ - **โšก Fast Execution** - Optimized bash script with <100ms execution time
116
+
117
+ ## ๐ŸŽ›๏ธ Features Overview
118
+
119
+ ### ๐Ÿ”ฅ Default Features (All Pre-selected in v1.2.2+)
120
+ | Feature | Description | Example |
121
+ |---------|-------------|---------|
122
+ | ๐Ÿ“ **Directory** | Current working directory | `~/my-project` |
123
+ | ๐ŸŒฟ **Git Branch** | Active git branch | `feature/statusline` |
124
+ | ๐Ÿค– **Model** | Claude model name & version | `Sonnet 4` |
125
+ | ๐Ÿ“Ÿ **Claude Code** | Claude Code version | `v1.0.85` |
126
+ | ๐ŸŽจ **Output Style** | Current output style setting | `default` |
127
+ | ๐Ÿง  **Context** | Remaining context with progress bar | `83% [========--]` |
128
+ | ๐Ÿ’ฐ **Cost** | Live costs with highlighted burn rate | `$49.00 ($16.55/h)` |
129
+ | โŒ› **Session** | Time until reset with progress | `3h 7m until reset at 01:00 (37%) [===-------]` |
130
+
131
+ ### ๐Ÿš€ Power Features (Also Pre-selected)
132
+ | Feature | Description | Example |
133
+ |---------|-------------|---------|
134
+ | ๐Ÿ“Š **Tokens** | Token consumption with burn rate | `14638846 tok (279900 tpm)` |
135
+
136
+ ### ๐ŸŽจ Example Outputs
137
+
138
+ **New 3-Line Modern Layout (v1.2.2+):**
139
+ ```
140
+ ๐Ÿ“ ~/Projects/cc-statusline ๐ŸŒฟ feature/context-usage-output-styles ๐Ÿค– Sonnet 4 ๐Ÿ“Ÿ v1.0.85 ๐ŸŽจ default
141
+ ๐Ÿง  Context Remaining: 83% [========--] โŒ› 3h 7m until reset at 01:00 (37%) [===-------]
142
+ ๐Ÿ’ฐ $49.00 ($16.55/h) ๐Ÿ“Š 14638846 tok (279900 tpm)
143
+ ```
144
+
145
+ **Compact Mode:**
146
+ ```
147
+ ๐Ÿ“ ~/my-app ๐ŸŒฟ main ๐Ÿค– Claude Sonnet ๐Ÿ“Ÿ v1.0.85
148
+ ๐Ÿง  Context Remaining: 95% [=========-]
149
+ ๐Ÿ’ฐ $2.48 ($12.50/h)
150
+ ```
151
+
152
+ ## ๐Ÿ› ๏ธ Advanced Usage
153
+
154
+ ### Preview Your Statusline
155
+ Test your statusline before restarting Claude Code:
156
+
157
+ ```bash
158
+ cc-statusline preview .claude/statusline.sh
159
+ ```
160
+
161
+ **What preview does:**
162
+ 1. ๐Ÿ“„ **Loads** your actual statusline script
163
+ 2. ๐Ÿงช **Runs** it with realistic mock data
164
+ 3. ๐Ÿ“Š **Shows** exactly what the output will look like
165
+ 4. โšก **Reports** performance metrics and functionality
166
+
167
+ ### Installation Safety Features (v1.2.4+)
168
+ - ๐Ÿ”’ **Safe Updates** - Never overwrites existing statuslines without confirmation
169
+ - ๐Ÿ›ก๏ธ **Settings Protection** - Preserves your existing settings.json configurations
170
+ - โš ๏ธ **Conflict Detection** - Warns when other statuslines are configured
171
+ - โœ… **Smart Defaults** - Project-level installation by default for safety
172
+
173
+ ### Custom Installation
174
+ ```bash
175
+ # Generate to custom location
176
+ cc-statusline init --output ./my-statusline.sh
177
+
178
+ # Skip auto-installation (manual setup)
179
+ cc-statusline init --no-install
180
+
181
+ # Global installation for convenience
182
+ npm install -g @chongdashu/cc-statusline
183
+ ```
184
+
185
+ ## ๐Ÿ”ง How It Works
186
+
187
+ ### How It Works
188
+
189
+ 1. **๐ŸŽฏ Configuration** - Two questions configure your preferences
190
+ 2. **๐Ÿ—๏ธ Generation** - Creates optimized bash script tailored to your needs
191
+ 3. **โš™๏ธ Installation** - Integrates with Claude Code settings
192
+ 4. **๐Ÿ”„ Updates** - Connects to ccusage for live usage statistics
193
+
194
+ ### Technical Architecture
195
+
196
+ - **โšก Bash-First** - Native shell execution for maximum speed
197
+ - **๐ŸŽจ Claude Code Optimized** - Forces colors for Claude Code terminals (respects NO_COLOR)
198
+ - **๐ŸŒ Environment Respect** - Honors `NO_COLOR` and other terminal conventions
199
+ - **๐Ÿ“ฆ Zero Dependencies** - Self-contained script with graceful fallbacks
200
+ - **๐Ÿ”’ Secure** - No network requests except ccusage integration
201
+
202
+ ## ๐Ÿ“‹ Requirements
203
+
204
+ ### โœ… Required (You Already Have These!)
205
+ - **Claude Code** - The tool you're already using
206
+ - **jq** - JSON processing (pre-installed on most systems)
207
+
208
+ ### ๐ŸŽ Optional Enhancements
209
+ - **git** - For branch display (you probably have this)
210
+ - **ccusage** - For usage stats (works via `npx` - no install needed)
211
+
212
+ ### Quick Compatibility Check
213
+ ```bash
214
+ command -v jq && echo "โœ… Ready to go!"
215
+ ```
216
+
217
+ ## ๐Ÿ“‚ File Structure
218
+
219
+ After installation, you'll have a clean setup:
220
+
221
+ ```
222
+ .claude/
223
+ โ”œโ”€โ”€ statusline.sh # ๐ŸŽฏ Your generated statusline script
224
+ โ””โ”€โ”€ settings.json # โš™๏ธ Auto-updated Claude Code configuration
225
+ ```
226
+
227
+ ### Manual Configuration (Backup Plan)
228
+
229
+ If auto-configuration fails, simply add this to `.claude/settings.json`:
230
+
231
+ ```json
232
+ {
233
+ "statusLine": {
234
+ "type": "command",
235
+ "command": ".claude/statusline.sh",
236
+ "padding": 0
237
+ }
238
+ }
239
+ ```
240
+
241
+ ## ๐Ÿ”ง Troubleshooting
242
+
243
+ ### ๐Ÿšซ Statusline Not Showing
244
+ 1. **Restart Claude Code** after installation
245
+ 2. **Verify settings** - Check `.claude/settings.json` contains the configuration above
246
+ 3. **Check permissions** - Ensure script is executable: `chmod +x .claude/statusline.sh`
247
+
248
+ ### ๐ŸŒ Performance Issues
249
+ - **Test performance**: `cc-statusline preview .claude/statusline.sh`
250
+ - **Optimize features**: Disable heavy features if execution > 500ms
251
+ - **Disable ccusage**: Remove usage tracking if not needed
252
+
253
+ ### ๐Ÿงฉ Missing Features
254
+ - **Install jq**: `brew install jq` (macOS) or `apt install jq` (Ubuntu)
255
+ - **ccusage setup**: Works automatically via `npx ccusage@latest`
256
+ - **Git not found**: Install git for branch display
257
+ - **Context not showing**: Ensure you're in an active Claude Code session with context usage
258
+ - **Colors not working**: Check that NO_COLOR environment variable is not set
259
+
260
+ ## ๐Ÿš€ Performance
261
+
262
+ | Metric | Target | Typical |
263
+ |--------|--------|---------|
264
+ | **Execution Time** | <100ms | 45-80ms |
265
+ | **Memory Usage** | <5MB | ~2MB |
266
+ | **CPU Impact** | Negligible | <1% |
267
+ | **Dependencies** | Minimal | jq only |
268
+
269
+ *Benchmarked on macOS with all features enabled*
270
+
271
+ ## ๐Ÿค Contributing
272
+
273
+ Contributions are welcome!
274
+
275
+ **Quick Start:**
276
+ ```bash
277
+ git clone https://github.com/chongdashu/cc-statusline
278
+ cd cc-statusline
279
+ npm install && npm run build
280
+ ```
281
+
282
+ **Contribution Areas:**
283
+ - ๐Ÿ› **Bug Fixes** - Help make it more robust
284
+ - โœจ **New Features** - Add support for more runtimes/features
285
+ - ๐Ÿ“š **Documentation** - Improve guides and examples
286
+ - ๐Ÿงช **Testing** - Add test coverage and edge cases
287
+
288
+ See our [Contributing Guide](CONTRIBUTING.md) for detailed information.
289
+
290
+ ## ๐Ÿงช Testing
291
+
292
+ ### Locking Mechanism Tests
293
+
294
+ The ccusage integration includes a robust file-based locking mechanism to prevent concurrent process spawning. Test this functionality:
295
+
296
+ **Single Test:**
297
+ ```bash
298
+ echo '{}' | ./test/test-statusline-with-lock.sh
299
+ ```
300
+
301
+ **Concurrent Test:**
302
+ ```bash
303
+ ./test/test-concurrent-locking.sh
304
+ ```
305
+
306
+ **Manual Concurrent Test:**
307
+ ```bash
308
+ # Spawn 10 concurrent processes
309
+ for i in {1..10}; do
310
+ echo '{}' | ./test/test-statusline-with-lock.sh &
311
+ done
312
+ ```
313
+
314
+ **Expected Behavior:**
315
+ - โœ… Only 1 process runs ccusage at a time
316
+ - โœ… Other processes skip gracefully (no pile-up)
317
+ - โœ… Lock files are properly cleaned up
318
+ - โœ… No hanging processes remain
319
+
320
+ **Verification Commands:**
321
+ ```bash
322
+ # Check for stale locks
323
+ ls /tmp/ccusage_statusline.* 2>/dev/null || echo "โœ… No locks remain"
324
+
325
+ # Monitor running processes
326
+ ps aux | grep ccusage | grep -v grep
327
+ ```
328
+
329
+ ## ๐Ÿ“Š Stats
330
+
331
+ <div align="center">
332
+
333
+ ![GitHub stars](https://img.shields.io/github/stars/chongdashu/cc-statusline?style=social)
334
+ ![GitHub forks](https://img.shields.io/github/forks/chongdashu/cc-statusline?style=social)
335
+ ![npm downloads](https://img.shields.io/npm/dm/@chongdashu/cc-statusline)
336
+
337
+ </div>
338
+
339
+ ## ๐Ÿ”— Related Projects
340
+
341
+ - **[ccusage](https://github.com/ryoppippi/ccusage)** - Claude Code usage analytics (would not be possible with it!)
342
+ - **[Claude Code](https://docs.anthropic.com/en/docs/claude-code)** - Official documentation
343
+
344
+ ## ๐Ÿ‘ฅ Contributors
345
+
346
+ We're grateful for all contributions that make cc-statusline better!
347
+
348
+ - **[Jonathan Borgwing (@DevVig)](https://github.com/DevVig)** - Critical performance fix for infinite ccusage process spawning ([#4](https://github.com/chongdashu/cc-statusline/pull/4))
349
+
350
+ ### How to Contribute
351
+
352
+ Want to see your name here? Check out our [Contributing Guide](CONTRIBUTING.md) and help make cc-statusline even better!
353
+
354
+ We welcome:
355
+ - ๐Ÿ› Bug fixes and performance improvements
356
+ - โœจ New features and enhancements
357
+ - ๐Ÿ“š Documentation improvements
358
+ - ๐Ÿงช Test coverage and quality assurance
359
+
360
+ ## ๐Ÿ“ Changelog
361
+
362
+ See [CHANGELOG.md](CHANGELOG.md) for detailed release history.
363
+
364
+ ## ๐Ÿ“„ License
365
+
366
+ MIT License - see [LICENSE](LICENSE) file for details.
367
+
368
+ ---
369
+
370
+ <div align="center">
371
+
372
+ **Made by [Chong-U](https://github.com/chongdashu) @ [AIOriented](https://aioriented.dev)**
373
+
311
374
  </div>