# rusiaaman/wcgw [Health: Active]

**Category:** 🛠️ Other Tools and Integrations  
**Repository:** https://github.com/rusiaaman/wcgw/blob/main/src/wcgw/client/mcp_server/Readme.md  
**GitHub Stars:** 674  
**Views:** 3  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/rusiaaman-wcgw

## Description
Autonomous shell execution, computer control and coding agent. (Mac)

## Tools
Capabilities this server exposes over MCP:

- **Initialize** — Reset shell and set up workspace environment
- **BashCommand** — Execute shell commands with timeout control
- **ReadFiles** — Read content from one or more files
- **WriteIfEmpty** — Create new files or write to empty files
- **FileEdit** — Edit existing files using search/replace blocks
- **ReadImage** — Read image files for display/processing
- **ContextSave** — Save project context and files for Knowledge Transfer or saving task checkpoints to be resumed later

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "wcgw": {
    "command": "npx",
    "args": ["-y","@modelcontextprotocol/inspector@0.1.7"]
  }
}
```

## Documentation

## 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:

```json
{
  "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.

_Full upstream README: https://allmcps.com/mcp/rusiaaman-wcgw/readme_