Skip to content

wsl

This directory provides native integration for the Windows Subsystem for Linux (WSL) within the Talon voice control system. It allows users operating in Windows terminal environments to seamlessly control their WSL linux distros, perform terminal commands, and translate file paths dynamically between Windows and Linux environments.

Key Components

The functionality is split across two core files:

  • wsl.talon: Defines the user voice commands, context activation rules, and inherits tags for unix shell commands, git, and Kubernetes (kubectl).
  • wsl.py: Coordinates registry-based Linux distribution discovery, window title parsing, terminal action overrides, and path translation between the Windows host and WSL guests.

How it Works

The integration focuses on robust terminal control, distribution discovery, and dynamic path tracking.

1. Dynamic Path Translation and Detection

To map commands like directory changes correctly, Talon must know the current working directory inside WSL. wsl.py monitors the active window title.

  • Window Title Convention: By modifying your shell's prompt (e.g., in .bashrc) to append the current path and WSL distro name to the terminal window title, Talon's background regex can extract the active distro and the current Linux path.
  • Path Conversion: wsl.py leverages the native wslpath utility within the targeted distribution to safely translate Linux-style paths (like /mnt/c/Users/... or /home/user/...) into standard Windows paths, and vice-versa.
  • Special Folder Remapping: Standard directories such as Desktop, Documents, and OneDrive are dynamically remapped to their correct absolute Windows host paths depending on the system's configuration.

2. Automatic WSL Distribution Discovery

wsl.py reads the Windows Registry at: HKEY_CURRENT_USER\SOFTWARE\Microsoft\Windows\CurrentVersion\Lxss

It registers a key change notifier (RegNotifyChangeKeyValue) to automatically detect when new WSL distributions are installed or removed, ensuring that Talon commands target valid active environments.

3. Voice Commands and Terminal Controls

When the user.wsl tag is active, the following actions and commands from wsl.talon become available:

  • Path Shortcuts: Saying go <user.letter> translates directly to opening host-mounted drives (e.g. go c navigates to /mnt/c via the file_manager_open_volume action).
  • Standard Terminal Navigation: Standardizes terminal commands (clear, list directories, change directory, kill running process) to work across generic UNIX tools.

Fallbacks and Stability

Running WSL commands asynchronously from the Windows host can occasionally block or hang if a distribution terminates or becomes unresponsive.

To prevent Talon from stalling or stuttering when this occurs, wsl.py implements several safety measures:

  • Failure Detection: If the script encounters a "WSL instance has terminated" error or a repeated timeout, it automatically disables WSL path detection to protect Talon’s UI thread.
  • Encoding Normalization: It handles unique UTF-16-LE encoding anomalies that sometimes occur with WSL-related command line output, decoding them cleanly into standard Python strings for logging.
  • Manual Recovery: If path detection is automatically disabled due to a WSL crash, you can manually re-enable it using the voice command (wsl | weasel) reset path detection once your WSL instance has been restarted.