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.
- package/LICENSE +203 -0
- package/README.md +362 -0
- package/bin/claude-statusline +22 -0
- package/dist/core/cache.d.ts +67 -0
- package/dist/core/cache.js +223 -0
- package/dist/core/cache.js.map +1 -0
- package/dist/core/config.d.ts +190 -0
- package/dist/core/config.js +192 -0
- package/dist/core/config.js.map +1 -0
- package/dist/core/security.d.ts +27 -0
- package/dist/core/security.js +154 -0
- package/dist/core/security.js.map +1 -0
- package/dist/env/context.d.ts +92 -0
- package/dist/env/context.js +295 -0
- package/dist/env/context.js.map +1 -0
- package/dist/git/native.d.ts +35 -0
- package/dist/git/native.js +141 -0
- package/dist/git/native.js.map +1 -0
- package/dist/git/status.d.ts +65 -0
- package/dist/git/status.js +256 -0
- package/dist/git/status.js.map +1 -0
- package/dist/index.bundle.js +11 -0
- package/dist/index.d.ts +9 -0
- package/dist/index.js +396 -0
- package/dist/index.js.map +1 -0
- package/dist/metafile.prod.json +473 -0
- package/dist/ui/symbols.d.ts +31 -0
- package/dist/ui/symbols.js +308 -0
- package/dist/ui/symbols.js.map +1 -0
- package/dist/ui/width.d.ts +29 -0
- package/dist/ui/width.js +261 -0
- package/dist/ui/width.js.map +1 -0
- package/dist/utils/runtime.d.ts +31 -0
- package/dist/utils/runtime.js +82 -0
- package/dist/utils/runtime.js.map +1 -0
- package/docs/ARCHITECTURE.md +336 -0
- package/docs/FEATURE_COMPARISON.md +178 -0
- package/docs/MIGRATION.md +354 -0
- package/docs/README.md +101 -0
- package/docs/eval-01-terminal-widths.md +519 -0
- package/docs/guide-01-configuration.md +277 -0
- package/docs/guide-02-troubleshooting.md +416 -0
- package/docs/guide-03-performance.md +183 -0
- package/docs/prd-01-typescript-perf-optimization.md +480 -0
- package/docs/research-01-sandbox-detection.md +169 -0
- package/docs/research-02-competitive-analysis.md +226 -0
- package/docs/research-03-platform-analysis.md +142 -0
- 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
|
+
}
|