This approach enables Windows tools and Linux workloads (Python, ML, CUDA) to run at full speed by eliminating the cross-filesystem bottleneck.

Introduction​

28% of developers use Windows, yet many need Linux for tools that don't run natively. WSL2 has become the standard solution, providing a full Linux kernel to run any popular distro - like Ubuntu, Debian, or Pop!OS.

The problem​

WSL2's major limitation: cross-platform filesystem operations are terribly slow.

I've created a benchmark to quantify the performance differences. The results are even worse than expected.

• WSL accessing the Windows filesystem (/mnt/c/) averages at ~6% of native performance, with random reads as low as 3% 🤔.
• Windows accessing the WSL filesystem (\\wsl.localhost\) averages at ~14%, with sequential writes for large files dropping below 1% performance 🤯.

In practice, this means that installing packages (yarn install), running the development server (yarn dev), or even checking the status of a Git repository (git status) can typically take 10-20x longer when crossing filesystem boundaries.

The solution​

We can completely circumvent the performance bottleneck by following a simple rule

• 💡 When working in Windows, use the Windows filesystem
• 💡 When working in Linux, use the Linux filesystem

This leaves us with a new problem:

• ❌ Changes to files and folders only reflected on one side

Both of which we can solve using:

• ✅ Real-time cross-system file synchronisation

There aren't many tools that do bidirectional local sync with conflict resolution well. But I've found a solution.

Alternatives​

Before we dive further into details, you might wonder: why not just use VMs or dual boot? It's a fair question.

I evaluated the following alternatives before settling on WSL with bi-directional sync.

TL;DR:

Type 2 hypervisors​

• ❌ VMware Workstation Pro: The pro version allows using host APIs to access the GPU and provides 3D acceleration, but not true passthrough (PCIe-level access). This limitation can be significant for machine learning workloads that expect direct GPU access.
• ⚠️ QEMU/KVM VFIO: QEMU on Windows 11 typically runs without hardware-assisted virtualization (like KVM), limiting its efficiency. Windows 11 lacks direct support for VFIO, inhibiting true GPU passthrough.

Since there is no passthrough, we would not be able to work with LLMs and other GPU workloads effectively.

Type 1 Hypervisors​

• ⚠️ VMware ESXi: The free version has limited GPU passthrough support. The paid version supports GPU passthrough (Direct Device Assignment), although no official support for consumer GPUs.
• ⚠️ Hyper-V: Microsoft's Hyper-V does offer GPU passthrough (Discrete Device Assignment), although no official support for either Windows 11 or consumer GPUs.
• ✅ Proxmox: Offers built-in PCI passthrough and works well for this task

Looks like Proxmox is an excellent candidate bare metal hypervisor that allows you to run Windows and Linux alongside each other and assign hardware to either of them

Caveat: To switch, Shut down VM #1 → detach GPU → attach GPU to VM #2 → start VM #2.

Dual Boot​

• ✅ Native performance: Files live natively where they're accessed most.
• ⚠️ Context switching: Rebooting between OSes disrupts flow.
• ⚠️ Shared state issues: Managing shared files and configurations between OSes is messy.

A dual boot setup is probably a good option if you intend to do all development work on Linux and other tasks on Windows that are not needed at the same time.

Personally I like to alternate between playing games and developing stuff on the regular.

WSL2 + Sync (This approach)​

• ✅ Native performance: Files live natively where they're accessed
• ✅ Unified development environment: No context switching, instant tool access
• ⚠️ GPU Virtualization: WSL2 provides GPU acceleration using a virtual GPU driver. It runs CUDA and DirectX workloads (AI/ML workloads, graphics rendering, etc.) efficiently.

For sake of moving forward I made the assumption that GPU virtualisation will be sufficient for my development needs.

What remains then is to solve the cross-filesystem performance issue with real-time synchronisation.

Enter Mutagen: real-time bidirectional sync​

Mutagen provides real-time bidirectional file synchronisation designed specifically for development workflows:

• Real-time synchronization with cross-platform filesystem watchers
• Conflict resolution for simultaneous edits, creation, deletes
• Extensive ignore patterns for node_modules, build artifacts, etc.

Each environment accesses files on their own filesystem. Mutagen synchronises files between them in the background.

Alternative solutions I've looked at lack important features:

• rsync: Not made for bidirectional sync; no conflict resolution
• Unison: Requires multiple endpoints and complex configuration
• rclone bisync: Cloud-optimised, complicated ignore patterns
• Syncthing: Looked promising, but no same-host folder support
• Native Windows tools: Not designed for development workflows

Mutagen setup guide​

Let's walk through setting up a robust, production-ready sync between Windows and WSL2.

Prerequisites​

• Windows 10/11 with WSL2 enabled
• Ubuntu 22.04 (or your preferred WSL distro from wsl --list --online)
• Username in WSL your Windows username in lowercase (e.g., webber for Webber)
• Administrative access to Windows

Step 1: install the Mutagen binary​

Download the latest version of Mutagen and install it on Windows.

Manual installation​

For example,

• download mutagen_windows_amd64_v0.18.1.tar.gz from that page,
• use 7-Zip to extract it, and
• place the mutagen.exe in a directory like C:\Users\YourName\Bin.
• Then add that directory to your PATH environment variable.

Automated installation​

# Create directory and download (adjust version as needed)
mkdir C:\Users\$env:USERNAME\Bin
cd C:\Users\$env:USERNAME\Bin

# Download latest release
Invoke-WebRequest -Uri "https://github.com/mutagen-io/mutagen/releases/download/v0.18.1/mutagen_windows_amd64_v0.18.1.zip" -OutFile "mutagen.zip"

# Extract
Expand-Archive -Path mutagen.zip -DestinationPath . -Force
Remove-Item mutagen.zip

# Add to PATH
[Environment]::SetEnvironmentVariable("Path", $env:Path + ";C:\Users\$env:USERNAME\Bin", [EnvironmentVariableTarget]::User)

# Verify installation
mutagen version

You can now run mutagen from any location.

Step 2: global configuration​

Before setting up sync sessions, be sure to configure Mutagen globally. This ensures that all sync sessions use consistent settings and ignore patterns.

Create a .mutagen.yml file in your Windows home directory.

# Example `~/.mutagen.yml` with most important settings
sync:
  defaults:
    mode: 'two-way-resolved' # Bidirectional sync with auto-resolution
    scanMode: 'accelerated' # Filesystem watching for better performance
    watch:
      mode: 'portable' # Use watchers for Windows and Linux filesystems
    ignore:
      # Ignore unnecessary and platform specific files
      - 'node_modules/'
      - '__pycache__/'
      - 'vendor/'

You can configure ignore patterns in two ways: Ignores that should always apply can be configured globally in .mutagen.yml, while session-specific ignores can be defined when creating sync sessions.

# ~/.mutagen.yml (in Windows homedir)
sync:
  defaults:
    mode: 'two-way-resolved'
    scanMode: 'accelerated'
    watch:
      mode: 'portable'
      pollingInterval: 2
    permissions:
      defaultFileMode: 0644
      defaultDirectoryMode: 0755
    ignore:
      vcs: false
      # Add any ignore patterns you want to apply for every sync session
      paths:
        # Node.js / JavaScript
        - 'node_modules/'
        - '.next/'
        - '.nuxt/'
        - '.output/'
        - 'dist/'
        - 'build/'
        - 'out/'
        - '.turbo/'
        - '.parcel-cache/'
        - '.cache/'
        - '.cache-loader/'
        - 'coverage/'
        - '.nyc_output/'
        - '.grunt/'
        - 'bower_components/'
        - '.sass-cache/'
        - '.fusebox/'
        - '.dynamodb/'
        - '.serverless/'
        - '.webpack/'
        - '.vuepress/dist/'
        - '.docusaurus/'
        - '.umi/'
        - '.umi-production/'
        - '.tern-port'
        - '.lock-wscript'
        - '.node_repl_history'
        - '*.pid'
        - '*.seed'
        - '*.pid.lock'
        - '.npm/'
        - '.config/configstore/'
        - '.pnp.cjs'
        - '.pnp.loader.mjs'
        - '.yarn/'
        - '.pnp/'
        - '.pnp.js'
        - '.pnp.*'
        - '.yarn-integrity'
        - '*.tsbuildinfo'
        - '.eslintcache'
        - '.stylelintcache'
        - '.terser-cache'
        - '.rpt2_cache/'
        - '.rts2_cache_cjs/'
        - '.rts2_cache_es/'
        - '.rts2_cache_umd/'
        - 'playwright-report/'
        - 'test-results/'
        - 'cypress/videos/'
        - 'cypress/screenshots/'

        # Python
        - '__pycache__/'
        - '*.py[cod]'
        - '*$py.class'
        - 'venv/'
        - 'env/'
        - 'ENV/'
        - '.Python'
        - '.pytest_cache/'
        - '.tox/'
        - '.coverage'
        - '.coverage.*'
        - 'htmlcov/'
        - '.hypothesis/'
        - '.pytype/'
        - '.mypy_cache/'
        - '.dmypy.json'
        - 'dmypy.json'
        - '.pyre/'
        - '.ruff_cache/'

        # Rust
        - 'target/'
        - 'Cargo.lock'
        - '**/*.rs.bk'
        - 'src-tauri/'

        # Java/Gradle
        - '.gradle/'
        - 'gradle-app.setting'
        - '.gradletasknamecache'

        # C#
        - 'bin/'
        - 'obj/'
        - 'artifacts/'

        # Unity
        - 'Library/'
        - 'Temp/'
        - 'obj/'
        - 'Build/'
        - 'Builds/'
        - 'Logs/'
        - 'UserSettings/'
        - 'UnityConnectSettings.asset'

        # PHP
        - '.phpunit.result.cache'
        - 'vendor/'

        # Go
        - 'vendor/'
        - 'go.sum'

        # IDEs and editors
        - '*.swp'
        - '*.swo'
        - '*~'
        - '.project'
        - '.classpath'
        - '.vscode-test/'

        # OS files
        - '.DS_Store'
        - '.DS_Store?'
        - '._*'
        - '.Spotlight-V100'
        - '.Trashes'
        - 'ehthumbs.db'
        - 'Thumbs.db'
        - 'desktop.ini'

        # Temporary files
        - 'tmp/'
        - 'temp/'
        - '.tmp/'
        - '.temp/'
        - '*.tmp'
        - '*.temp'
        - '*.bak'
        - '*.backup'
        - '*.old'

        # Logs
        - '*.log'
        - '*.log*'
        - 'logs/'

        # Documentation builds
        - '_site/'
        - 'site/'

Step 3: Automate startup​

To ensure Mutagen starts automatically when Windows boots, create a startup script that's executed when your system starts.

I've created a PowerShell script that checks all prerequisites and sets up the necessary environment. It also creates a startup script that starts the Mutagen daemon and resumes all sync sessions on startup.

# install-mutagen.ps1

# Mutagen Installation and Setup
# This script handles Mutagen installation checks and general setup
# Running this script multiple times will have no negative effects

Write-Host "=== Mutagen Installation and Setup ===" -ForegroundColor Cyan

# Check if Mutagen is installed
Write-Host "Checking Mutagen installation..." -NoNewline
try {
  $mutagenVersion = mutagen version 2>$null
  if ($LASTEXITCODE -ne 0) {
    throw "Mutagen command failed"
  }
  Write-Host " OK" -ForegroundColor Green
  Write-Host "  Version: $mutagenVersion" -ForegroundColor DarkGray
} catch {
  Write-Host " FAILED" -ForegroundColor Red
  Write-Host "Error: Mutagen is not installed or not in PATH" -ForegroundColor Red
  Write-Host "Please install Mutagen from: https://github.com/mutagen-io/mutagen/releases" -ForegroundColor Yellow
  exit 1
}

# Check if WSL is available
Write-Host "Checking WSL availability..." -NoNewline
try {
  $wslStatus = wsl --status 2>$null
  if ($LASTEXITCODE -ne 0) {
    throw "WSL command failed"
  }
  Write-Host " OK" -ForegroundColor Green
} catch {
  Write-Host " FAILED" -ForegroundColor Red
  Write-Host "Error: WSL is not installed or not running" -ForegroundColor Red
  Write-Host "Please install WSL: wsl --install" -ForegroundColor Yellow
  exit 1
}

# Check if Ubuntu-22.04 distro exists
Write-Host "Checking Ubuntu-22.04 distro..." -NoNewline
$distros = wsl --list --quiet
if ($distros -notcontains "Ubuntu-22.04") {
  Write-Host " FAILED" -ForegroundColor Red
  Write-Host "Error: Ubuntu-22.04 distro not found" -ForegroundColor Red
  Write-Host "Available distros:" -ForegroundColor Yellow
  $distros | ForEach-Object { Write-Host "  - $_" -ForegroundColor DarkGray }
  exit 1
}
Write-Host " OK" -ForegroundColor Green

# Check if .mutagen.yml exists in home directory
$mutagenConfig = "$env:USERPROFILE\.mutagen.yml"
Write-Host "Checking .mutagen.yml configuration..." -NoNewline
if (!(Test-Path $mutagenConfig)) {
  Write-Host " MISSING" -ForegroundColor Yellow
  Write-Host "Warning: No .mutagen.yml found in $env:USERPROFILE" -ForegroundColor Yellow
  Write-Host "Sync will use command-line ignore patterns only" -ForegroundColor Yellow
} else {
  Write-Host " OK" -ForegroundColor Green
}

# Start Mutagen daemon if not running
Write-Host "Starting Mutagen daemon..." -NoNewline
try {
  mutagen daemon start 2>$null
  Write-Host " OK" -ForegroundColor Green
} catch {
  Write-Host " FAILED" -ForegroundColor Red
  Write-Host "Error: Could not start Mutagen daemon" -ForegroundColor Red
  exit 1
}

# Create startup bat file
$binDir = "C:\Users\$env:USERNAME\Bin"
$startupScript = "$binDir\mutagen-startup.bat"

Write-Host "Creating startup script..." -NoNewline
if (Test-Path $startupScript) {
  Write-Host " EXISTS" -ForegroundColor Yellow
  Write-Host "  Found: $startupScript" -ForegroundColor DarkGray
} else {
  try {
    # Create Bin directory if it doesn't exist
    if (!(Test-Path $binDir)) {
      New-Item -ItemType Directory -Path $binDir -Force | Out-Null
    }

    # Create the bat file content
    $batContent = @"
@echo off
mutagen daemon start
mutagen sync resume --all
"@

    Set-Content -Path $startupScript -Value $batContent -Encoding ASCII
    Write-Host " OK" -ForegroundColor Green
    Write-Host "  Created: $startupScript" -ForegroundColor DarkGray
  } catch {
    Write-Host " FAILED" -ForegroundColor Red
    Write-Host "Error: Could not create startup script" -ForegroundColor Red
    Write-Host $_.Exception.Message -ForegroundColor Red
    exit 1
  }
}

# Register startup shortcut
$startupShortcut = "$env:APPDATA\Microsoft\Windows\Start Menu\Programs\Startup\Mutagen.lnk"

Write-Host "Registering startup shortcut..." -NoNewline
if (Test-Path $startupShortcut) {
  Write-Host " EXISTS" -ForegroundColor Yellow
  Write-Host "  Found: $startupShortcut" -ForegroundColor DarkGray
} else {
  try {
    if (Test-Path $startupScript) {
      $WshShell = New-Object -comObject WScript.Shell
      $Shortcut = $WshShell.CreateShortcut($startupShortcut)
      $Shortcut.TargetPath = $startupScript
      $Shortcut.WorkingDirectory = $binDir
      $Shortcut.WindowStyle = 7  # Minimized
      $Shortcut.Description = "Start Mutagen sync daemon and resume all sessions"
      $Shortcut.Save()
      Write-Host " OK" -ForegroundColor Green
      Write-Host "  Created: $startupShortcut" -ForegroundColor DarkGray
    } else {
      throw "Startup script not found"
    }
  } catch {
    Write-Host " FAILED" -ForegroundColor Red
    Write-Host "Error: Could not create startup shortcut" -ForegroundColor Red
    Write-Host $_.Exception.Message -ForegroundColor Red
    exit 1
  }
}

Write-Host "`n=== Installation Complete ===" -ForegroundColor Green
Write-Host "Mutagen is installed and configured for auto-startup." -ForegroundColor Green
Write-Host "`nNext steps:" -ForegroundColor Cyan
Write-Host "  .\install-mutagen-syncs.ps1          # Create sync sessions" -ForegroundColor DarkGray
Write-Host "  .\install-mutagen-syncs.ps1 -Force   # Recreate sync sessions" -ForegroundColor DarkGray

Example output

Mutagen will now start automatically when you log in to Windows.

Managing sync sessions​

We can now create sync sessions.

Example usage​

# Create a sync session
mutagen sync create `
  "C:\Users\$env:USERNAME\Repositories" `
  "\\wsl.localhost\Ubuntu-22.04\home\$($env:USERNAME.ToLower())\Repositories\" `
  --name="repositories"

# Watch sync progress in real-time
mutagen sync monitor repositories

# Skip file discovery and force a sync
mutagen sync flush repositories

# Remove a sync session
mutagen sync terminate repositories

Creating sync sessions with a script​

Here's my setup script that creates the sync session for my repositories and home directory.

# Mutagen Sync Session Management
# This script manages Mutagen sync sessions between Windows and WSL

param(
    [switch]$Force  # Force recreation of syncs even if they exist
)

Write-Host "Mutagen Sync Session Management" -ForegroundColor Cyan

# Track if any syncs already exist (for showing tip at end)
$script:HasExistingSyncs = $false

# Function to create or recreate a sync with simpler positional parameters
function Create-Sync {
    param(
        [Parameter(Position=0, Mandatory=$true)]
        [string]$Name,

        [Parameter(Position=1, Mandatory=$true)]
        [string]$SourcePath,

        [Parameter(Position=2, Mandatory=$true)]
        [string]$DestPath,

        [Parameter(Position=3, Mandatory=$false)]
        [string[]]$IgnorePatterns = @()
    )

    Write-Host "Managing '$Name' sync..." -ForegroundColor DarkGray -NoNewline

    # Sanitize name for mutagen:
    # - Replace invalid characters with hyphens
    # - Only allow alphanumeric, hyphens, and underscores
    # - Truncate to 63 characters max
    $SafeName = $Name -replace '[^a-zA-Z0-9_-]', '-'
    if ($SafeName.Length -gt 63) {
        $SafeName = $SafeName.Substring(0, 63)
    }

    # Check if sync exists
    $syncList = mutagen sync list 2>$null
    $existingSync = $syncList | Where-Object { $_ -match "^Name:\s+$SafeName\s*$" }

    if ($existingSync -and !$Force) {
        Write-Host " Exists" -ForegroundColor DarkGray
        $script:HasExistingSyncs = $true
        return
    }

    if ($existingSync -and $Force) {
        Write-Host " Terminating" -ForegroundColor Yellow
        mutagen sync terminate $SafeName 2>$null
        Start-Sleep -Seconds 1
    }

    if (!$existingSync) {
        Write-Host " Creating" -ForegroundColor Yellow
    }

    # Check if source and destination exist
    if (!(Test-Path $SourcePath)) {
        Write-Host " Failed" -ForegroundColor Red
        Write-Host "  Source path not found: $SourcePath" -ForegroundColor Red
        return
    }

    # Create destination directory if it doesn't exist
    if (!(Test-Path $DestPath)) {
        try {
            New-Item -ItemType Directory -Path $DestPath -Force | Out-Null
        } catch {
            Write-Host " Failed" -ForegroundColor Red
            Write-Host "  Cannot create destination: $DestPath" -ForegroundColor Red
            return
        }
    }

    # Build create command
    $createArgs = @(
        "sync", "create",
        $SourcePath,
        $DestPath,
        "--name=$SafeName"
    )

    # Add ignore patterns if provided
    foreach ($pattern in $IgnorePatterns) {
        $createArgs += "--ignore=$pattern"
    }

    try {
        $output = & mutagen @createArgs 2>&1
        if ($LASTEXITCODE -ne 0) {
            throw "Sync creation failed"
        }
        # Show mutagen output indented and in dark gray (filter out empty lines)
        if ($output) {
            $output | Where-Object { $_.Trim() -ne "" } | ForEach-Object { Write-Host "    $_" -ForegroundColor DarkGray }
        }
    } catch {
        Write-Host " Failed" -ForegroundColor Red
        Write-Host "  Error creating sync: $($_.Exception.Message)" -ForegroundColor Red
        exit 1
    }
}

# Create syncs using simplified positional parameters

# Home sync with specific ignore patterns
Create-Sync `
    "home" `
    "C:\Users\$env:USERNAME\" `
    "\\wsl.localhost\Ubuntu-22.04\home\$($env:USERNAME.ToLower())\" `
    @(
        '**',
        '!.mutagen.yml',
        '!.gitconfig*',
        '!.claude/',
        '!.claude/test.md',
        '!.claude/CLAUDE.md',
        '!.claude/mcp.json',
        '!.claude/settings.json',
        '!.claude/settings.local.json',
        '!.aws/',
        '!.aws/**',
        '!.config/',
        '!.config/**',
        '!.ssh/',
        '!.ssh/**',
        '!.editorconfig',
        '!.wslconfig'
    )

# Repository syncs - explicit paths for clarity
Create-Sync `
    "takken.io" `
    "C:\Users\$env:USERNAME\Repositories\takken.io\" `
    "\\wsl.localhost\Ubuntu-22.04\home\$($env:USERNAME.ToLower())\Repositories\takken.io\"

Create-Sync `
    "docusaurus-plugin-content-gists" `
    "C:\Users\$env:USERNAME\Repositories\docusaurus-plugin-content-gists\" `
    "\\wsl.localhost\Ubuntu-22.04\home\$($env:USERNAME.ToLower())\Repositories\docusaurus-plugin-content-gists\"

# Show tip if any syncs already existed
if ($script:HasExistingSyncs) {
    Write-Host "`nTip: Use " -ForegroundColor DarkGray -NoNewline
    Write-Host "-Force" -ForegroundColor White -NoNewline
    Write-Host " to recreate existing syncs" -ForegroundColor DarkGray
}

Write-Host "`nSync Status" -ForegroundColor Cyan

# Parse mutagen sync list output manually
$syncListOutput = mutagen sync list 2>$null
if ($syncListOutput) {
    $lines = $syncListOutput -split "`n"
    $currentSync = @{}

    foreach ($line in $lines) {
        $line = $line.Trim()

        if ($line -match "^Name:\s*(.+)$") {
            $currentSync.Name = $matches[1]
        }
        elseif ($line -match "^URL:\s*(.+)$" -and !$currentSync.Alpha) {
            $currentSync.Alpha = $matches[1]
        }
        elseif ($line -match "^URL:\s*(.+)$" -and $currentSync.Alpha) {
            $currentSync.Beta = $matches[1]
        }
        elseif ($line -match "^Status:\s*(.+)$") {
            $currentSync.Status = $matches[1]

            # Output the sync info when we have all parts
            if ($currentSync.Name -and $currentSync.Alpha -and $currentSync.Beta -and $currentSync.Status) {
                if ($currentSync.Status -match "(Watching for changes|Scanning files)") {
                    $statusDisplay = "✓"
                    $statusColor = "Green"
                } elseif ($currentSync.Status -match "(conflict|error|failed|problem)") {
                    $statusDisplay = "✗ $($currentSync.Status)"
                    $statusColor = "Red"
                } else {
                    $statusDisplay = "⚠ $($currentSync.Status)"
                    $statusColor = "Yellow"
                }
                Write-Host "  $($currentSync.Name): " -ForegroundColor White -NoNewline
                Write-Host "$statusDisplay" -ForegroundColor $statusColor
                Write-Host "    " -NoNewline
                Write-Host "$($currentSync.Alpha) " -ForegroundColor DarkGray -NoNewline
                Write-Host "↔ " -ForegroundColor Yellow -NoNewline
                Write-Host "$($currentSync.Beta)" -ForegroundColor DarkGray
                $currentSync = @{}
            }
        }
    }
} else {
    Write-Host "  No syncs found" -ForegroundColor DarkGray
}

Write-Host "`nUseful Commands" -ForegroundColor Cyan
Write-Host "  mutagen sync create " -ForegroundColor DarkGray -NoNewline; Write-Host "[name]" -ForegroundColor Magenta -NoNewline; Write-Host " " -ForegroundColor DarkGray -NoNewline; Write-Host "[source]" -ForegroundColor Magenta -NoNewline; Write-Host " " -ForegroundColor DarkGray -NoNewline; Write-Host "[dest]" -ForegroundColor Magenta -NoNewline; Write-Host "   # Create a new sync" -ForegroundColor DarkGray
Write-Host "  mutagen sync terminate " -ForegroundColor DarkGray -NoNewline; Write-Host "[name]" -ForegroundColor Magenta -NoNewline; Write-Host "                # Remove specific sync" -ForegroundColor DarkGray
Write-Host "  mutagen sync list                            # List all syncs" -ForegroundColor DarkGray
Write-Host "  mutagen sync list -l                         # List all syncs with detailed info" -ForegroundColor DarkGray
Write-Host "  mutagen sync monitor " -ForegroundColor DarkGray -NoNewline; Write-Host "[name]" -ForegroundColor Magenta -NoNewline; Write-Host "                  # Watch sync activity for a specific sync" -ForegroundColor DarkGray

Example output:

And that's it! Mutagen will keep the desired folders in sync!

WSL configuration​

Config file​

Create a .wslconfig file in your Windows home directory.

[wsl2]
# Machine configuration for WSL2 on Windows 11
memory=16GB
processors=8
swap=0                      # Disable swap if you have enough RAM
nestedVirtualization=false  # Disable if not needed

# Networking settings
localhostForwarding=true    # Allows you to run dev server on WSL and access it via localhost
dhcp=true                   # WSL obtains IP via DHCP
ipv6=true                   # Enable IPv6 support

Change it to suit your hardware. This example allocates 16GB of RAM and 8 CPU cores to WSL2.

GPU access​

To run GPU workloads in WSL2, you need to install CUDA toolkit.

sudo apt install -y nvidia-cuda-toolkit

Verify that passthrough works:

nvidia-smi

It works if you see the driver version and CUDA version.

Docker CLI access​

To use Docker CLI in WSL2, enable Docker integration in Docker Desktop settings on Windows.

At that point you should be able to run Docker commands in WSL2.

docker --help

Troubleshooting​

In my case, I wasn't able to connect to the Docker daemon in WSL2, even though Docker Desktop was running.

which docker # /mnt/c/Program Files/Docker/Docker/resources/bin/docker

sudo tee /etc/wsl.conf <<EOF
[interop]
appendWindowsPath = false
EOF

wsl --shutdown

# Restart WSL
wsl

which docker # /usr/bin/docker

Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?

ls -alh /var/run/docker.sock

# List in the general location
ls /mnt/wsl/docker-desktop

# drill down to find the socket file, in my case it was here:
ls /mnt/wsl/docker-desktop/shared-sockets/host-services/

  # Create the directory if it doesn't exist
  sudo mkdir -p /var/run

  # Link the socket file
  sudo ln -sf /mnt/wsl/docker-desktop/shared-sockets/host-services/docker.proxy.sock /var/run/docker.sock

  # Set the correct permissions
  sudo chmod 666 /var/run/docker.sock

  # Make sure your user is part of the group that owns the link
  GROUP=$(stat -c '%G' /var/run/docker.sock)
  sudo usermod -aG "$GROUP" "$(whoami)"

  # Verify the link
  ls -alh /var/run/docker.sock

  # Verify that the sock works
  docker ps

Conclusion​

This solution, using Mutagen offers an elegant workaround that delivers the best of both worlds: Windows productivity tools along with Linux capabilities.

• Preserved workflows: Use Windows tools on Windows paths, Linux tools on Linux paths
• Native performance: Each environment accesses files at full native speed
• Transparent synchronisation: Changes appear on both sides almost instantly
• No manual intervention: Once configured, synchronisation happens automatically

No more 10-20x slowdowns. No more choosing between ecosystems. Whether you're building web apps, training ML models, or juggling mixed technology stacks, this approach will help make WSL2 viable for serious development work.

Have you tried this setup? Share your experience in the comments!

To make for a truly slick experience, I have considered different terminals, shells, prompts and hotkeys, as well as command-line tools and plugins, including typeahead and fuzzy search.

A quick tip 💡​

Customizing your terminal can be time-consuming, so I use a simple trick to avoid repeating the process.

My home directory is a git repository. I track only specific config and settings files while ignoring everything else.

This keeps my setup consistent and makes syncing configurations across machines effortless.

TL;DR​

The Terminal​

For the purpose of this post, I'll differentiate between terminal, shell and prompt. Let's start with the terminal.

Definition​

Historically, a terminal was a physical device consisting of a keyboard and a display (first image), used for interacting with a computer. Nowadays, we basically wrap a virtual version of such a terminal in our operating system using a window (second image). Technically, it would be called a terminal emulator but it's usually called terminal for simplicity.

Choice​

There are different terminals out there, each with their pros and cons and different way of configuration. Personally, I've used ConEmu, Cmder, windows-terminal-quake and Windows Terminal.

Out of those, I've found Windows Terminal to be the most modern and easy to use. It's also actively developed by Microsoft. It supports tabs, panes, key bindings, different fonts and character sets, custom themes, quake-style console and much more.

Installation​

choco install microsoft-windows-terminal

winget install -e --id Microsoft.WindowsTerminal

scoop bucket add extras
scoop install -g windows-terminal

Once you've installed Windows Terminal, run it. It should look similar to the image below.

By default, it opens an outdated version of PowerShell, that can be recognised by its blue icon.

The first message printed on the terminal is a suggestion of replacing that with something more modern. Let's do that next.

The Shell​

Definition​

A shell is a digital interface that allows users to interact with the operating system. It can be graphical, like the Windows Explorer, or command-line based, like Command Prompt (aka cmd) and PowerShell. A shell lets you navigate the system, modify its files and launch scripts and applications.

Introduction​

If you're a Windows user, chances are you've used Command Prompt, Git Bash, WSL or PowerShell before. If yes, then you've most likely also found that not all commands work in your preferred shell.

Working out how to cater for most use cases in a single shell can also take much time. Especially if you like to integrate the various available productivity tools into it.

Rationale​

To me, switching between multiple shells comes with two major downsides. Firstly, you lose the context that you are working in, which means that you can not easily chain commands, reuse output or pass variables between the shells. Secondly, each shell has unique configurations and quirks, requiring setup and making for a learning curve. That means double the effort, the occasional confusion and a huge inhibitor for becoming a command line power user.

Therefore, I'd argue that it is valuable to choose a single shell environment and master it thoroughly. It is, then, also important to choose a shell that modern and powerful enough for most use cases.

Luckily, today there are excellent tools available that can make a Windows shell almost as powerful as their Linux counterparts.

Choice​

I've found PowerShell 7 to be the most modern and powerful command-line shell for Windows. It is open-source, works across Windows, Linux and MacOS and features a built-in scripting language. It also allows you to easily install plugins. PowerShell is well maintained and has a decent ecosystem.

Installation​

winget install -e --id Microsoft.PowerShell

Alternatives​

Below you will find the considered alternatives, each provided with a short rationale.

The Prompt​

This brings us to the third important part of the terminal setup: the prompt.

Definition​

The prompt is the text that indicates the shell is ready to accept commands. It can be customised to show specific information, like the current directory, the time and the exit code of the last executed command.

Modern prompts can also show context specific information. A couple of examples:

• display the git branch (or other VCS equivalent) of the folder that you're in.
• show the status of the repository, like untracked files, staged files, etc.
• show the currently active language runtime for a project, like go, node, python, etc.

Rationale​

A great prompt can be very helpful for productivity. Ideally you'd be able to see with the blink of an eye what project you're working on, what branch you're on and what version of bun, rust or other language runtime you're using in your project.

And instead of having to type echo $? or echo $LastExitCode to find out whether the last command ran successfully or not, wouldn't it be useful it would just show you red or green in your next prompt?

I believe the best prompt possible would have the following characteristics:

• Run extremely fast, so that the terminal doesn't feel laggy.
• Be portable across different shells.
• No over information; show just practical information.
• Show that needed information in a concise way, using symbols and colours where possible.

Choice​

For years, I've used Oh-My-Posh, combined with PoshGit. But more recently I've started using Starship. And while both are great options, The latter is definitely the much more modern option here.

Starship​

Starship is written from the ground up in Rust, with high performance in mind. It has made prompt configuration so simple that creating your own config has become very accessible. It is also cross-platform and works on any shell.

On their discussions page, the community shares their setups and custom commands and modules. These can be very useful for inspiration purposes.

Nerd fonts​

Nerd fonts is an amazing open source initiative that takes existing fonts, and adds glyphs and icons to it. These fonts are specialised for use by developers, in IDEs and Terminals.

Installation​

These are the steps to installing Starship.

1. Install a Nerd font
2. Install Starship
3. Tell your shell to use Starship for it's prompt

choco install starship

winget winget install --id Starship.Starship

scoop install -g starship

Once you've configured your shell to use Starship, restart your terminal. If you did everything correctly, your terminal should look similar to the image below.

From here you can go in many directions in terms of configuration and adding plugins. I'll dedicate a few short chapters on what I've set up below.

Theme config​

Choice​

Ever heard of Dracula theme?

As a developer it's important to reduce your cognitive load where possible. And once you get used to a theme, you'll learn to recognise the meaning of each colour in different contexts, which will reduce that load. For this reason I use the same developer-oriented colour scheme, called Dracula, across many applications, including my terminal.

Test method​

In Starship's discussion called "share your setup", people have resorted to using neofetch or fastfetch as a quick way to show structured information and the colour palette. Let's do the same!

We'll install the better maintained and cross-platform fastfetch.

winget install -e --id=Fastfetch-cli.Fastfetch

Then run it.

fastfetch

Expected result​

Here's a before and after picture, when applying Dracula theme.

As you can see, the changes are subtle. The slightly softer colours will however make it much easier to look at an information overload, as they won't 'scream' so much. And the slightly darker whites works better on light backgrounds, and it's fine-tuned for use with autocompletion.

Installation​

Start by following the official instructions to install Dracula in Windows Terminal.

Optionally, use my fine-tuned optimisations

{
  "profiles": {
    "defaults": {
      "background": "#0C0C0C",
      "colorScheme": "Dracula Webber",
      "font": {
        "face": "FiraCode Nerd Font Mono",
        "size": 14
      },
      "opacity": 70,
      "useAcrylic": true
    }
  }
}

{
  "schemes": [
    {
      "name": "Dracula Webber",
      "background": "#22212C",
      "black": "#22212C",
      "blue": "#5D4FA1",
      "brightBlack": "#7E7A94",
      "brightBlue": "#907AFF",
      "brightCyan": "#84FFEA",
      "brightGreen": "#7FFF73",
      "brightPurple": "#FF99CC",
      "brightRed": "#FFAA99",
      "brightWhite": "#FFFFFF",
      "brightYellow": "#FFFF99",
      "cursorColor": "#FFFFFF",
      "cyan": "#5ADBC6",
      "foreground": "#A2AECA",
      "green": "#51D378",
      "purple": "#FF80BF",
      "red": "#E74A2A",
      "selectionBackground": "#8B89FF",
      "white": "#F8F8F2",
      "yellow": "#FFFF80"
    }
    // ... other schemes here.
  ]
}

Prompt config​

Choice​

Starship allows you to create and share prompt configurations. They also have a couple of presets to choose from.

Since I was quite interested to have my own personalised prompt configuration that I can iterate on over time, I've chosen to learn from the presets and build my own.

Installation​

Installing my config is simple.

• Open the Starship config.

code ~/.config/starship.toml

• Copy the contents of my config and paste it in there.
• Save the file.

That's it!

When you now press 'enter' in your terminal, the change should be reflected as shown in the image below.

Terminal Icons​

There's a nifty plugin called Terminal Icons. It uses icons and colours that help you recognise common files in the blink of an eye.

Installation​

code $PROFILE

Import-Module -Name Terminal-Icons # Icons when listing directories

Autocompletion​

Now that things are starting to look good, let's add some functionality.

There are a few types of autocompletion that I find very useful.

Types​

Basic autocomplete​

You type a few characters. A suggestion appears. You use ctrl+f to accept one word, or ctrl+space to accept the complete suggestion.

Tab autocomplete​

You type a few characters. You press tab to cycle though the different options.

Using history​

You can use the up and down arrow keys to cycle through previously used commands.

Fuzzy search​

Fuzzy search allows you to query the history, autocomplete suggestions, files and folders, by typing a partial match.

Example​

If you are looking for a folder called ~/Repositories/takken.io, you can type things like repotak to find it. See highlights for query matches.

Hotkeys​

• Alt + C to quickly change directory
• Ctrl + T to autocomplete files
• Ctrl + R to search and autocomplete from history

This is where a few keystrokes can start to become very powerful.

Installation​

To achieve autocompletion for above examples we'll need two plugins. PSReadLine and PSFzf.

code $PROFILE

Import-Module -Name PSReadLine # typeahead predictions and whatnot
Import-Module -Name PSFzf # activate using `Ctrl T`, `Ctrl R` and `Alt C`

# Advanced completion features (arrow up and down after having started typing)
Set-PSReadLineOption -HistorySearchCursorMovesToEnd
Set-PSReadLineKeyHandler -Key UpArrow -Function HistorySearchBackward
Set-PSReadLineKeyHandler -Key DownArrow -Function HistorySearchForward

# Autocomplete suggestions
Set-PSReadLineKeyHandler -Key Tab -Function MenuComplete # options: [Complete|MenuComplete]

# Autocomplete predictions [HistoryAndPlugin, History, Plugin] requires PS 7.1+
Set-PSReadLineOption -PredictionSource HistoryAndPlugin # accept prediction using right arrow
Set-PSReadLineOption -Colors @{ InlinePrediction = '#888888' }

# accepting suggestions
Set-PSReadLineKeyHandler -Chord "Ctrl+f" -Function ForwardWord # Accept one word
Set-PSReadLineKeyHandler -Chord "Ctrl+Spacebar" -Function ForwardChar # Accept full suggestion

Unix tools​

Some of the most common Linux commands are available as part of Git's "Optional Unix tools" package.

Installation​

All you have to do is install Git for Windows with the "Optional Unix tools" option enabled.

choco install -y git --params "/GitAndUnixToolsOnPath /WindowsTerminal /NoAutoCrlf"

Quake-style console​

The Quake-style console is a terminal that slides down from the top of the screen when you press a hotkey. It's a great way to quickly access the terminal without having to switch windows.

Installation​

{
  "command": {
    "action": "quakeMode"
  },
  "id": "User.quakeMode.F1E129A4",
  "keys": "ctrl+`"
},

Split panes​

Split panes are a great way to multitask in the terminal. For example, run an application in one pane, and while that application runs, enter commands in a different pane.

See official docs about panes for more information.

Once you know the hotkeys it works super fast and smooth.

Installation​

These hotkeys should mostly work out of the box. If you want to change them, you can do so by modifying the settings.json file.

{
  "command": "closePane",
  "id": "Terminal.ClosePane",
  "keys": "ctrl+shift+w"
},
{
  "command":{
    "action": "splitPane",
    "split": "auto",
    "splitMode": "duplicate"
  },
  "id": "User.splitPane.A6751878",
  "keys": "alt+shift+d"
},
{
  "command": {
    "action": "splitPane",
    "split": "down",
    "splitMode": "duplicate"
  },
  "id": "User.splitPane.10B260D2",
  "keys": "alt+shift+minus"
},
{
  "command": {
    "action": "splitPane",
    "split": "right",
    "splitMode": "duplicate"
  },
  "id": "User.splitPane.FEF0D40B",
  "keys": "alt+shift+plus"
},
{
  "command": {
    "action": "splitPane",
    "split": "up",
    "splitMode": "duplicate"
  },
  "id": "User.splitPane.7A967A9",
  "keys": "ctrl+alt+shift+up"
},
{
  "command":  {
    "action": "splitPane",
    "split": "right",
    "splitMode": "duplicate"
  },
  "keys": "ctrl+alt+shift+right"
},
{
  "command":  {
    "action": "splitPane",
    "split": "down",
    "splitMode": "duplicate"
  },
  "keys": "ctrl+alt+shift+down"
},
{
  "command":  {
    "action": "splitPane",
    "split": "left",
    "splitMode": "duplicate"
  },
  "id": "User.splitPane.652D529A",
  "keys": "ctrl+alt+shift+left"
}

And there we have it. A modern terminal setup for Windows.

Limitations​

The terminal setup I've described is very powerful and modern. It's also very customisable. But it does take about half a second to load and does have some limitations when it comes to third party integrations.

Some modern tools and services export configuration for command completion. These are often written for Unix-like systems and might not always be compatible with PowerShell or Windows-based systems.

Some of the most used completion tools:

Conclusion​

For years, the terminal experience in Windows has left much to be desired. But with Microsoft's recent efforts, the terminal experience has improved significantly. Windows Terminal and PowerShell 7 are very modern, and no longer lag behind their Unix counterparts.

There are many components to a full terminal setup. At every step there are multiple options to consider. Having a combination that works for almost every use-case without too many edge cases can be a challenge.

By using Starship, Terminal Icons, and autocompletion features that can deliver an impressive terminal experience.

I hope this guide has been helpful to you. If you have any questions or suggestions, please leave a comment below.

Glossary​

In everyday use, you might find the terms 'terminal', 'console', and 'shell' used interchangeably, often referring to the interface you type your commands into on a Unix-like or Windows system.

In this chapter I've documented my reasoning around the build and each component. I also explain the tweaks I've done for my specific setup.

Hardware​

Let's start with the hardware. What did I get and why?

In order to tell you why, I need to tell you what requirements I had.

Requirements​

• Since it will be running Home Assistant, and basically be the brain of my home, it needs to be reliable.
• It also needs to run 24/7 without costing a fortune in electricity, so low power usage.
• I really wanted it to be able to run a few virtualised workloads for when I want to play around with stuff, so decent performance.
• My 19" rack is connected to the kitchen, so it needs to be quiet.

Research​

I did a lot of research on what hardware to get and looked at many different options.

Components​

These are the components I ended up with. I've tried to describe my reasoning for each component, but if you have any questions please don't hesitate to drop a comment.

Main components​

Accessories​

The build​

Here's what the build looks like.

Efficiency tweaks​

Measuring​

To measure the power usage I used a calibrated Nous A1T.

I calibrated the plug using a multi meter and a 40W light bulb (resistive load).

First boot​

First thing I did was boot it up with no additional settings. Not surprisingly, it crashed while booting into Unraid. Loading an OS is CPU heavy task and the energy usage spiked above the maximum the PSU could handle.

So the first tweak was to

• set the CPU TDP limit to 35W.

After this everything worked very smoothly. 🎉

Time for stats!

Stress testing​

I ran a stress test with mprime to see what the maximum power usage was.

Source: https://www.mersenne.org/download/

# Download
wget https://www.mersenne.org/download/software/v30/30.8/p95v308b17.linux64.tar.gz

# Extract
mkdir mprime && tar -xf ./p95v308b17.linux64.tar.gz -C mprime

# Manual
./mprime/mprime --help

# Run
./mprime/mprime -t

For the visual people among us, here's what that looks like:

Initial stats​

Now that we know both our idle and stress power usage, we can start tweaking.

But before that, time for the initial stats!

What's interesting is that even without any tweaks, the idle power usage of the server is already very low.

This has everything to do with the specific hardware that was chosen, especially the motherboard with its focus on energy efficiency and the power supply unit (PSU) not being so large that it becomes inefficient at low loads.

BIOS tweaks​

BIOS tweaks: Turn off unused devices​

Firstly, the most obvious tweaks: turning off all the things we don't need.

• Audio: Disabled
• PCI Express Slot 1: Disabled
• PCI Express Slot 2: Disabled
• PCI Express Slot 3: Disabled
• PCI Express Slot 4: Disabled
• Serial port: Disabled

Great results so far!

BIOS tweaks: Review all relevant settings​

CPU​

• Enhanced Intel SpeedStep Technology: Enabled (was Enabled)
• Turbo Boost: Disabled (was Enabled)
• C States: Enabled (was Enabled)
• Package C State Limit: Auto (was Auto)

And since there's some headroom left, I also increase the maximum power limit.

• CPU TDP Limit: 60W (was 35W)

USB​

• USB 3.1 Gen 2 speed: Disabled (was Enabled)
• USB Port Control: Enable rear and internal ports (was Enable all ports)

NIC​

• Wake on LAN: Disabled (was Enabled)

PCI​

• Above 4G Decoding: Disabled (was Enabled)

BIOS tweaks: Disable graphics​

The default settings for my motherboard are as follows:

• Primary display: Auto
• Internal graphics: Auto

This means that the next test is to pull out the monitor cable and see how it affects power usage. Unfortunately pulling out the cable didn't make any difference.

I then manually disabled the internal graphics controller, which did seem to make a small difference, but still too small to measure.

I wasn't able to detect a significant difference in power usage with this tweak.

Software tweaks​

Software tweaks can help out where hardware settings are not sufficient or not available. One of the main things to focus on is the CPU, or more specifically, the C-states.

C-states​

The different C-states (C0 through C10) represent varying levels of power-saving modes:

• C0 is the operating state.
• C10 is the deepest idle state.
• The higher the C-state, the more power is saved.

We'll use Powertop to try and improve the C-state usage.

Powertop​

Powertop comes as one of the recommended tools to tweak power usage on Linux. It's a tool that gives you quite a bit of insight into what's going on with your system. It also allows you to tweak some settings.

I've followed this guide to install it on Unraid. I'll describe some of the steps here.

Install​

Download the file in /boot/extra, then reboot to automatically install it.

mkdir /boot/extra
cd /boot/extra
wget https://github.com/mgutt/unraid-packages/raw/main/6.11.0/powertop-2.15-x86_64-1.txz

Analyse​

Run powertop without --auto-tune (for now) to get an overview of what's going on.

powertop

On the Idle stats tab it looks like much of the time is spent in the C2 state.

Looking at the Tunables tab: It seems like there are many things to tune still.

Tuning​

Now that we have an overview of what's going on, let's try to tune some of the settings.

powertop --auto-tune

# or alternatively
powertop --quiet --auto-tune

After running this command, the Tunables tab looks like this:

The Idle stats tab looks a lot better now too: Instead of the CPU spending most of the time in the C2 state it's now spending most of the time in the C8 state.

Keep tuning after reboot​

First of, let's test that the array still comes up after tuning.

In Unraid stop the array, then run the tuning command again.

powertop --quiet --auto-tune

Now start the array again. If the array comes up, you should be good to go.

To keep the tuning after reboot, add the tuning command to the go file like so:

echo "powertop --quiet --auto-tune" >> /boot/config/go

Finally, reboot and check if everything still works as expected.

reboot

Results​

Et voilà! After applying tuning, the power usage is down to 7W on average. Awesome! 🎉

Conclusion​

And there we have it!

A powerful server that uses only 7W on average when idle. I'm really happy with the results.

Credits​

I could not have done it without the awesome contributions people made to the Big Efficient Server Topic (Dutch).

Special thanks to mrmrmr in particular. 🙏🏻

When the piece had arrived, I was surprised to see a chunk of dirt that was burnt in, seemingly connecting some contact points together. I was worried that this would cause a short circuit and damage the CPU.

Analysis​

I found that the shape of the dirt was different from what it seems on the first picture.

Upon closer inspection, using a digital microscope, the dirt seemed to be a bit more loose and some discolouration became visible.

On this second picture you see more discolouration and one contact that's almost completely covered in dirt.

Cleaning​

What not to use?​

After some research, I found out the following:

• Don't use any liquid that corrodes the metal
• Don't use any liquid that leaves a residue
• Don't use any liquid that evaporates too slowly
• Don't use a material that can leave behind residue

So what can you use?​

• I found that isopropyl alcohol is a good choice. It's a solvent that evaporates quickly and doesn't leave any residue. It's also used to clean electronics. I use Isopropanol 99.9% Isopropyl Alcohol 2-Propanol 250ml in Glass Bottle.
• Cotton swabs are a good choice. They are small and don't leave behind any residue.
• Toothpicks are a good choice. They are small and can be used to scrape off dirt.
• A plastic scraper can also be helpful to scrape off dirt. Be sure to remove any particles that might break off.
  • I happened to have this glue remover lying around. While it's not ideal, it's better than using a metal scraper.

The process​

There is always a risk that your hardware stops working. I would recommend to only clean your hardware if there is a good reason to do so.

Rubbing​

Cleaning with isopropyl alcohol and a cotton swab

1. Dip the cotton swab in the isopropyl alcohol
2. Gently rub the dirt with the cotton swab
3. Repeat until the dirt is gone

In my case, the dirt was pretty persistent. I had to use something with an edge to scrape it off.

Scraping​

4. Use a toothpick or plastic scraper in a gentle motion to scrape off the dirt.
5. Use the cotton swab to remove any material that might have broken off.

Rubbing again​

After scraping off the dirt, I used the cotton swab again to remove any residue.

6. Dip the cotton swab in the isopropyl alcohol
7. Gently rub the dirt with the cotton swab.

This is a video of what it looked like for me:

As you can see in the video, the dirt isn't completely gone. However, this should be clean enough to get it working without short-circuiting.

Drying​

Some alcohol may have seeped into the CPU. It's important to let it dry before installing it.

8. Wait 15 minutes to make sure the CPU is completely.

Testing​

9. Install the CPU, apply thermal paste and install the cooler.
10. Boot the system and check if it works.

In my case, I installed the CPU, and it worked without any issues.

The game is all about building your own logistic network using train railway tracks combined with different signals. A game that requires a lot of structure and/or creativity of you in order to succeed.

After receiving a first direct message from Raiane, we soon found out that we had both made the same observation: that surprisingly many conservative people with very clear structures in their mind, using circular conversational approaches (not unlike OCD) seem to be drawn to this game's Discord server.

Raiane stated that the critics in the feedback channel were being pricks. While admittedly that sentiment resonated well with me as they weren't being particularly polite, I also argued that they probably weren't being pricks on purpose. And that intention counts.

For the next two hours or so we continued our conversation. We asked ourselves “How and when should we be more inclusive of others?”. It brought forth the importance of context and nuance among other things. I would like to share the following condensed snippets from that conversation with you.

German and Portuguese​

• Raiane: German, one of the hardest languages to learn! I believe it is only a little harder than Portuguese, though both have complex conjugations.
• Webber: Portuguese seems hard to learn as well. The same word can have a different gender in each language, and I hear there are no clear rules to deduce whether a word should be masculine or feminine in Portuguese.
• Raiane: Oh yeah... nouns can be masculine or feminine... and yes, there's not really a "why" that was chosen. And it can become confusing too.
• Raiane: For example a car can be a she or a he, and sometimes one would just call it whatever feels right in that context. :P
• Raiane: I mean, you could say "My (she) Ranger", or "My (he, for the make Ford) Ranger" - so in this case either gender is fine.

Evolution of language​

• Webber: Now that there's a rising preference to use "they", rather than “he/she” and also “hey peeps” instead of “hey guys”, German grammar is getting into some trouble.
• Webber: For example, the English word colleagues in German becomes Kolleg*innen, where the asterisk denotes the inclusion of any gender.
• Webber: Does it become easier or harder in Portuguese or Brazilian Portuguese?
• Raiane: We use masculino and feminino when the subject is masculine (Webber). But when the subject is feminine, like when using a feminine noun or pronoun (she), the same words are used as masculina and feminina. So that by itself is a great example.
• Raiane: As part of the inclusion discussion these became exactly how it is written in English: "masculine" and "feminine". Some also suggest "masculinx" and "femininx". There are all kinds of jokes going around about this in Brazil. There’s a gender for "they" as well (eles/elas, m/f).
• Webber: Not everyone agrees in Germany either, often because of language fundamentals based on dated views on gender identity that ended up breaking the grammar in a way.
• Raiane: I think for Portuguese it would take a full grammar reform to propagate those inclusivity changes.

Inclusivity​

• Raiane: I feel very reluctant about these inclusion things. I don't know to which extent they are really including, or actually excluding or giving unfair advantages for minorities.
• Raiane: For example, someone with autism spectrum disorder could go out of their way to let people know about it, just to get an advantage.
• Raiane: Isn't giving advantages to disadvantaged minorities and acknowledging they are a disadvantaged minority creating segregation by itself?
• Webber: Agreed one the point that it's a very nuanced discussion.
• Webber: I believe a good heuristic might be to imagine when one would feel offended if something was said or not accounted for 10 years from now.
• Webber: For example: If you were to treat someone like a slave today, as people would in history (not even that long ago), many people would be offended, not excluding bystanders.
• Webber: Or if you were to tell someone - who you know is diagnosed with classic autism - to “deal with it”, referring to the noise level in an office.

Identity​

• Webber: And I believe the key is in identity.
• Webber: Lets take your example of a neurodiverse person and an example about gender:
  • As a neurodiverse person, I wouldn't feel offended if somebody does not take my neurological condition in mind, because it's not what defines me as a person.
  • If you tell someone "you are not a boy, because you don't have a penis and biology says so" to someone who doesn't identify with their biological sex, they will likely be offended because you're effectively telling them they can't be themselves.
• Webber: After the inclusivity revolution has passed, we'll probably look at gender inclusion as the most normal thing in the world - something you just do out of respect.
• Webber: However, before the end of that revolution it'll take society many examples, nuances, explanations and pioneers to pave the way, because it has to balance against conservatism. Which I wouldn't say is a bad thing by the way, as this process filters many bad ideas.

The neurodiversity example​

• Raiane: While chatting in discord, people would probably hate it if someone told them they are this or that neuro-wise. So wouldn't it be hard to bring that up even when you’d feel offended?
• Webber: Yea exactly. But my point is that you can't really be offended by people not taking into account that you’re neurodiverse, because it doesn't define you. It's not a big part of your identity. So while some people might feel offended I believe it's not always warranted.
• Webber: There's something called owning up to it as well. That said, there are traits that do require people's understanding.
• Webber: In the end it’s all about respecting each other; if someone places their autism very close to their identity, who are we to judge them?

The gender example​

• Raiane: How would a professor give a lecture about biology in a class with someone that has an identity that doesn't match their biological gender?
• Raiane: Another example that has been becoming a meme recently, are the women in sports performing remarkably well... well, and them not being biological women.
• Raiane: I mean, I want to treat people equally but the very concept of inclusion seems contradictory to equality!
• Webber: So yea, this seems controversial, but for me it can also be simplified to the following.
• Webber: Consider these two facts:
  • Women are more socially intelligent than men on average.
  • On average male bodies are stronger than female bodies.
• Webber: We don't have to be afraid of these facts, because both of these are purely based in biology and it’s just how humans evolved for thousands of years.
• Webber: However, we have to recognise is that there is a difference between sex (biology) and gender (identity), and that these facts do not make either sex more valuable.
• Webber: Furthermore, it has been scientifically proven (and not disproven) that for example men and women should be mixed equally in order to combine their qualities and to make for the best outcomes in governments, leadership, teamwork and so on.

Racial bias​

• Raiane: And here's a case from Brazil. There's a ProUni (something like pro-university) that gives advantages, for instance, for black people to qualify for university.
• Raiane: Knowing this ProUni, how can you help not thinking "that black person in class" is taking the place of a "more committed white person"?
• Webber: Yea so thinking "is that black person not taking the space of a white person" and "the white person being more committed, or more deserving" is called racial bias.
• Webber: It is normal, but it is not a good thing. Over time we should all learn to accept that Latin Americans are just as deserving as African people and vice versa. And that Europeans have humour not so different from Latin Americans.
• Webber: I believe the only real way to do that is by exposure.
• Webber: For example by having a friend, classmate or colleague, and finding out that prejudice was just a story, never based on facts, but based in fear of change and fear of the unknown.

Conclusion​

Ultimately something I keep learning is that context matters.

Every conversation is different, as it is with different people in different situations. A conversation about the Russo-Ukrainian War with someone from Brazil brings up very different nuances than a conversation about the same topic with my colleagues from Ukraine and Russia.

And yes, as a wealthy, able, white, european, male person I feel it's my responsibility to not perpetuate sexual, racial or other bias. This is the reason why I can no longer laugh at some of my friends’ jokes, which can sometimes be at the expense of gay people.

And to do that I will sometimes have to change my own point of view compared to what it was before, in order to better align with reality. And if it were up to me, ideally, so would everyone. Yes, it can sometimes be tiring, but it is also the right thing to do.

While this approach will usually lead to a successful outcome, I've found that spending just enough time up-front has led me to create working products much faster and with less effort.

As a developer, for several years I have underestimated both the importance of choosing the right tools for the job, and how crucial the time spent evaluating them really is. The key is in making informed-enough decisions about how best to achieve your goal, be it another feature, or an entirely new stack.

Thinking up front​

Think about "What should we be building? For whom? Why do they need it?"

Once we start coding we may no longer think about important concepts like development speed, maintainability and scalability of code. A good reason to do research up-front.

Another important aspect is the level of familiarity with any preferred programming languages and frameworks within the team that will build the application.

In case of a new stack, we may take these thoughts and convert them into technical requirements.

Mindset​

Requirements for an application may change at any time, sometimes very unexpectedly. Change usually doesn't have to be a bad thing, as long as you're prepared for it. This is why I believe it's best to keep architectural decisions quite practical.

Thinking ahead and not skipping over important decisions can end up saving much time. It allows you to imagine the big picture, which in turn will help you choose your tools with more insight. Then, given any collection of tools, you should also be ready to adapt to changing needs and requirements.

It is likely a good idea to start building as soon as possible after some research, to verify whether choices about tools that you have made indeed satisfy the requirements, as you suspected they would.

Make the best decisions you can, based on your current knowledge and continue doing so while moving forward and building your application. These decisions can be considered informed-enough.

Also, try to accept that some decisions you make now may be superseded by those of the future you. Once you accept that you have made the best decision at the time and that you can change your mind as you learn more, you can let go of negative feelings that could slow you down.

This mindset helps create forward momentum.

Mental model​

Perhaps keeping it practical is easier said than done. It does take a little experience to really keep things practical when there are so many nuances to explore and consider.

Having a mental model is a simple way to not get lost. Over the years I have developed a mental model that contains a few steps to consider when trying to systematically determine the most fitting stack for an application. You may use it as a starting point and remove steps or add your own as you see fit for your projects.

1. Analysis

• Requirements
  • Using modal verbs to describe must haves, nice to haves and clarify scope and limitations.

2. Fundamental choices

• Should I use code at all?
• Language and frameworks
  • Which languages does my team already know?
  • Which languages offer the most suitable frameworks?
  • Which framework will be at the core of my application?

3. Technologies

• User interface
• Data persistence
• Authentication
• Continuous Integration
• Deployment

I would recommend to timebox research for the combined steps. Probably no more than an hour for small projects, and up to a few days for projects that will likely be maintained for over two years.

Keep in mind that decisions don't have to be written in stone and may be revised as we learn more. And that's usually a good thing - we're now spending less time trying to make "perfect" decisions up-front, and we're feeding a healthy mindset of acting on informed-enough decisions based on what we know now.

Example​

I will use Takken.io as a case example to demonstrate one way of interpreting these steps and also to illustrate each step in more detail.

1. Analysis​

Application: Takken.io

Goal: A personal blog and a showcase for my hobby projects.

Requirements:

• Easy to change and extend
• Search engine friendly
• May not take longer than a weekend or two to set up

Nice to have:

• Categories for blog posts
• Some design space for custom tools I might be creating
• Easy to migrate

2. Fundamental choices​

Should I use code at all?​

Once requirements are clear, some may be eager to jump into the code editor to get started, where others may look forward to explore the options. I believe it is important to consider existing services that may already offer what you're trying to achieve. There can be much value in the work not done.

In most scenarios you'll find there are three categories of options:

• no-code options like Tumblr and Medium,
• ready-made blogging applications like WordPress, and
• building your own.

The technical knowledge that's required grows with each category respectively.

For this blog I have chosen to build my own, so that it will be easier to create a custom experience, which is something I'm looking to do over time. Since coding is my hobby it's also fine for me if that means doing a little more work than strictly necessary.

Language​

Front-end applications usually require JavaScript and are nowadays made easy by libraries like React and Vue making them the de facto choices for highly productive teams. For my simple use-case there's no reason not to choose from one of these.

Between JavaScript and TypeScript (a superset of the former) I went with TypeScript based on three major selling points:

• Many errors show up earlier during the development process because of static typing
• Editor better understands the code, which makes things like autocompletion work much better out of the box
• Setting up transpilation and linting is a breeze compared to using Babeljs

The community seems to agree, as a survey by StackOverflow puts TypeScript among the most loved languages.

Python, although capable, was not a great option for the backend because of how useful reusing types between server, client and UI components can be.

Runtime​

For JavaScript there's a choice to make about which runtime to use. We'll quickly look into that too.

Deno will likely take over from Node in a while. I would prefer to use Deno as soon as possible. At the time of writing it does not support some very powerful frameworks just yet, so I've gone with Node for now.

Framework​

Frameworks help you get a lot done quickly at the expense of their learning curve and often some loss of performance.

Over time, I've grown in favour of writing code as high-level as possible, while maintaining enough flexibility to achieve my goals. High-level code allows producing features much faster than with low-level code. This is part of why choosing a fitting framework for your project is very important.

There is an excellent comparison of both frontend frameworks and backend frameworks on StateOfJS.com that I highly recommend checking out to get a feel for what is out there.

React was my UI framework of choice because its development team at Facebook has shown their expertise and motivation to continuously improve what they have started, which includes extensive care for the experience of the developers who use their library to build complex UIs.

For the backend Next.js was a great choice because of its server side rendering capability, which is great for Search Engine Optimisation (SEO) purposes.

The more opinionated Gatsby would be an excellent alternative as it is very capable and has GraphQL integrated out of the box. I'll also keep an eye out for new and upcoming frameworks.

3. Technologies​

User interface​

For the blog it would be great to have a visually attractive page that can be found in search engines. Perhaps the posts should also be translatable.

For translations my visitors may just use Google Translate for now. For SEO, I will keep in mind that the meta information about the pages should be properly populated and further optimisations can be checked later.

To create that attractive page, my aim is to be able to customise colors, spacing and typography while keeping a consistent look throughout the application. Picking a design system up-front would most likely save me time later.

Design System​

A design system is a set of rules and principles that describe how a design should be implemented. Much like with choosing a framework for the core of the application, a design system implementation can help significantly speed up development by not reinventing the wheel through very time-consuming tasks.

A great comparison of CSS frameworks can be found on https://2020.stateofcss.com/en-US/report/.

Having tried most of the options listed in the comparison, I ended up with Ant design. Mostly because it offers a lot of functionality out of the box for React and it is relatively easy to customise; through CSS Modules and LESS variables as well as in line styles for quick fixes. It is quite good!

Data persistence​

Whether it's being done locally or in the cloud; storing and querying data is an essential part of most applications. Most storage services have significant performance capabilities, so there isn't going to be the need to worry about it much in this initial phase.

Decide what level of control is needed over the structure of the data, whether other systems may need to use the same data, and who should have ownership. It may also be helpful to consider who will be interacting with the data and how to comply with data privacy laws.

For Takken.io the posts will be written by myself. Readers and reviewers should be able to comment or fix typographic mistakes directly. Feedback or comments should be possible in some kind of comment section, or at least a thumbs up or down with an input field.

The posts can be stored as markdown. As the code of Takken.io is publicly available, readers will be able to place comments and suggest changes to the blog posts directly on GitHub.

Metadata such as likes, dislikes and feedback still needs their own storage and custom implementation in the UI. For that any database or backend-as-a-service will do.

Authentication​

To keep things simple it may be nice to have the authentication layer and the data layer from the same service, be it a CMS or a database.

Contentful CMS looks truly promising, but has a hard limit after which it would become quite expensive for personal projects and the prospect of hitting that limit feels somewhat discouraging.

Then there is the lightweight option of mongodb using a denormalised schema or one may find an elegant way to use sql databases using Next.js and some library. Vercel is a modern group that supports very big companies and their recommendations were also quite useful. https://www.google.com/amp/s/vercel.com/docs/solutions/databases.amp

After evaluating which databases would be easiest to use, my choice fell on Firebase firestore in conjunction with reactfire. Reason for choosing this is that it allows for running queries on the client and it gives control over which documents may be accessed based on the authenticated user, if any. Firebase authentication works extremely well and it's also easy to configure.

Firebase firestore works very similar to MongoDB, which can be used to migrate towards in the event that the scale of the application grows beyond optimisation limits. At that point it may be worth investing time in.

Continuous Integration​

Continuous Integration is about making the process to merge code into the primary branch a lightweight activity. Let's keep our mind on building features instead of worrying about code styles, formatting, merge conflicts, too much; Instead it's useful to set up a first iteration of a CI workflow before anything else.

Because I am using GitHub for all my projects, I will also use their CI system called GitHub Actions. For Takken.io, the compile step is done through Next.js. After compilation, the result needs to be verified.

Since Vercel has created a ready-to-use action for building and deploying Next.js applications it was the first thing to check. It turned out to be sufficient for a first iteration of the CI for this project as deployments can quickly be checked for correctness. Their plugin supports deployments both for pull requests (feature branches) and the main branch (production), so it also covers the deployment topic. Awesome!

Outcome​

For whoever may be interested; the result of the example case is a template repository called Simple React App. The code of Takken.io is based on that and is also publicly available.

Conclusion​

In order to be ready to adapt to changing requirements and in an effort to maximise the value created, it can often be useful to schedule a session to consider the right tools for the job.

By spending limited time researching up-front, we allow ourselves to make informed-enough decisions and to create forward momentum.

A mental model and timeboxing can help to stay on track, so that we do not end up spending much time on details that may not turn out to be proportionally relevant.

Decisions probably do not need to be written in stone, as many details only become clear during implementation and each iteration offers the opportunity to inspect and adapt.