acp-wsl lets a Windows IDE plugin communicate over ACP with an agent running in WSL.
It is an ACP stdio proxy that translates ACP filesystem paths between Windows drive paths and the corresponding
/mnt/<drive> WSL paths. Install it on Windows or in WSL and route ACP traffic through it.
Download the release binary for your operating system and architecture from GitHub Releases.
- Download from latest release.
- Rename and place it on
PATH.- on Windows, rename to
acp-wsl.exe. - on WSL, rename to
acp-wsland make executable.
- on Windows, rename to
To build from source instead, use the Go version declared in go.mod:
go build ./cmd/acp-wsl
acp-wsl [--unknown-fields=false] -- <agent-command> [agent-arguments]
Run the proxy on either side of the boundary:
| Proxy location | Command |
|---|---|
| Windows | acp-wsl -- wsl --distribution Ubuntu -- your-acp-agent |
| WSL | acp-wsl -- your-acp-agent |
The command after -- is started by acp-wsl. ACP messages pass between the Windows client and that command over
standard input and output.
--unknown-fields defaults to true. For ACP messages that do not match the embedded schema, it also maps an
absolute Windows or WSL path in unrecognized payload fields. ACP permits agents to send custom fields, which may
contain paths not covered by the schema.
Set --unknown-fields=false to disable mapping outside the embedded ACP schema:
acp-wsl --unknown-fields=false -- <agent-command> [agent-arguments]
When enabled, unknown-field mapping recognizes only absolute C:\..., C:/..., and /mnt/c/... values. Documented
ACP path fields remain mapped. Free text, command arguments, environment values, and non-file URLs are not candidates.
--version prints the installed version and exits.
--help prints command usage and exits.
| Windows client → WSL agent | WSL agent → Windows client |
|---|---|
C:\work\project → /mnt/c/work/project |
/mnt/c/work/project → C:\work\project |
file:///C:/work/project → file:///mnt/c/work/project |
file:///mnt/c/work/project → file:///C:/work/project |
Mapped fields in official ACP are defined in:
ACP v1 and v2 filesystem fields and typed file: URIs are mapped.
UNC paths, drive-relative paths such as C:work, and current-drive-rooted paths such as \work are forwarded
unchanged; the proxy cannot determine their absolute location.
Here are configuration examples for the communication of IDE plugins on Windows to agents in WSL.
- Install the IDE plugin.
- Install
acp-wsleither on Windows or in WSL. - Copy the entry for the agent and proxy location you want into the plugin configuration.
| IDE | Plugin | Example configuration |
|---|---|---|
| VS Code | ACP Client | settings.json |
| JetBrains | AI Assistant | acp.json |
The agent and its adapters should run with WSL's Node.js and npm — not node/npm in Windows inherited through
PATH.
Also install the ACP adapter for these agents:
- Amp: amp-acl
- Claude: claude-agent-acp
- Codex: codex-acp
acp-wsl-debug behaves like acp-wsl with the additional option --log-file.
acp-wsl-debug --log-file <path> -- <agent-command> [agent-arguments]
--log-file <path> logs forwarded ACP traffic before and after mapping, mapping decisions, stream errors, and agent
process exit status.
Warning: The log contains raw ACP traffic, including API keys, credentials, prompts, source paths, and agent output.
Download the debug command from the latest release (acp-wsl-debug.zip) or build it from source:
go build ./cmd/acp-wsl-debug