wcgw: an MCP server that gives Claude a real shell and file editor

What wcgw solves for people running coding agents

Most chat-based coding agents are limited by their tools. They can read a snippet you paste, or call a narrow function, but they cannot compile the project, watch a long-running process, or respond to a prompt that a CLI tool prints halfway through. wcgw is an MCP server built around that gap. Its README describes it as "a MCP server with tightly integrated shell and code editing tools", and the stated purpose is to let chat applications code, build and run on your local machine.

The audience is narrow and technical. You need an MCP-capable client, a machine where you are comfortable giving an agent shell access, and enough patience to configure a desktop config file. The README's own warning is the clearest statement of who this is not for: the server "does not restrict LLMs from executing arbitrary commands or making unintended changes", and it says to run the repository only if you fully understand the risks of an agent with no restrictions. That is not boilerplate caution. It is the design.

How the shell and file tools actually work

The server exposes shell and editing tools over MCP, and the mechanics it documents are mostly about keeping an agent oriented. After every shell command the current working directory is returned, so the model does not lose track of where it is. Command polling exits after a short timeout, but status checks tolerate waiting when a command is still streaming fresh output. Multiple background commands can run alongside the main interactive shell, and interactive programs are handled through arrow keys, interrupts and ANSI escape sequences.

File editing follows an Aider-like search-and-replace model rather than a tool call per change. The README says this performs better than tool-call-based replacement. Two guards stand out. The AI must read a file at least once before it may edit or rewrite it, which blocks accidental overwrites, and large files are chunked by token length so reading them does not flood the context window. Matching is spacing tolerant, warns on problems such as indentation mismatch, and returns the closest match when nothing lines up so the model can correct itself. When a search block has several matches, the tool disambiguates using previous search blocks and otherwise fails on purpose, trading convenience for correctness.

Initialisation returns a repository structure selected from .gitignore plus a statistical approach, and a ContextSave tool writes task context to a single file that a later chat can resume by task id.

Installing wcgw and running a first command from Claude

The documented path is a uvx install wired into the Claude desktop config. On macOS and Linux the README says to install uv with Homebrew, and it stresses using Homebrew because uv must live in a global location such as /usr/bin. Then add this server block to claude_desktop_config.json and restart Claude.

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

On macOS that file sits at ~/Library/Application Support/Claude/claude_desktop_config.json. After the restart the wcgw tools appear in the client. The README also documents a --shell argument to force bash or zsh instead of the detected shell.

For a first run, start in a mode with a smaller blast radius. The README says asking for architect mode produces a plan first and prevents premature file editing, and code-writer mode restricts edits to paths you supply, with wildcard support. The default wcgw mode has no restrictions. A reasonable first task is to point the agent at a small project, ask for architect mode, and let it read files and propose a plan before any write happens. If you want to watch the session, the README notes you can attach to the same terminal with screen -x, or use the wcgw VS Code extension.

The restrictions wcgw deliberately does not have

The most important limitation is the one the project advertises. There is no approval step, no command allowlist and no sandbox described in the README. An agent in the default mode can run anything your user account can run, and the README warns that the tool can be misused by attackers or run dangerous commands if the AI hallucinates. If your threat model includes a model that misreads a task, wcgw is the wrong tool as shipped.

The softer limitations matter too. File protections are heuristics, not guarantees: search-replace matching can fail by design when a block is ambiguous, and the agent then has to retry. Interactive command handling depends on terminal emulation through pyte and pexpect, so programs with unusual terminal behaviour are a plausible source of friction, though the README does not enumerate which ones. There is also a version boundary worth knowing: support for GPTs over a relay server was removed on 27 Apr 2025, and the README states that only the MCP server is supported in version 5 and later. Anyone following an older tutorial that configures a custom GPT will find it does not match current releases.

wcgw compared with a plain MCP filesystem server

The obvious alternative for many teams is a minimal MCP server that exposes file read and write plus a narrowly scoped command runner, or the filesystem servers that ship with MCP client ecosystems. The difference is statefulness. A filesystem server gives the model a set of file operations and nothing else; each command is independent and the model has to reconstruct context from tool output.

wcgw keeps a live shell session that both the agent and the human can drive. That is what makes long builds, REPLs and interactive prompts workable, and it is why the project can offer screen -x attachment and a VS Code extension that attaches the agent's shell inside the editor. The cost is exactly the thing a filesystem server avoids: a persistent process with your privileges and no confirmation gate. If your work is mostly reading and patching files, the narrower server is the safer trade. If your work involves running and debugging real programs, wcgw's shell is the reason to accept the risk.

Maintenance, licensing and the upgrade path

The repository is not archived, and the last push was on 2026-08-07. Releases are frequent and small: 5.6.5 on 2026-08-06 fixed git worktree context, 5.6.4 on 2026-07-30 was a build fix, and 5.6.2 on 2026-04-29 covered performance optimisations. pyproject.toml lists version 5.6.7, so the package version can move ahead of the newest tagged release. The changelog entries are terse, which means an upgrade is cheap to perform but not always cheap to evaluate: you may need to read the diff to know what a fix touched.

Dependencies are pinned with upper bounds (mcp>=1.23.0,<2, anthropic>=0.39.0,<1, openai>=1.46.0,<3), and Python 3.11 or newer is required. That bounding reduces surprise breakage from upstream. The project ships a Dockerfile whose entrypoint is wcgw_mcp and which installs screen, so a containerised run is possible, but the README's install instructions are the uvx route rather than the container. The licence is Apache-2.0, which permits commercial use and modification with the usual notice and patent terms; this is a description of the licence file, not legal advice, and you should read it in full if you plan to redistribute.

Editorial conclusion

Adopt wcgw if you want an MCP client to drive a real terminal on a machine whose loss you can tolerate, and if you will start in architect or code-writer mode before letting it run unrestricted. Do not adopt it if you need per-command approval, sandboxing, or a guarantee that an agent cannot overwrite files outside a workspace; the README states plainly that it does not restrict LLMs from executing arbitrary commands. Before trusting it, read the modes section of the README, confirm which CLAUDE.md or AGENTS.md file your project root contains, and check the release notes for the version you pin, since the project dropped GPT relay support at version 5.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. README
4. Releases
5. rusiaaman/wcgw on GitHub