From 3bc8e225f426e64e5bc1ecfe0db8387143efb024 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Nuno=20Salva=C3=A7=C3=A3o?= <nuno.salvacao@gmail.com>
Date: Tue, 16 Sep 2025 06:41:49 +0100
Subject: [PATCH] Update documentation with Windows-specific details (#82)

---
 README.md | 171 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 171 insertions(+)

diff --git a/README.md b/README.md
index 61e507f..8b7b8b3 100644
--- a/README.md
+++ b/README.md
@@ -34,6 +34,7 @@
 - [Recent Updates](#-recent-updates)
 - [Features](#-features)
 - [Quick Start](#-quick-start)
+- [Windows Support](#-windows-support)
 - [Usage](#-usage)
 - [API Documentation](#-api-documentation)
 - [Development](#️-development)
@@ -146,6 +147,176 @@ The interactive configuration tool provides a terminal UI where you can:
 
 ---
 
+## 🪟 Windows Support
+
+ccstatusline works seamlessly on Windows with full feature compatibility across PowerShell (5.1+ and 7+), Command Prompt, and Windows Subsystem for Linux (WSL).
+
+### Installation on Windows
+
+#### Option 1: Using Bun (Recommended)
+```powershell
+# Install Bun for Windows
+irm bun.sh/install.ps1 | iex
+
+# Run ccstatusline
+bunx ccstatusline@latest
+```
+
+#### Option 2: Using Node.js
+```powershell
+# Using npm
+npx ccstatusline@latest
+
+# Or with Yarn
+yarn dlx ccstatusline@latest
+
+# Or with pnpm
+pnpm dlx ccstatusline@latest
+```
+
+### Windows-Specific Features
+
+#### Powerline Font Support
+For optimal Powerline rendering on Windows:
+
+**Windows Terminal** (Recommended):
+- Supports Powerline fonts natively
+- Download from [Microsoft Store](https://aka.ms/terminal)
+- Auto-detects compatible fonts
+
+**PowerShell/Command Prompt**:
+```powershell
+# Install JetBrains Mono Nerd Font via winget
+winget install DEVCOM.JetBrainsMonoNerdFont
+
+# Alternative: Install base JetBrains Mono font
+winget install "JetBrains.JetBrainsMono"
+
+# Or download manually from: https://www.nerdfonts.com/font-downloads
+```
+
+#### Path Handling
+ccstatusline automatically handles Windows-specific paths:
+- Git repositories work with both `/` and `\` path separators
+- Current Working Directory widget displays Windows-style paths correctly
+- Full support for mapped network drives and UNC paths
+- Handles Windows drive letters (C:, D:, etc.)
+
+### Windows Troubleshooting
+
+#### Common Issues & Solutions
+
+**Issue**: Powerline symbols showing as question marks or boxes
+```powershell
+# Solution: Install a compatible Nerd Font
+winget install JetBrainsMono.NerdFont
+# Then set the font in your terminal settings
+```
+
+**Issue**: Git commands not recognized
+```powershell
+# Check if Git is installed and in PATH
+git --version
+
+# If not found, install Git:
+winget install Git.Git
+# Or download from: https://git-scm.com/download/win
+```
+
+**Issue**: Permission errors during installation
+```powershell
+# Use non-global installation (recommended)
+npx ccstatusline@latest
+
+# Or run PowerShell as Administrator for global install
+```
+
+**Issue**: "Execution Policy" errors in PowerShell
+```powershell
+# Temporarily allow script execution
+Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
+```
+
+**Issue**: Windows Defender blocking execution
+```powershell
+# If Windows Defender flags the binary:
+# 1. Open Windows Security
+# 2. Go to "Virus & threat protection"
+# 3. Add exclusion for the ccstatusline binary location
+# Or use temporary bypass (not recommended for production):
+Add-MpPreference -ExclusionPath "$env:USERPROFILE\.bun\bin"
+```
+
+#### Windows Subsystem for Linux (WSL)
+ccstatusline works perfectly in WSL environments:
+
+```bash
+# Install in WSL Ubuntu/Debian
+curl -fsSL https://bun.sh/install | bash
+source ~/.bashrc
+bunx ccstatusline@latest
+```
+
+**WSL Benefits**:
+- Native Unix-style path handling
+- Better font rendering in WSL terminals
+- Seamless integration with Linux development workflows
+
+### Windows Terminal Configuration
+
+For the best experience, configure Windows Terminal with these recommended settings:
+
+#### Terminal Settings (settings.json)
+```json
+{
+  "profiles": {
+    "defaults": {
+      "font": {
+        "face": "JetBrainsMono Nerd Font",
+        "size": 12
+      },
+      "colorScheme": "One Half Dark"
+    }
+  }
+}
+```
+
+#### Claude Code Integration
+Configure ccstatusline in your Claude Code settings:
+
+**For Bun users** (Windows: `%USERPROFILE%\.claude\settings.json`):
+```json
+{
+  "statusLine": "bunx ccstatusline@latest"
+}
+```
+
+**For npm users**:
+```json
+{
+  "statusLine": "npx ccstatusline@latest"
+}
+```
+
+### Performance on Windows
+
+ccstatusline is optimized for Windows performance:
+- **Bun runtime**: Significantly faster startup times on Windows
+- **Caching**: Intelligent caching of git status and file operations
+- **Async operations**: Non-blocking command execution
+- **Memory efficient**: Minimal resource usage
+
+### Windows-Specific Widget Behavior
+
+Some widgets have Windows-specific optimizations:
+
+- **Current Working Directory**: Displays Windows drive letters and UNC paths
+- **Git Widgets**: Handle Windows line endings (CRLF) automatically  
+- **Custom Commands**: Support both PowerShell and cmd.exe commands
+- **Block Timer**: Accounts for Windows timezone handling
+
+---
+
 ## 📖 Usage
 
 Once configured, ccstatusline automatically formats your Claude Code status line. The status line appears at the bottom of your terminal during Claude Code sessions.