wcgw for Claude Code: Setup & Config

What you can do with wcgw in Claude Code

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

• Run compiler checks and iterate on code changes.
• Save a task checkpoint and resume it in another chat.

Before you start: wcgw in Claude Code

• 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 Claude Code configuration

1. Choose Claude Code configuration scope

   For wcgw, open Project scope: .mcp.json at the repository root. Project JSON: merge into mcpServers; user scope: use the CLI.

2. Add wcgw to Claude Code

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

3. Check wcgw in Claude Code

   wcgw: Inspect claude mcp list and /mcp status.

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

claude mcp add-json --scope project 'wcgw' '{"type":"stdio","command":"uvx","args":["--python","3.12","wcgw@latest"],"env":{}}'

wcgw tools available to Claude Code

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

Initialize

For wcgw's Initialize, review the permission request and arguments in Claude Code before approval.

BashCommand

For wcgw's BashCommand, review the permission request and arguments in Claude Code before approval.

ReadFiles

For wcgw's ReadFiles, review the permission request and arguments in Claude Code before approval.

Read one or more files into the assistant context.

WriteIfEmpty

For wcgw's WriteIfEmpty, review the permission request and arguments in Claude Code before approval.

Write a new file or populate an empty one.

FileEdit

For wcgw's FileEdit, review the permission request and arguments in Claude Code before approval.

Modify a file using search-and-replace blocks.

ReadImage

For wcgw's ReadImage, review the permission request and arguments in Claude Code before approval.

ContextSave

For wcgw's ContextSave, review the permission request and arguments in Claude Code before approval.

Store task context and relevant files for later continuation.

wcgw: full stored tool descriptions

Troubleshooting wcgw in Claude Code

• If wcgw fails to start, check uvx --python (from uv, for Python tools), the working directory, and Claude Code's selected scope; inspect claude mcp list and /mcp.
• wcgw uses stdio here: Claude Code 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 Claude Code troubleshooting lives in the /clients/claude-code guide.

Frequently asked questions