Wcgw

What rusiaaman/wcgw MCP server does

rusiaaman/wcgw MCP server connects an MCP client to a local shell and workspace. It is intended for coding workflows where an agent needs to inspect a repository, make controlled file changes, run commands, and iterate on compiler or test feedback. The server also supports saving project context so a task can be resumed or handed to another AI conversation.

The available tools are:

• Initialize resets the shell and prepares the workspace environment.
• BashCommand runs shell commands with timeout control.
• ReadFiles reads one or more files.
• WriteIfEmpty creates a file or writes only when the target is empty.
• FileEdit changes existing files through search-and-replace blocks.
• ReadImage makes image files available for display or processing.
• ContextSave stores project context and file information for checkpoints or knowledge transfer.

How it works

During initialization, the server returns a selected view of the workspace structure and loads a root-level CLAUDE.md or AGENTS.md file when present. It can also load corresponding instruction files from ~/.wcgw/. File reads are chunked for large files, and a file must be read before the agent can edit or rewrite it. Edits use search-and-replace matching with tolerance for spacing differences; ambiguous or unsuccessful matches produce feedback rather than silently applying an uncertain change.

Shell commands run through a persistent, interactive terminal. The working directory is reported after commands, and command polling is designed to return quickly while still allowing status checks for processes that continue running. Multiple background commands can run alongside the main shell. Interactive terminal behavior includes keyboard input, interrupts, and ANSI escape sequences. A user can attach to the same terminal with the related VS Code extension or with screen -x.

Setup and configuration

The documented Claude Desktop setup uses uv and the uvx runner. Install uv, then add the following MCP server configuration:

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

The configuration can include --shell followed by a shell path such as /bin/bash. The README documents macOS and Linux setup, plus Windows through WSL. On WSL, Claude Desktop launches the server with wsl.exe; uv must be available globally or referenced by its full WSL path.

Tools and capabilities

rusiaaman/wcgw MCP server includes syntax checking feedback for file writes and edits, incremental handling for large changes, and protection against overwriting files that have not been read. Its default wcgw mode has no stated restrictions on shell or file access. The README also describes architect and code-writer modes: one is intended for planning, while the other focuses on code editing and project building with optional path constraints.

ContextSave writes task details and relevant file paths to a single saved context file. A later conversation can request resumption by task ID. The server can also automatically use repository instructions and supports ZSH in addition to Bash.

Limitations and notes

The server provides unfiltered access to the machine's shell and files. It does not prevent arbitrary commands or unintended changes, so it should be run only when that level of agent authority is acceptable. The documented Windows setup requires WSL rather than native Windows execution. No authentication or remote hosted endpoint is described in the provided material.