Add WSL setup guide with shared and separate strategies
This commit is contained in:
admin
562
WSL-SETUP.md
Normal file
562
WSL-SETUP.md
Normal file
@@ -0,0 +1,562 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user