wsl-env

name

wsl-env

description

Reach and act on Windows-side services, processes, launchers, and logs when the agent runs inside WSL. Use whenever a service seems unreachable from WSL (a localhost curl fails), when you need to start/stop or inspect a Windows-side process or .ps1 launcher, read Windows logs, hibernate the machine, or when the repo ships both a .sh and a .ps1 entry point. Self-detecting: if this is not WSL or the target is not Windows-side, it is a no-op. Applies inside subagents too. Never conclude "unreachable" or "can't test this" from WSL without first trying both the Windows LAN-IP and powershell.exe.

wsl-env - WSL to Windows-side helper

When the agent runs inside WSL, the thing it needs to reach or drive often lives on the Windows side. WSL frequently cannot reach Windows localhost ports directly, so a naive curl localhost:PORT failing is NOT evidence that a service is down. This skill defines how to detect that situation and how to act across the WSL/Windows boundary correctly.

Self-detect first (no-op when irrelevant)

Before doing anything WSL-specific, check whether it applies:

• Is this actually WSL? Check for the WSL kernel signature, e.g. grep -qi microsoft /proc/version (or check /proc/sys/kernel/osrelease). If not WSL, this skill is a no-op - use normal local access.
• Is the target Windows-side? A service bound by a Windows process, a Windows .ps1 launcher, a Windows path, or a machine-level action (hibernate). If the target is a native Linux service inside the WSL distro, this skill is a no-op - reach it the normal Linux way.

Only when both are true do the rules below apply.

Reaching a service: try BOTH methods before giving up

A service reachability failure from WSL has two distinct fixes depending on how the service is bound. Never conclude "unreachable" without trying both.

1. Service bound to 0.0.0.0 (all interfaces): reachable from WSL via the Windows LAN-IP, NOT via localhost/127.0.0.1. Point the request at the host's real LAN address plus the port.

2. True localhost-only service (bound to 127.0.0.1 on Windows): not reachable from WSL by IP at all. Reach it by running the request on the Windows side through powershell.exe, for example:

   powershell.exe -NoProfile -Command "(Invoke-WebRequest -UseBasicParsing -TimeoutSec 5 http://localhost:PORT/path).Content"
   

Rule: if the LAN-IP method fails, try the powershell.exe method (and vice versa) before reporting the service as down.

Getting the values: config first, then discover

The LAN-IP is environment-specific and DYNAMIC - the host's real LAN address. Resolve it at runtime, never hardcode it; the config only caches it:

"${CLAUDE_PLUGIN_ROOT}/scripts/credo-config.sh" get personal.wsl.lan_ip

Windows-side services are configured as a named endpoint list under personal.wsl.endpoints, each entry {name, port, reach}. The reach field records how that one endpoint is reached, because different services on the same machine bind differently:

• reach: lan_ip - the service binds 0.0.0.0; reach it from WSL via the Windows LAN-IP plus its port, never via localhost/127.0.0.1.
• reach: localhost - the service is Windows-localhost-only; reach it by running the request on the Windows side through powershell.exe.

So a single repo can have several endpoints, each with its own reach path - for example a UI/panel via lan_ip and an API via localhost - and you pick the method per endpoint from its reach field, not one method for the whole machine. Read the list with:

"${CLAUDE_PLUGIN_ROOT}/scripts/credo-config.sh" get personal.wsl.endpoints

(Config keys: personal.wsl.lan_ip and personal.wsl.endpoints. Empty by default - fill just-in-time with the user's permission. Never conclude a service is unreachable without having tried both reach methods for its endpoint.)

If the LAN-IP is not configured, discover it generically on the Windows side rather than guessing. Query the Windows adapters and pick the real physical LAN adapter (Wi-Fi or Ethernet), not a virtual adapter (WSL, Hyper-V, VirtualBox, and similar virtual switches have their own addresses that are not the machine's LAN address):

powershell.exe -NoProfile -Command "Get-NetIPAddress -AddressFamily IPv4 | Select-Object IPAddress,InterfaceAlias"

Choose the address whose InterfaceAlias is the real Wi-Fi/Ethernet adapter and whose address is a private LAN address. Do not assume any particular subnet - what is a valid LAN range on one machine is not on another. Confirm the choice by reachability, then offer to store it in config so it need not be rediscovered.

Windows processes, launchers, logs, power-down: use powershell.exe

Anything on the Windows side is driven through powershell.exe, which runs in the Windows context and can see Windows localhost, processes, and scripts:

• Inspect processes: powershell.exe -NoProfile -Command "Get-CimInstance Win32_Process -Filter \"name='python.exe'\" | Select ProcessId,CommandLine"
• Start a Windows-side server by invoking the project's .ps1 launcher via powershell.exe - run it detached / in the background so the WSL call does not block on a foreground server.
• Stop a Windows-side process: powershell.exe -NoProfile -Command "Stop-Process -Id <pid>" or the project's stop script.
• Read Windows logs by having powershell.exe read them on the Windows side.
• Machine power-down on the Windows side runs through powershell.exe too, but the ACTUAL autonomous power-down command credo runs is NOT hardcoded here - it comes from the credo sleep.command config (set at /credo:setup; on WSL that is typically shutdown.exe /h). It is governed by the credo autonomous-session sleep rules (veto window and double-fire protection; never on the agent's own initiative outside those rules). sleep.command is the source of truth.

If a Windows-side service must accept inbound connections from WSL and still cannot be reached after both methods above, a Windows Firewall inbound rule for that port may be required. Propose it; do not silently change the firewall.

Dual-platform parity (.sh + .ps1)

When a repo is meant to run on both Linux/WSL and Windows, entry points and helper scripts need a working counterpart on each platform - a .sh and an equivalent .ps1. The agent checks for itself whether this parity is relevant for the current repo (it is not relevant for a Linux-only or Windows-only project). If it is relevant, keeping the two in parity is mandatory: do not add or change one platform's script without providing or updating the other. A missing counterpart on a dual-platform repo is an incomplete change, not an optional extra.