claude-agents/WSL-SETUP.md

# WSL (Windows Subsystem for Linux) Sync Guide

Complete guide for syncing Claude Code agents and skills using WSL on Windows.

---

## 🎯 Why WSL is Better Than Native Windows

- ✅ **Same commands as Linux** - No path conversions or PowerShell/Batch differences
- ✅ **Native curl/git** - Skillshare installs with one command
- ✅ **Better performance** - Git operations are faster
- ✅ **Consistent with server** - Same environment as server-ai
- ✅ **Easy shell scripts** - Bash scripts work as-is

---

## 📋 Prerequisites

### Install WSL (If Not Already Installed)

```powershell
# In PowerShell as Administrator
wsl --install

# Or install specific distro
wsl --install -d Ubuntu-22.04

# Reboot Windows
```

### Verify WSL Installation

```bash
# Check WSL version (should be WSL 2)
wsl --version

# Enter WSL
wsl

# Check distro
cat /etc/os-release
```

---

## 🔀 Two Setup Strategies

### Strategy 1: Shared (Recommended)
**WSL and Windows Claude Code share the same skills/agents**

**Use when:**
- You use Claude Code in both WSL and Windows
- Want consistency across both environments
- Don't want duplicate files

### Strategy 2: Separate
**WSL has independent skills/agents, syncs separately**

**Use when:**
- Only use Claude Code in WSL *or* Windows, not both
- Need different skills for different environments
- Want complete isolation

---

## 🔗 Strategy 1: Shared Setup (WSL + Windows)

### Step 1: Install in Windows First

Follow the Windows guide to set up agents/skills in Windows:
- Agents: `C:\Users\YourName\.claude\agents`
- Skills: `C:\Users\YourName\.config\skillshare\skills`

### Step 2: Create Symlinks in WSL

```bash
# In WSL - Replace YourName with your Windows username

# Create .claude directory if it doesn't exist
mkdir -p ~/.claude

# Symlink agents (WSL points to Windows)
ln -s /mnt/c/Users/YourName/.claude/agents ~/.claude/agents

# Symlink skills target (for Claude Code in WSL)
ln -s /mnt/c/Users/YourName/.claude/skills ~/.claude/skills

# Symlink Skillshare source directory
mkdir -p ~/.config
ln -s /mnt/c/Users/YourName/.config/skillshare ~/.config/skillshare
```

### Step 3: Verify Symlinks

```bash
# Check symlinks
ls -la ~/.claude/
ls -la ~/.config/

# Should show:
# agents -> /mnt/c/Users/YourName/.claude/agents
# skills -> /mnt/c/Users/YourName/.claude/skills
# skillshare -> /mnt/c/Users/YourName/.config/skillshare
```

### Step 4: Install Skillshare in WSL (Optional)

```bash
# If you want to run skillshare commands from WSL
curl -fsSL https://raw.githubusercontent.com/runkids/skillshare/main/install.sh | sh

# Test
skillshare status
```

### Step 5: Daily Sync (From WSL)

```bash
# Pull agents (from WSL)
cd ~/.claude/agents  # Actually points to Windows directory
git pull origin main

# Pull skills (from WSL)
skillshare pull --remote  # Updates Windows skillshare directory
```

**How it works:**
- Both WSL and Windows Claude Code read from same directories
- Changes in WSL appear instantly in Windows (and vice versa)
- Git sync updates both environments automatically

---

## 🔧 Strategy 2: Separate Setup (WSL Only)

### Step 1: Install Git in WSL

```bash
# Update packages
sudo apt update

# Install git
sudo apt install git -y

# Configure git
git config --global user.name "admin"
git config --global user.email "admin@server-ai.local"
git config --global init.defaultBranch main
```

### Step 2: Clone Agents

```bash
# Clone agents to WSL
git clone https://admin:MyN3wP%40ssword%21@gitea.pressmess.duckdns.org/admin/claude-agents.git ~/.claude/agents

# Verify
ls ~/.claude/agents/
```

### Step 3: Install Skillshare

```bash
# Install Skillshare
curl -fsSL https://raw.githubusercontent.com/runkids/skillshare/main/install.sh | sh

# Verify
skillshare version
```

### Step 4: Setup Skills

```bash
# Initialize Skillshare
skillshare init --no-copy --all-targets --git

# Add remote
cd ~/.config/skillshare/skills
git remote add origin https://admin:MyN3wP%40ssword%21@gitea.pressmess.duckdns.org/admin/claude-skills.git

# Pull skills
skillshare pull --remote

# Verify
skillshare status
```

### Step 5: Daily Sync

```bash
# Same as Linux commands - pull agents
cd ~/.claude/agents && git pull

# Pull skills
skillshare pull --remote
```

---

## 🗂️ Understanding WSL Paths

### Accessing Windows from WSL

```bash
# Windows C: drive
/mnt/c/

# Windows user directory
/mnt/c/Users/YourName/

# Windows Claude directory
/mnt/c/Users/YourName/.claude/

# Windows Documents
/mnt/c/Users/YourName/Documents/
```

### Accessing WSL from Windows

```
# In Windows Explorer, type:
\\wsl$\Ubuntu\home\yourname\.claude\

# Or in PowerShell
cd \\wsl$\Ubuntu\home\yourname\.claude\
```

### Path Translations

| Windows | WSL |
|---------|-----|
| `C:\Users\YourName\` | `/mnt/c/Users/YourName/` |
| `%USERPROFILE%\.claude` | `/mnt/c/Users/YourName/.claude` |
| `D:\Projects\` | `/mnt/d/Projects/` |

---

## 🚀 Quick Setup Commands

### Shared Setup (Fastest)

```bash
# Run in WSL after Windows setup is complete
mkdir -p ~/.claude ~/.config
ln -s /mnt/c/Users/$(cmd.exe /c "echo %USERNAME%" | tr -d '\r')/.claude/agents ~/.claude/agents
ln -s /mnt/c/Users/$(cmd.exe /c "echo %USERNAME%" | tr -d '\r')/.claude/skills ~/.claude/skills
ln -s /mnt/c/Users/$(cmd.exe /c "echo %USERNAME%" | tr -d '\r')/.config/skillshare ~/.config/skillshare
```

### Separate Setup (Full Linux)

```bash
# Run in WSL
curl -fsSL https://raw.githubusercontent.com/runkids/skillshare/main/install.sh | sh
git clone https://admin:MyN3wP%40ssword%21@gitea.pressmess.duckdns.org/admin/claude-agents.git ~/.claude/agents
skillshare init --no-copy --all-targets --git
cd ~/.config/skillshare/skills
git remote add origin https://admin:MyN3wP%40ssword%21@gitea.pressmess.duckdns.org/admin/claude-skills.git
skillshare pull --remote
```

---

## 📝 WSL Shell Aliases

Add to `~/.bashrc` in WSL:

```bash
# Sync shortcuts
alias sync-agents='cd ~/.claude/agents && git pull origin main'
alias sync-skills='skillshare pull --remote'
alias sync-all='sync-agents && sync-skills'

# Push shortcuts
alias push-agents='cd ~/.claude/agents && git add . && git commit -m "Update from WSL" && git push'
alias push-skills='skillshare sync && skillshare push -m "Update from WSL"'

# Status shortcuts
alias agent-status='cd ~/.claude/agents && git status'
alias skill-status='skillshare status'

# Reload bashrc
source ~/.bashrc
```

Usage:
```bash
sync-all        # Pull both agents and skills
push-agents     # Push agent changes
skill-status    # Check skillshare status
```

---

## 🔄 Daily Workflow (WSL)

### Morning Sync

```bash
# Open WSL terminal
wsl

# Pull latest from all machines
sync-all  # Or manually:
cd ~/.claude/agents && git pull
skillshare pull --remote
```

### Working

```bash
# Create new agent
nano ~/.claude/agents/my-new-agent.md

# Create new skill
skillshare new my-helper
nano ~/.config/skillshare/skills/my-helper/SKILL.md
```

### Evening Push

```bash
# Push agents
cd ~/.claude/agents
git add .
git commit -m "Add my-new-agent"
git push origin main

# Push skills
skillshare sync
skillshare push -m "Add my-helper skill"
```

---

## 🛠️ WSL-Specific Tips

### 1. Performance

WSL 2 is fast, but accessing Windows files (`/mnt/c/`) is slower than native WSL files (`~/`).

**If using shared setup:**
- Acceptable for git pull/push
- Skillshare sync might be slightly slower

**If performance is critical:**
- Use separate setup (pure WSL paths)

### 2. Line Endings

Git in WSL handles line endings correctly by default:

```bash
# Verify (should be false or input)
git config --global core.autocrlf

# Set if needed
git config --global core.autocrlf input
```

### 3. File Permissions

Windows files accessed from WSL may have unusual permissions:

```bash
# If you see weird permissions like 777
# Add to ~/.bashrc or /etc/wsl.conf
echo "[automount]
options = metadata,umask=22,fmask=11" | sudo tee -a /etc/wsl.conf

# Restart WSL
wsl --shutdown
wsl
```

### 4. VS Code Integration

VS Code works great with WSL:

```bash
# In WSL, open VS Code
code ~/.claude/agents/
code ~/.config/skillshare/skills/

# VS Code will connect to WSL automatically
```

---

## 🐛 Troubleshooting WSL

### Symlink Not Working

```bash
# Check if symlink exists
ls -la ~/.claude/agents

# Remove broken symlink
rm ~/.claude/agents

# Recreate
ln -s /mnt/c/Users/YourName/.claude/agents ~/.claude/agents
```

### Permission Denied

```bash
# Check Windows directory permissions
ls -la /mnt/c/Users/YourName/.claude/

# If owned by root, fix permissions
sudo chown -R $(whoami):$(whoami) ~/.claude/
```

### Git Not Found in WSL

```bash
# Install git
sudo apt update
sudo apt install git -y
```

### Skillshare Not Found

```bash
# Check installation
which skillshare

# If not found, reinstall
curl -fsSL https://raw.githubusercontent.com/runkids/skillshare/main/install.sh | sh

# Add to PATH if needed
echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
```

### WSL Can't Access Windows Files

```bash
# Check if Windows drives are mounted
ls /mnt/c/

# If not mounted, check WSL config
cat /etc/wsl.conf

# Should have:
# [automount]
# enabled = true
```

---

## 🎯 Recommended Setup by Use Case

### Case 1: Claude Code in Both WSL and Windows
**Use: Shared Setup**
- Symlink WSL to Windows directories
- One set of skills/agents
- Sync from either environment

### Case 2: Claude Code Only in WSL
**Use: Separate Setup**
- Native WSL paths (~/.claude/)
- Better performance
- Pure Linux experience

### Case 3: Claude Code Only in Windows
**Use: Windows Native Setup**
- Don't need WSL for Claude Code
- But can use WSL for git commands (faster)
- Symlink Windows to WSL if desired

### Case 4: Development in WSL, Claude Code in Windows
**Use: Shared Setup**
- Code in WSL, run Claude in Windows
- Both access same skills/agents
- Best of both worlds

---

## 📊 Performance Comparison

| Operation | Native Windows | WSL (Shared) | WSL (Separate) |
|-----------|---------------|--------------|----------------|
| Git clone | Medium | Medium | Fast |
| Git pull | Medium | Medium | Fast |
| Skillshare sync | Medium | Slow | Fast |
| File access | Fast | Slow | Fast |
| Overall | Medium | Medium | **Fastest** |

**Recommendation**: If performance matters, use separate WSL setup.

---

## 🔐 Credentials in WSL

### Option 1: Store in Git URL (Already Configured)

```bash
# Already set in remote URL
https://admin:MyN3wP%40ssword%21@gitea.pressmess.duckdns.org/...
```

### Option 2: Git Credential Helper

```bash
# Install credential helper
git config --global credential.helper store

# First pull/push will prompt for password
# Then stored in ~/.git-credentials
```

### Option 3: SSH Keys

```bash
# Generate SSH key in WSL
ssh-keygen -t ed25519 -C "admin@wsl"

# Copy public key
cat ~/.ssh/id_ed25519.pub

# Add to Gitea (Settings → SSH Keys)

# Update remotes
cd ~/.claude/agents
git remote set-url origin git@gitea.pressmess.duckdns.org:admin/claude-agents.git
```

---

## 📚 Resources

- **WSL Install**: https://learn.microsoft.com/en-us/windows/wsl/install
- **WSL Best Practices**: https://learn.microsoft.com/en-us/windows/wsl/setup/environment
- **VS Code + WSL**: https://code.visualstudio.com/docs/remote/wsl

---

## ✅ Quick Checklist

### Shared Setup:
- [ ] Install WSL
- [ ] Set up agents/skills in Windows
- [ ] Create symlinks from WSL to Windows
- [ ] Test: `ls ~/.claude/agents`
- [ ] Optional: Install Skillshare in WSL

### Separate Setup:
- [ ] Install WSL
- [ ] Install git in WSL
- [ ] Clone agents repo
- [ ] Install Skillshare
- [ ] Initialize Skillshare with remote
- [ ] Test sync

---

**Last Updated**: 2026-01-29
**Version**: 1.0
**WSL Version**: WSL 2
**Tested With**: Ubuntu 22.04, Ubuntu 24.04