claude-statusline 2.1.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.
Files changed (48) hide show
  1. package/LICENSE +203 -0
  2. package/README.md +362 -0
  3. package/bin/claude-statusline +22 -0
  4. package/dist/core/cache.d.ts +67 -0
  5. package/dist/core/cache.js +223 -0
  6. package/dist/core/cache.js.map +1 -0
  7. package/dist/core/config.d.ts +190 -0
  8. package/dist/core/config.js +192 -0
  9. package/dist/core/config.js.map +1 -0
  10. package/dist/core/security.d.ts +27 -0
  11. package/dist/core/security.js +154 -0
  12. package/dist/core/security.js.map +1 -0
  13. package/dist/env/context.d.ts +92 -0
  14. package/dist/env/context.js +295 -0
  15. package/dist/env/context.js.map +1 -0
  16. package/dist/git/native.d.ts +35 -0
  17. package/dist/git/native.js +141 -0
  18. package/dist/git/native.js.map +1 -0
  19. package/dist/git/status.d.ts +65 -0
  20. package/dist/git/status.js +256 -0
  21. package/dist/git/status.js.map +1 -0
  22. package/dist/index.bundle.js +11 -0
  23. package/dist/index.d.ts +9 -0
  24. package/dist/index.js +396 -0
  25. package/dist/index.js.map +1 -0
  26. package/dist/metafile.prod.json +473 -0
  27. package/dist/ui/symbols.d.ts +31 -0
  28. package/dist/ui/symbols.js +308 -0
  29. package/dist/ui/symbols.js.map +1 -0
  30. package/dist/ui/width.d.ts +29 -0
  31. package/dist/ui/width.js +261 -0
  32. package/dist/ui/width.js.map +1 -0
  33. package/dist/utils/runtime.d.ts +31 -0
  34. package/dist/utils/runtime.js +82 -0
  35. package/dist/utils/runtime.js.map +1 -0
  36. package/docs/ARCHITECTURE.md +336 -0
  37. package/docs/FEATURE_COMPARISON.md +178 -0
  38. package/docs/MIGRATION.md +354 -0
  39. package/docs/README.md +101 -0
  40. package/docs/eval-01-terminal-widths.md +519 -0
  41. package/docs/guide-01-configuration.md +277 -0
  42. package/docs/guide-02-troubleshooting.md +416 -0
  43. package/docs/guide-03-performance.md +183 -0
  44. package/docs/prd-01-typescript-perf-optimization.md +480 -0
  45. package/docs/research-01-sandbox-detection.md +169 -0
  46. package/docs/research-02-competitive-analysis.md +226 -0
  47. package/docs/research-03-platform-analysis.md +142 -0
  48. package/package.json +89 -0
@@ -0,0 +1,169 @@
1
+ # Sandbox Detection Research
2
+
3
+ ## Overview
4
+
5
+ This document documents research into detecting sandbox environments for statusline indicators, specifically for Claude Code statusline implementations.
6
+
7
+ ## Problem Statement
8
+
9
+ Claude Code statusline scripts run in a sanitized environment that doesn't receive the actual sandbox environment variables (like `SANDBOX_RUNTIME=1`). This makes automatic sandbox detection challenging.
10
+
11
+ ## Key Findings
12
+
13
+ ### 1. Environment Variable Limitations
14
+
15
+ **Claude Code Statusline Environment (from debug logs):**
16
+ ```
17
+ FEATURE=notset (CLAUDE_CODE_STATUSLINE_SHOW_SANDBOX not available)
18
+ TMPDIR=/var/folders/.../T/ (not /tmp/claude)
19
+ SANDBOX_RUNTIME=notset
20
+ CLAUDE_CODE_ENTRYPOINT=cli
21
+ ```
22
+
23
+ **Available Environment Variables:**
24
+ - `CLAUDE_CODE_ENTRYPOINT=cli` - Entry point indicator
25
+ - `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1` - **NOT a sandbox indicator** (only disables telemetry)
26
+
27
+ ### 2. Existing Statusline Projects Research
28
+
29
+ #### Container Detection Approaches (from Starship)
30
+
31
+ **File-based Detection Methods (Priority Order):**
32
+ 1. **/.dockerenv** - Docker container indicator
33
+ 2. **/proc/vz** + **/proc/bc** - OpenVZ detection
34
+ 3. **/dev/incus/sock** - Incus container socket
35
+ 4. **/run/.containerenv** - Podman/Others (parse for name/image)
36
+ 5. **/run/systemd/container** - SystemD containers
37
+ 6. **/run/host/container-manager** - OCI container manager
38
+
39
+ **Cross-platform Considerations:**
40
+ - Disabled on non-Linux systems entirely
41
+ - Special handling for WSL with systemd
42
+
43
+ #### Claude Code Statusline Projects
44
+
45
+ **Projects Examined:**
46
+ - rz1989s/claude-code-statusline
47
+ - dwillitzer/claude-statusline
48
+ - Owloops/claude-powerline
49
+ - sirmalloc/ccstatusline
50
+ - Ido-Levi/claude-code-tamagotchi
51
+
52
+ **Key Finding: No existing projects have solved sandbox detection.**
53
+
54
+ All projects focus on:
55
+ - Configuration detection
56
+ - Git repository detection
57
+ - MCP server monitoring
58
+ - Security (safe file handling, input validation)
59
+
60
+ None attempt to detect Claude Code's sandbox/restricted mode.
61
+
62
+ ### 3. Container Detection Methods for Adaptation
63
+
64
+ **Most Reliable Methods:**
65
+ ```bash
66
+ # File-based checks (most reliable in restricted environments)
67
+ if [[ -f "/.dockerenv" ]]; then echo "Docker"; fi
68
+ if [[ -d "/proc/vz" ]] && ! [[ -d "/proc/bc" ]]; then echo "OpenVZ"; fi
69
+ if [[ -S "/dev/incus/sock" ]]; then echo "Incus"; fi
70
+
71
+ # System-based detection
72
+ systemd-detect-virt --container 2>/dev/null
73
+ virt-what 2>/dev/null
74
+
75
+ # Process namespace analysis
76
+ cat /proc/1/cmdline | tr '\0' ' '
77
+ ```
78
+
79
+ **Environment-based Detection (Less Reliable):**
80
+ ```bash
81
+ # Container environment variables
82
+ grep -q "container=" /proc/1/environ
83
+ grep -q docker /proc/1/cgroup
84
+
85
+ # Kubernetes/OpenShift indicators
86
+ [[ -n "${KUBERNETES_PORT:-}" ]]
87
+ ```
88
+
89
+ ### 4. Potential Sandbox Detection Approaches
90
+
91
+ #### File-based Detection
92
+ - Look for Claude Code-specific files in `/tmp/claude*`
93
+ - Check for restricted filesystem access
94
+ - Test system file readability (`/proc/version`, `/etc/passwd`)
95
+
96
+ #### Command Availability Testing
97
+ - Sandboxes often restrict system commands
98
+ - Test for `uname`, `ps`, `systemctl` availability
99
+
100
+ #### Process Namespace Analysis
101
+ - Compare current PID namespace with init process
102
+ - Check if init process looks like system init
103
+
104
+ #### Resource Limitations
105
+ - Check memory/CPU limits typical of sandboxes
106
+ - Test network access restrictions
107
+
108
+ ## Implementation Challenges
109
+
110
+ ### 1. Environment Isolation
111
+ Claude Code sanitizes the environment passed to statusline scripts, removing sandbox-specific variables.
112
+
113
+ ### 2. False Positives
114
+ Container detection methods might trigger in non-sandbox development environments (Docker development containers, etc.).
115
+
116
+ ### 3. Cross-platform Complexity
117
+ Different methods work on Linux vs macOS vs Windows.
118
+
119
+ ### 4. Performance Impact
120
+ Detection methods must be fast enough for frequent statusline updates.
121
+
122
+ ## Current Implementation Status
123
+
124
+ ### What Works:
125
+ - ✅ Feature toggle via `CLAUDE_CODE_STATUSLINE_SHOW_SANDBOX=1`
126
+ - ✅ Manual sandbox indicator control
127
+ - ✅ Proper icon selection (Nerd Font vs fallback)
128
+ - ✅ Statusline integration
129
+
130
+ ### What Doesn't Work:
131
+ - ❌ Automatic sandbox detection
132
+ - ❌ Environment variable detection (sanitized)
133
+ - ❌ Reliable file-based detection (no Claude Code-specific files found)
134
+
135
+ ### Known Limitations:
136
+ - Claude Code doesn't pass sandbox state to statusline scripts
137
+ - No reliable Claude Code-specific sandbox indicators available
138
+ - Container detection methods designed for containers, not application sandboxing
139
+
140
+ ## Recommendations
141
+
142
+ ### Short-term:
143
+ - Use manual toggle approach with `CLAUDE_CODE_STATUSLINE_SHOW_SANDBOX=1`
144
+ - Document limitation for users
145
+ - Request feature from Claude Code team to pass sandbox state
146
+
147
+ ### Long-term:
148
+ - Implement multiple detection methods with confidence scoring
149
+ - Add configuration for custom detection rules
150
+ - Consider file-based monitoring for Claude Code-specific patterns
151
+
152
+ ## Future Research Directions
153
+
154
+ 1. **Claude Code Internal APIs**: Check if Claude Code exposes sandbox state through other means
155
+ 2. **Process Monitoring**: Monitor Claude Code process characteristics
156
+ 3. **Filesystem Analysis**: Look for Claude Code sandbox artifacts
157
+ 4. **Network Behavior**: Analyze network patterns in sandboxed vs non-sandboxed modes
158
+ 5. **Resource Usage**: Monitor memory/CPU patterns unique to sandboxed execution
159
+
160
+ ## References
161
+
162
+ - [Starship Container Module](https://github.com/starship/starship)
163
+ - [Claude Code Documentation](https://code.claude.com/docs)
164
+ - [Container Detection Methods](https://github.com/moby/moby/issues/18390)
165
+ - [SystemD Detection](https://www.freedesktop.org/software/systemd/man/systemd-detect-virt.html)
166
+
167
+ ---
168
+
169
+ **Note:** This represents current research as of the investigation date. Sandbox detection methods may evolve with Claude Code updates.
@@ -0,0 +1,226 @@
1
+ # Competitive Analysis Research
2
+
3
+ ## Overview
4
+
5
+ This document provides a comprehensive competitive analysis of existing Claude Code statusline projects to identify feature gaps, market positioning, and strategic opportunities for our statusline implementation.
6
+
7
+ ## Methodology
8
+
9
+ **Projects Analyzed:**
10
+ - rz1989s/claude-code-statusline
11
+ - dwillitzer/claude-statusline
12
+ - Owloops/claude-powerline
13
+ - sirmalloc/ccstatusline
14
+ - Ido-Levi/claude-code-tamagotchi
15
+
16
+ **Analysis Criteria:**
17
+ Feature comparison across 15 dimensions including performance, customization, environment support, and unique capabilities.
18
+
19
+ **Research Date:** November 2025
20
+
21
+ ## Competitive Landscape Matrix
22
+
23
+ ### Complete Feature Comparison
24
+
25
+ | **Criteria** | **rz1989s** | **dwillitzer** | **Owloops** | **sirmalloc** | **Ido-Levi** | **Our Project** |
26
+ |--------------|------------|---------------|-------------|---------------|--------------|-----------------|
27
+ | **Enhanced Environment Support** | Extensive (8+ envs) | Basic | Good | Good | Basic | Node.js, Python, Docker + sandbox detection |
28
+ | **Color Theme Support** | Excellent (18+ themes) | Good | Excellent (5+ themes) | Excellent | Basic | ASCII/Nerd Font modes |
29
+ | **Custom Format Strings** | Outstanding (227+ TOML) | Excellent (templates) | Very Good | Excellent | Basic | Environment variables only |
30
+ | **Performance Optimization** | Exceptional (<50ms) | Good (<50ms) | Good (~80ms) | Good (~80ms) | Fair (AI overhead) | ~99ms (36ms optimized) |
31
+ | **Parallel Processing** | Advanced (concurrent) | Basic | Good | Good | Basic | Sequential |
32
+ | **Automated Testing** | Comprehensive (77+ tests) | Limited | Good | Good | Basic | Manual testing |
33
+ | **Installation Scripts** | Outstanding (3-tier system) | Good | Excellent (npx) | Excellent (npx) | Good | Manual setup |
34
+ | **Documentation Quality** | Outstanding | Good | Very Good | Excellent | Very Good | Comprehensive docs |
35
+ | **Plugin Architecture** | Advanced (18 components) | Limited | Good | Excellent | Basic | Monolithic |
36
+ | **Configuration Files** | Outstanding (TOML) | Good | Very Good | Excellent | Good | Environment variables |
37
+ | **Sandbox Detection** | Good (restricted env) | Basic | Basic | Good | Basic | **Unique research area** |
38
+ | **Git Integration Depth** | Exceptional (advanced) | Basic | Very Good | Excellent | Basic | Comprehensive indicators |
39
+ | **Terminal Compatibility** | Outstanding | Good | Very Good | Excellent | Good | Cross-platform optimized |
40
+ | **Cross-platform Support** | Excellent | Good | Very Good | Outstanding | Good | macOS/Linux |
41
+ | **Error Handling** | Exceptional | Good | Good | Very Good | Good | Robust validation |
42
+
43
+ ## Market Segmentation Analysis
44
+
45
+ ### **Category 1: Enterprise-Grade Solutions**
46
+ **rz1989s/claude-code-statusline**
47
+ - **Strengths:** 227+ configuration options, enterprise caching, comprehensive testing
48
+ - **Target:** Enterprise users, complex workflows
49
+ - **Codebase:** 1000+ lines, TypeScript planned
50
+ - **Performance:** Sub-50ms with universal caching
51
+
52
+ ### **Category 2: Specialized Solutions**
53
+
54
+ **sirmalloc/ccstatusline**
55
+ - **Strengths:** TUI interface, Windows support, powerline features
56
+ - **Target:** Interactive configuration users, Windows developers
57
+ - **Codebase:** React-based, widget system
58
+ - **Performance:** ~80ms with async operations
59
+
60
+ **Ido-Levi/claude-code-tamagotchi**
61
+ - **Strengths:** AI-powered behavioral enforcement, virtual pet concept
62
+ - **Target:** Gamification enthusiasts, productivity hackers
63
+ - **Codebase:** AI integration with Groq API
64
+ - **Performance:** Variable (AI processing overhead)
65
+
66
+ **dwillitzer/claude-statusline**
67
+ - **Strengths:** Multi-provider AI support, intelligent token counting
68
+ - **Target:** Multi-AI platform users
69
+ - **Codebase:** Provider-agnostic design
70
+ - **Performance:** <50ms optimized
71
+
72
+ ### **Category 3: Balanced Solutions**
73
+
74
+ **Owloops/claude-powerline**
75
+ - **Strengths:** Powerline aesthetics, good customization
76
+ - **Target:** Visual customization enthusiasts
77
+ - **Codebase:** Modular widget system
78
+ - **Performance:** ~80ms with caching
79
+
80
+ ## Feature Saturation Analysis
81
+
82
+ ### 🔴 **TABLE STAKES - Universal Features**
83
+ These features are implemented by all major projects and are considered baseline expectations:
84
+
85
+ - **Performance <100ms:** All projects achieve sub-100ms response times
86
+ - **Cross-platform Support:** Universal macOS/Linux compatibility
87
+ - **Basic Git Integration:** Git repository status detection is standard
88
+ - **Environment Variables:** All projects support environment variable configuration
89
+ - **Terminal Compatibility:** Basic emoji/ASCII fallback support
90
+
91
+ ### 🟡 **COMPETITIVE DIFFERENTIATORS - High Adoption**
92
+ These features are implemented by 60-80% of advanced projects:
93
+
94
+ - **Color Theme Support (80%):** 4/5 projects offer multiple themes
95
+ - rz1989s: 18+ themes including Catppuccin variants
96
+ - Owloops: 5 built-in themes (dark, light, nord, tokyo-night, rose-pine)
97
+ - sirmalloc: Multiple themes with ANSI/256/truecolor
98
+ - dwillitzer: Provider-aware color coding
99
+
100
+ - **Custom Format Strings (80%):** 4/5 advanced projects offer user-defined formats
101
+ - rz1989s: 227+ TOML settings with template variables
102
+ - sirmalloc: Interactive TUI with custom widgets
103
+ - dwillitzer: Template system with %model%, %context%, %project%
104
+ - Owloops: CLI flags and config file templates
105
+
106
+ - **Enhanced Environment Support (60%):** 3/5 projects detect multiple runtimes
107
+ - rz1989s: Node.js, Python, Docker, Ruby, Go, Rust, Java
108
+ - Owloops: Multiple development environments
109
+ - sirmalloc: Node.js, Bun, Python, Git environments
110
+
111
+ ### 🟢 **BLUE OCEAN OPPORTUNITIES - Unique Differentiators**
112
+ These features represent unique market positioning opportunities:
113
+
114
+ - **Sandbox Detection:** **Only our project is actively researching this**
115
+ - **AI Integration:** Only Ido-Levi offers AI-powered statusline analysis
116
+ - **Enterprise Caching:** Only rz1989s provides enterprise-grade universal caching
117
+ - **Powerline Support:** Only sirmalloc and Owloops implement powerline aesthetics
118
+ - **Multi-provider Support:** Only dwillitzer supports multiple AI providers
119
+
120
+ ## Strategic Positioning Analysis
121
+
122
+ ### **Our Competitive Advantages**
123
+
124
+ 1. **Unique Research Focus:** Sandbox detection is an unsolved problem
125
+ 2. **Academic Documentation:** Research-driven approach differentiates from feature-focused competitors
126
+ 3. **Focused Simplicity:** 284 lines vs competitors' 1000+ lines maintainability
127
+ 4. **Security-First Design:** Robust input validation and command injection protection
128
+ 5. **Performance Clarity:** Transparent performance metrics and optimization strategies
129
+
130
+ ### **Market Position**
131
+ **"The Security-Focused Research-Driven Statusline"**
132
+
133
+ - Differentiates through academic approach to unsolved problems
134
+ - Targets security-conscious developers and enterprise environments
135
+ - Positions as the most thoroughly documented and analyzed solution
136
+
137
+ ## Implementation Gap Analysis
138
+
139
+ ### **HIGH PRIORITY - Competitive Necessity**
140
+ Missing features that create competitive disadvantage:
141
+
142
+ 1. **Color Theme Support**
143
+ - **Competitive Gap:** 4/5 major projects implement this
144
+ - **Implementation Effort:** Medium - requires color system architecture
145
+ - **User Impact:** High - visual customization is highly valued
146
+ - **Timeline:** 2-3 weeks for basic implementation
147
+
148
+ 2. **Custom Format Strings**
149
+ - **Competitive Gap:** 4/5 advanced projects offer this
150
+ - **Implementation Effort:** High - requires configuration system redesign
151
+ - **User Impact:** High - customization flexibility expected by power users
152
+ - **Timeline:** 4-6 weeks for comprehensive implementation
153
+
154
+ ### **MEDIUM PRIORITY - Market Differentiation**
155
+ Features that strengthen competitive position:
156
+
157
+ 3. **Enhanced Environment Support**
158
+ - **Competitive Gap:** Behind rz1989s, ahead of dwillitzer/Ido-Levi
159
+ - **Implementation Effort:** Low-Medium - leverage existing detection patterns
160
+ - **User Impact:** Medium - valuable for polyglot environments
161
+ - **Timeline:** 1-2 weeks for Ruby/Go/Rust support
162
+
163
+ 4. **Parallel Processing**
164
+ - **Competitive Gap:** Only rz1989s has advanced concurrent operations
165
+ - **Implementation Effort:** High - requires architecture redesign
166
+ - **User Impact:** Medium-High - performance improvement
167
+ - **Timeline:** 3-4 weeks for full concurrent implementation
168
+
169
+ ### **LOW PRIORITY - Strategic Innovation**
170
+ Unique differentiator investments:
171
+
172
+ 5. **Sandbox Detection Completion**
173
+ - **Competitive Gap:** **Blue Ocean - no competitors**
174
+ - **Implementation Effort:** Medium - research foundation exists
175
+ - **User Impact:** High - solves unique Claude Code problem
176
+ - **Timeline:** 2-3 weeks for production implementation
177
+
178
+ ## Development Roadmap Recommendations
179
+
180
+ ### **Phase 1: Competitive Parity (Weeks 1-4)**
181
+ 1. **Week 1-2:** Implement basic color theme system
182
+ 2. **Week 3-4:** Add custom format string support
183
+ 3. **Outcome:** Feature parity with 80% of competitors
184
+
185
+ ### **Phase 2: Strategic Differentiation (Weeks 5-8)**
186
+ 1. **Week 5-6:** Complete sandbox detection implementation
187
+ 2. **Week 7-8:** Enhanced environment support (Ruby, Go, Rust)
188
+ 3. **Outcome:** Unique market position with competitive feature set
189
+
190
+ ### **Phase 3: Performance Optimization (Weeks 9-12)**
191
+ 1. **Week 9-10:** Parallel processing architecture
192
+ 2. **Week 11-12:** Advanced performance optimizations
193
+ 3. **Outcome:** Performance leadership alongside feature completeness
194
+
195
+ ## Success Metrics
196
+
197
+ ### **Adoption Metrics**
198
+ - GitHub stars growth rate vs competitors
199
+ - Issue resolution time and community engagement
200
+ - Documentation quality assessments
201
+
202
+ ### **Technical Metrics**
203
+ - Performance benchmarks (target: <50ms full feature set)
204
+ - Code maintainability (lines of code vs feature complexity)
205
+ - Test coverage (target: 80%+ for new features)
206
+
207
+ ### **Market Position Metrics**
208
+ - Feature completeness score vs competitors
209
+ - Unique differentiator recognition (sandbox detection)
210
+ - Security and documentation standards leadership
211
+
212
+ ## Conclusion
213
+
214
+ The competitive analysis reveals a crowded but fragmented market with clear opportunities for differentiation. Our project's unique research-driven approach and focus on unsolved problems (sandbox detection) provides a strong foundation for market positioning.
215
+
216
+ **Key Strategic Insights:**
217
+ 1. **Immediate Need:** Color themes and custom formats for competitive parity
218
+ 2. **Unique Opportunity:** Sandbox detection as blue ocean differentiator
219
+ 3. **Market Position:** Security-focused, research-driven statusline solution
220
+ 4. **Competitive Advantage:** Academic documentation and problem-solving approach
221
+
222
+ The recommended implementation roadmap prioritizes competitive necessity while building toward unique market differentiation through innovative research and security-focused design.
223
+
224
+ ---
225
+
226
+ **Note:** This analysis represents the competitive landscape as of November 2025. The statusline ecosystem evolves rapidly, and competitive positions may shift with new releases and feature additions.
@@ -0,0 +1,142 @@
1
+ # Platform Distribution Analysis and Windows Support Decision
2
+
3
+ ## Executive Summary
4
+
5
+ This document analyzes the platform distribution of CLI tool users and provides justification for focusing on Unix-like systems (macOS, Linux, WSL) rather than providing native Windows support for the TypeScript rewrite of claude-statusline.
6
+
7
+ ## Research Findings
8
+
9
+ ### 1. Official Claude Code CLI Platform Support
10
+ - **macOS 10.15+**
11
+ - **Linux (Ubuntu 20.04+/Debian 10+)**
12
+ - **Windows 10+** via WSL 1/2 or Git for Windows
13
+
14
+ ### 2. Developer Platform Statistics (2024-2025)
15
+
16
+ #### Operating System Distribution
17
+ - **Windows**: 59.2% (personal), 47.8% (professional)
18
+ - **macOS**: 31.8% (personal), 31.8% (professional)
19
+ - **Linux distributions**: ~27-28% (Ubuntu being the most popular)
20
+ - **WSL specifically**: 17.1% (personal), 16.8% (professional)
21
+
22
+ #### Node.js/npm Platform Distribution
23
+ - **Linux**: 78% of downloads
24
+ - **Windows**: 17% of downloads
25
+ - **macOS**: 5% of downloads
26
+
27
+ ### 3. Windows Developer Behavior Patterns
28
+
29
+ #### WSL Adoption Trends
30
+ - Rapid growth between 2021-2023
31
+ - WSL is now open source (Microsoft Build 2025)
32
+ - 17% of developers use WSL as their primary development environment
33
+
34
+ #### Terminal Tool Preferences on Windows
35
+ 1. **WSL**: Provides authentic Linux environment at kernel level
36
+ - Preferred by professional developers for CLI tools
37
+ - Full Linux integration, not just emulation
38
+ - Seamlessly runs Unix-like tools
39
+
40
+ 2. **Git Bash**: Simple but limited
41
+ - "Painfully slow" for complex operations
42
+ - Basic Unix command support
43
+ - Not a true Linux environment
44
+
45
+ 3. **PowerShell**: Powerful but different paradigm
46
+ - Windows-native, object-oriented pipeline
47
+ - Incompatible with Unix-like tool conventions
48
+ - Requires Windows-specific adaptations
49
+
50
+ ### 4. CLI Tool Usage Patterns
51
+
52
+ #### Evidence from Community
53
+ - Multiple third-party guides for running Claude Code on Windows via WSL
54
+ - Reddit threads show confusion about native Windows support
55
+ - General consensus: "Claude Code requires macOS or Linux to run properly"
56
+ - Windows users actively seek WSL solutions for CLI tools
57
+
58
+ #### Node.js Ecosystem Insight
59
+ - 78% Linux downloads suggest serious CLI development happens on Unix-like systems
60
+ - Professional developers prefer Unix-like environments for Node.js development
61
+ - CLI tool ecosystem primarily targets Unix-like systems
62
+
63
+ ## Decision: Target Unix-Like Systems Only
64
+
65
+ ### Rationale
66
+
67
+ 1. **WSL Covers Windows Developers**
68
+ - Most Windows developers using CLI tools already use WSL
69
+ - WSL provides a genuine Linux environment where Unix tools work natively
70
+ - No loss of functionality for Windows users willing to use WSL
71
+
72
+ 2. **Complexity vs Benefit**
73
+ - Native Windows support requires significant complexity
74
+ - Cross-platform abstractions (like simple-git) add overhead
75
+ - Minimal user base for native Windows CLI tools
76
+
77
+ 3. **Performance Optimization**
78
+ - Eliminating Windows-specific code improves performance
79
+ - Simpler code base is easier to optimize and maintain
80
+ - Unix-only implementation is more efficient
81
+
82
+ 4. **Development Velocity**
83
+ - Focus on primary use case (95% of users)
84
+ - Reduced testing surface
85
+ - Faster iteration and improvements
86
+
87
+ ### Implementation Strategy
88
+
89
+ #### Phase 1: Remove Windows-Specific Code
90
+ 1. Replace simple-git with native git commands using `child_process.spawn`
91
+ 2. Remove Windows-specific path handling
92
+ 3. Simplify git operations for Unix-like systems only
93
+ 4. Add proper error messages for native Windows users directing to WSL
94
+
95
+ #### Phase 2: Update Documentation
96
+ 1. Document WSL as the recommended Windows approach
97
+ 2. Update system requirements to clarify Unix-like focus
98
+ 3. Add installation guide for WSL setup
99
+ 4. Remove references to Git Bash/PowerShell support
100
+
101
+ #### Phase 3: Communication (Future Release)
102
+ 1. Frame as performance optimization, not dropping support
103
+ 2. Emphasize that existing WSL users are unaffected
104
+ 3. Provide clear migration path for any Windows users
105
+
106
+ ## Impact Analysis
107
+
108
+ ### Benefits
109
+ - **Performance**: 5ms improvement from simple-git removal (per performance optimization plan)
110
+ - **Simplicity**: Reduced code complexity and maintenance burden
111
+ - **Testing**: Fewer platform combinations to test
112
+ - **Development**: Faster feature development and bug fixes
113
+
114
+ ### Risks
115
+ - **Minimal**: Windows CLI developers already use WSL
116
+ - **Mitigation**: Clear documentation and helpful error messages
117
+ - **Fallback**: Can reconsider if significant demand emerges
118
+
119
+ ## Sources
120
+ - Stack Overflow Developer Survey 2024-2025
121
+ - Node.js Statistics 2024-2025
122
+ - Microsoft Build 2025 announcements
123
+ - WSL adoption trend analysis
124
+ - Claude Code GitHub issues and community discussions
125
+ - Terminal tool usage patterns research
126
+
127
+ ## Conclusion
128
+
129
+ The data strongly supports focusing on Unix-like systems for the TypeScript rewrite. WSL provides adequate coverage for Windows developers who need CLI tools, while eliminating native Windows support significantly simplifies the code base and improves performance.
130
+
131
+ This decision aligns with the broader trend in the developer ecosystem where professional Windows developers increasingly use WSL for Unix-like tooling, and the Node.js ecosystem's strong Linux preference (78% of downloads).
132
+
133
+ ## Next Steps for simple-git Replacement
134
+
135
+ Based on this analysis and the performance optimization plan in `docs/prd-01-typescript-perf-optimization.md`:
136
+
137
+ 1. **Replace simple-git** with native `child_process.spawn` commands (5ms improvement)
138
+ 2. **Remove Windows-specific code** and path handling complexity
139
+ 3. **Update documentation** to clarify WSL as the recommended Windows approach
140
+ 4. **Keep existing parsing logic** - only the command execution needs to change
141
+
142
+ The implementation is already outlined in Phase 1, Task 1.1 of the performance optimization plan, indicating it's a straightforward change.
package/package.json ADDED
@@ -0,0 +1,89 @@
1
+ {
2
+ "name": "claude-statusline",
3
+ "version": "2.1.2",
4
+ "description": "Simple statusline for Claude Code with git indicators. TypeScript rewrite for performance and npm distribution.",
5
+ "main": "dist/index.bundle.js",
6
+ "bin": {
7
+ "claude-statusline": "bin/claude-statusline"
8
+ },
9
+ "type": "module",
10
+ "scripts": {
11
+ "build": "tsc",
12
+ "build:bundle": "node esbuild.config.js",
13
+ "build:prod": "node esbuild.prod.config.js && npm run build:types",
14
+ "build:types": "tsc --emitDeclarationOnly",
15
+ "dev": "tsc --watch",
16
+ "dev:bundle": "node esbuild.config.js --watch",
17
+ "start": "node dist/index.js",
18
+ "start:bundle": "node dist/index.js",
19
+ "test": "node --test --experimental-strip-types tests/**/*.test.ts",
20
+ "test:bundle": "npm run build:bundle && npm test",
21
+ "lint": "eslint src/**/*.ts",
22
+ "format": "prettier --write src/**/*.ts",
23
+ "benchmark": "node scripts/benchmark.js",
24
+ "benchmark:bundle": "npm run build:bundle && npm run benchmark",
25
+ "prepublishOnly": "npm run build:prod && npm test",
26
+ "bun:build": "bun build src/index.ts --outdir dist --target node",
27
+ "bun:build:bundle": "node esbuild.config.js",
28
+ "bun:dev": "bun --watch src/index.ts",
29
+ "bun:start": "bun src/index.ts",
30
+ "bun:start:bundle": "bun dist/index.js",
31
+ "bun:test": "bun test tests/**/*.test.ts",
32
+ "bun:benchmark": "bun scripts/benchmark.js",
33
+ "bun:benchmark:bundle": "npm run build:bundle && bun scripts/benchmark.js"
34
+ },
35
+ "keywords": [
36
+ "claude-code",
37
+ "statusline",
38
+ "git",
39
+ "cli",
40
+ "terminal",
41
+ "productivity"
42
+ ],
43
+ "author": "shrwnsan",
44
+ "license": "Apache-2.0",
45
+ "repository": {
46
+ "type": "git",
47
+ "url": "https://github.com/shrwnsan/claude-statusline.git"
48
+ },
49
+ "bugs": {
50
+ "url": "https://github.com/shrwnsan/claude-statusline/issues"
51
+ },
52
+ "homepage": "https://github.com/shrwnsan/claude-statusline#readme",
53
+ "engines": {
54
+ "node": ">=22.6.0",
55
+ "bun": ">=1.0.0"
56
+ },
57
+ "dependencies": {
58
+ "yaml": "^2.6.1",
59
+ "zod": "^3.23.8"
60
+ },
61
+ "devDependencies": {
62
+ "@types/node": "^22.10.1",
63
+ "@typescript-eslint/eslint-plugin": "^8.18.0",
64
+ "@typescript-eslint/parser": "^8.18.0",
65
+ "esbuild": "^0.27.1",
66
+ "eslint": "^9.17.0",
67
+ "eslint-config-prettier": "^9.1.0",
68
+ "eslint-plugin-prettier": "^5.2.1",
69
+ "prettier": "^3.4.2",
70
+ "typescript": "^5.7.2"
71
+ },
72
+ "files": [
73
+ "dist/",
74
+ "bin/",
75
+ "README.md",
76
+ "LICENSE",
77
+ "docs/"
78
+ ],
79
+ "exports": {
80
+ ".": {
81
+ "import": "./dist/index.bundle.js",
82
+ "types": "./dist/index.d.ts"
83
+ },
84
+ "./config": {
85
+ "import": "./dist/core/config.js",
86
+ "types": "./dist/core/config.d.ts"
87
+ }
88
+ }
89
+ }