WSL Integration

Automatic and Silent Synchronization between WSL and Windows Version: 3.13.2 | Last updated: February 2026

---

Table of Contents

1. What is WSL Auto-Sync?
2. Installation and Configuration
3. Activation Methods
4. Advanced Options
5. Use Cases
6. Troubleshooting
7. FAQ

---

What is WSL Auto-Sync?

The Problem It Solves

BEFORE (without auto-sync):

# 1. Edit file in WSL
vim /home/user/app.go

# 2. Manually copy to Windows
cp /home/user/app.go /mnt/c/Users/user/app.go

# 3. Repeat for EVERY change...

NOW (with auto-sync):

# 1. Edit file in WSL
vim /home/user/app.go

# 2. Automatically copied to Windows!
# No manual intervention
# No additional scripts
# Transparent and silent

Key Features

• Automatic: Syncs when writing/editing files
• Silent: No annoying logs (configurable)
• Asynchronous: Does not block your operations
• Intelligent: Only syncs what is necessary
• Configurable: Filters, exclusions, mappings

---

Installation and Configuration

Prerequisites

1. Windows 10/11 with WSL2
2. MCP Filesystem Ultra v3.4.0+
3. Run MCP from inside WSL

Verify WSL:

cat /proc/version
# Should contain "microsoft" or "WSL"

echo $WSL_DISTRO_NAME
# Should show: Ubuntu, Debian, etc.

Installing MCP

# 1. Clone repository
cd ~
git clone https://github.com/notcharliemarsh/mcp-filesystem-go-ultra.git
cd mcp-filesystem-go-ultra

# 2. Build
go build -o filesystem-ultra

# 3. Move to PATH (optional)
sudo mv filesystem-ultra /usr/local/bin/

---

Activation Methods

Method 1: Environment Variable (Fastest)

Temporary (current session only):

export MCP_WSL_AUTOSYNC=true
filesystem-ultra

Permanent (add to ~/.bashrc or ~/.zshrc):

echo 'export MCP_WSL_AUTOSYNC=true' >> ~/.bashrc
source ~/.bashrc

Verify:

echo $MCP_WSL_AUTOSYNC
# Output: true

---

Method 2: Configuration File (More Control)

Location: ~/.config/mcp-filesystem-ultra/autosync.json

Basic Configuration:

mkdir -p ~/.config/mcp-filesystem-ultra
cat > ~/.config/mcp-filesystem-ultra/autosync.json << 'EOF'
{
  "wsl_auto_sync": {
    "enabled": true,
    "sync_on_write": true,
    "sync_on_edit": true,
    "sync_on_delete": false,
    "silent": false,
    "config_version": "1.0"
  }
}
EOF

Advanced Configuration (with filters):

{
  "wsl_auto_sync": {
    "enabled": true,
    "sync_on_write": true,
    "sync_on_edit": true,
    "sync_on_delete": false,
    "silent": true,
    "exclude_patterns": [
      "*.tmp",
      "*.swp",
      "*.log",
      "node_modules/*",
      ".git/*",
      "__pycache__/*"
    ],
    "only_subdirs": [
      "/home/user/projects",
      "/home/user/documents"
    ],
    "target_mapping": {
      "/home/user/special/file.txt": "D:\\CustomLocation\\file.txt"
    },
    "config_version": "1.0"
  }
}

---

Method 3: MCP Tool (From Claude Desktop)

From Claude Desktop, use the MCP tool:

configure_autosync({
  enabled: true,
  sync_on_write: true,
  sync_on_edit: true,
  silent: true
})

Expected response:

Auto-sync enabled!

Files written/edited in WSL will be automatically copied to Windows.
You can disable it anytime with: configure_autosync({enabled: false})

---

Advanced Options

Configuration Options

Option	Type	Default	Description
enabled	bool	false	Enable/disable auto-sync
sync_on_write	bool	true	Sync when writing files
sync_on_edit	bool	true	Sync when editing files
sync_on_delete	bool	false	Delete in Windows when deleting in WSL
silent	bool	false	Hide synchronization logs
exclude_patterns	[]string	[]	File patterns to exclude
only_subdirs	[]string	[]	Only sync these directories
target_mapping	map	{}	Custom path mapping

---

Exclusion Filters

Syntax: Standard glob patterns

Examples:

{
  "exclude_patterns": [
    "*.tmp",
    "*.swp",
    "*.log",
    "node_modules/*",
    ".git/*",
    "__pycache__/*",
    "*.pyc",
    ".env",
    "secrets.json"
  ]
}

---

Selective Directory Synchronization

Only sync specific directories:

{
  "only_subdirs": [
    "/home/user/projects",
    "/home/user/documents",
    "/home/user/Desktop"
  ]
}

Behavior:

# Inside allowed subdirs -> SYNCS
echo "sync" > /home/user/projects/app.go    # Synced

# Outside allowed subdirs -> DOES NOT SYNC
echo "ignore" > /home/user/temp/test.txt    # Not synced

---

Custom Path Mapping

Redirect specific files to custom locations:

{
  "target_mapping": {
    "/home/user/config.json": "D:\\AppConfig\\config.json",
    "/home/user/logs/app.log": "C:\\Logs\\myapp.log"
  }
}

---

Use Cases

Case 1: Web Development in WSL + VSCode in Windows

Scenario: You work with Node.js in WSL but use VSCode in Windows.

Setup:

# 1. Enable auto-sync
export MCP_WSL_AUTOSYNC=true

# 2. Configure exclusions
cat > ~/.config/mcp-filesystem-ultra/autosync.json << 'EOF'
{
  "wsl_auto_sync": {
    "enabled": true,
    "silent": true,
    "exclude_patterns": ["node_modules/*", "*.log", ".git/*"]
  }
}
EOF

Workflow:

• Claude Desktop edits index.js in WSL
• Auto-sync copies to C:\Users\user\projects\webapp\index.js
• VSCode detects change and updates
• No manual intervention required

---

Case 2: Backup Scripts

Scenario: You generate backups in WSL that must be in Windows.

Setup:

{
  "wsl_auto_sync": {
    "enabled": true,
    "only_subdirs": ["/home/user/backups"],
    "target_mapping": {
      "/home/user/backups": "D:\\Backups"
    }
  }
}

---

Verification and Monitoring

Check Status

From Claude Desktop (MCP tool):

autosync_status()

Response:

Auto-Sync Status

Status: ENABLED
Environment: WSL
Windows User: username

Configuration:
  Sync on Write: true
  Sync on Edit: true
  Sync on Delete: false

Config File: /home/user/.config/mcp-filesystem-ultra/autosync.json

View Sync Logs

If silent: false:

[AutoSync] Synced: /home/user/test.txt -> C:\Users\user\test.txt
[AutoSync] Synced: /home/user/app.go -> C:\Users\user\app.go

If silent: true:

# No logs (silent)

---

Troubleshooting

Problem 1: Auto-sync not working

Symptoms: Files are not copied to Windows

Diagnosis:

# 1. Verify you are in WSL
cat /proc/version | grep -i microsoft
# Should contain "microsoft" or "WSL"

# 2. Verify environment variable
echo $MCP_WSL_AUTOSYNC
# Should be: true

# 3. Check status (from Claude Desktop)
autosync_status

Solution:

# If not in WSL -> Will not work (only works in WSL)

# If variable not set:
export MCP_WSL_AUTOSYNC=true

# Restart MCP
pkill filesystem-ultra
filesystem-ultra

---

Problem 2: Files copied to wrong path

Symptoms: Files appear in unexpected locations

Solution: Use target_mapping:

{
  "target_mapping": {
    "/home/user/file.txt": "C:\\CustomPath\\file.txt"
  }
}

---

Problem 3: Slow performance

Symptoms: Slow write/edit operations

Note: Auto-sync should NOT cause slowness (it is asynchronous)

Diagnosis:

# Measure time without auto-sync
unset MCP_WSL_AUTOSYNC
time echo "test" > /home/user/test1.txt

# Measure time WITH auto-sync
export MCP_WSL_AUTOSYNC=true
time echo "test" > /home/user/test2.txt

# Difference should be less than 10ms

---

Problem 4: Too many logs

Symptoms: Many [AutoSync] Synced: ... logs

Solution:

{
  "wsl_auto_sync": {
    "enabled": true,
    "silent": true
  }
}

---

FAQ

Does auto-sync work on native Windows?

No. Auto-sync only works when MCP runs inside WSL.

If you run MCP on native Windows, auto-sync is automatically disabled.

---

What happens if I delete a file in WSL?

Depends on configuration:

{
  "sync_on_delete": false  // Default - does NOT delete in Windows
}

{
  "sync_on_delete": true   // Also deletes in Windows
}

---

Can binary files be synced?

Yes. Auto-sync works with any file type (text, binaries, images, etc.).

---

How much space does auto-sync use?

Zero. Auto-sync does not duplicate files unnecessarily. It only copies what you change.

---

How do I temporarily disable auto-sync?

Option 1: Environment variable

unset MCP_WSL_AUTOSYNC

Option 2: MCP tool

configure_autosync({enabled: false})

---

Best Practices

DO

1. Use silent: true in production
2. Configure exclude_patterns for node_modules, .git, etc.
3. Use only_subdirs to limit synchronization
4. Verify status with autosync_status regularly

DO NOT

1. Do not sync large directories (e.g., /usr, /var)
2. Do not sync sensitive files (e.g., .env, secrets.json)
3. Do not rely on instantaneous sync (there is minimal latency due to async)
4. Do not use on production servers (only for local development)

---

Conclusion

WSL Auto-Sync makes working between WSL and Windows transparent and frictionless.

Enable auto-sync and forget about copying files manually.

---

Additional Resources:

• Report Issues

---

Version: 3.13.2 Last updated: February 2026