wcgw for Windsurf: Setup & Config

What you can do with wcgw in Windsurf

Choose wcgw for a shared interactive agent terminal plus code-editing and checkpoint tools.

• Share an interactive terminal with an assistant.
• Save a task checkpoint and resume it in another chat.

Before you start: wcgw in Windsurf

• uv / uvx available to the MCP client
• Python 3.12 for the documented launch
• WSL on Windows

The README documents this configuration for Claude Desktop. A --shell argument can select bash or zsh. Understand the unrestricted shell and file-access risks before running it.

wcgw Windsurf configuration

1. Choose Windsurf configuration scope

   For wcgw, open macOS/Linux: ~/.codeium/windsurf/mcp_config.json Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json. Merge into mcpServers; remote endpoints use serverUrl.

2. Add wcgw to Windsurf

   Use the wcgw entry below in mcpServers. Keep wcgw's documented stdio connection fields and your other Windsurf entries.

3. Check wcgw in Windsurf

   wcgw: Refresh MCP in Windsurf settings and inspect Cascade’s tools.

{
  "mcpServers": {
    "wcgw": {
      "command": "uvx",
      "args": [
        "--python",
        "3.12",
        "wcgw@latest"
      ],
      "env": {}
    }
  }
}

wcgw tools available to Windsurf

wcgw's stored tool list documents 7 tools; compare it with Windsurf's connected tool list, because the stored list is not a live check.

Initialize

After refreshing wcgw in Windsurf settings, check Cascade's tool list for Initialize.

Set up the shell and workspace, or resume saved task context.

BashCommand

After refreshing wcgw in Windsurf settings, check Cascade's tool list for BashCommand.

Run shell commands or send interactive input to the terminal.

ReadFiles

After refreshing wcgw in Windsurf settings, check Cascade's tool list for ReadFiles.

WriteIfEmpty

After refreshing wcgw in Windsurf settings, check Cascade's tool list for WriteIfEmpty.

Write a new file or populate an empty one.

FileEdit

After refreshing wcgw in Windsurf settings, check Cascade's tool list for FileEdit.

ReadImage

After refreshing wcgw in Windsurf settings, check Cascade's tool list for ReadImage.

ContextSave

After refreshing wcgw in Windsurf settings, check Cascade's tool list for ContextSave.

Store task context and relevant files for later continuation.

wcgw: full stored tool descriptions

Troubleshooting wcgw in Windsurf

• Check uvx --python (from uv, for Python tools) on the machine running Windsurf's MCP integration for wcgw; refresh MCP and inspect Cascade's tools.
• wcgw uses stdio here: Windsurf must keep the configured process running; protocol output belongs on stdout and diagnostics on stderr.
• Known limitation: Default mode gives unrestricted shell and filesystem access.
• Known limitation: Code-writer command lists are not enforced allow-lists.
• Known limitation: Windows requires WSL.
• General Windsurf troubleshooting lives in the /clients/windsurf guide.

Frequently asked questions