wcgw hands an MCP client an unrestricted shell, and says so first
Shell and coding agent on mcp clients
At a glance
- What is it?
- rusiaaman/wcgw is a Python MCP server that gives Claude and other clients a real interactive terminal and guarded file editing, with architect, code-writer and unrestricted modes. Its own warning block is the honest part: no authentication, no command filtering, and hallucination-driven damage is a documented outcome.
- Who is it for?
- wcgw is for a developer who wants an agent to drive a real terminal rather than a sandbox, on a machine where a wrong command costs nothing. It is not for an unattended agent, a shared host or a device holding credentials you cannot rotate, because the default mode has full authorisation and the server adds no filtering of its own.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- No. The owners have archived the repository on GitHub, so it is read-only and no longer receives changes.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- rusiaaman/wcgw679 ★ · +5
| Repository | 2026-09-11 | 2026-11-15 |
|---|---|---|
| rusiaaman/wcgw | 674 | 679 |
5 Stars in the last 65 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The warning paragraph is the most honest part of the README
The second paragraph of the documentation is a warning, and it is unusually blunt. This MCP server provides unfiltered access to your machine's shell and files. It does not restrict language models from executing arbitrary commands or making unintended changes. It can be misused by attackers, and it can run dangerous commands if the model hallucinates. The instruction to the reader is to run the repository only if you fully understand and accept the risks of running AI agents with no restrictions. There is no allowlist, no confirmation callback and no sandbox in that description. Everything else the project offers, the interactive terminal, the file protections, the modes, is layered on top of that baseline rather than reducing it, which is why the choice of whether to install it is really a choice about what a hallucination is allowed to do to your disk.
The reason to use it is a terminal both sides can drive
The stated rationale, framed for 2026, is an interactive shell experience that you and the agent can both control, including sending key-strokes, combined with a VS Code extension that attaches the agent's shell inside your editor. That is the actual differentiator against a tool that runs one command and returns text. Commands are interactive in the full sense, with arrow keys, interrupt handling and ANSI escape sequences supported, and the terminal runs multiplexed so you can attach to the same session the agent is using, either through that extension or with screen -x, to read history, interrupt a process or type at the prompt. On the shell side there are three optimisations aimed at keeping a model oriented: the current working directory is returned after every command, command polling gives up quickly so feedback is not slow, and status checks tolerate waiting when a command is still streaming fresh output.
File edits are gated by a read-before-write rule
The protections here are specific enough to be worth reading before you enable them. The model must read a file at least once before it is allowed to edit or rewrite it, which exists to prevent accidental overwrites of files it has never seen. Very large files are chunked by token length so reading them does not flood the context, and on initialisation the workspace directory structure is returned after selecting the important files, using .gitignore plus a statistical approach rather than sending the whole tree. Edits are search-and-replace with spacing-tolerant matching that warns about problems such as indentation mismatch, and when nothing matches, the closest match is handed back to the model so it can correct itself instead of guessing. A block with multiple candidate matches is resolved against previous search blocks and fails rather than picking one, which is a deliberate correctness choice. Syntax checking reports errors back to the model on write, and large edits are split incrementally based on the percentage of the file changing.
Three modes, and the default one is unrestricted
Modes are the only scope control in the design, and they are worth understanding before your first run. Architect mode is for planning, inspired by aider's architect mode, so a plan is agreed before anything is written, which is meant to improve accuracy and prevent premature edits. Code-writer mode is for editing and building, and it accepts specific paths with wildcard support so other files cannot be touched. The default is wcgw mode, described as having no restrictions and full authorisation. Context handling sits alongside those modes. A ContextSave tool writes detailed context, including relevant file paths with descriptions, into a single file that acts as a task checkpoint or a knowledge transfer artefact, and a later conversation can resume it by asking to resume that task id. Project instructions are loaded automatically from CLAUDE.md or AGENTS.md at the project root, with global copies under a .wcgw directory, the filename match being case sensitive and CLAUDE.md preferred when both exist.
Configuration is one JSON block launched by uvx
Setup for Claude Desktop on Mac and Linux starts with installing uv through homebrew, with an explicit instruction that uv must be on a global path such as /usr/bin/ if it came from anywhere else. Then claude_desktop_config.json gets an entry whose command is uvx and whose arguments pin Python 3.12 and the latest wcgw release, followed by restarting the app. Two options extend it. A --shell argument forces a specific shell, bash or zsh, for clients that default to something else. And the server keeps stdio as its default transport, but can be run as a long-lived HTTP endpoint for gateways that prefer one:
uvx --python 3.12 wcgw@latest --transport streamable-http --host 127.0.0.1 --port 8765That endpoint is served under an /mcp/ path and, as documented, is bound to loopback, which is the right default for a server with no authentication. One inconsistency in the setup section is worth noting for Linux users, since the configuration file path given is the macOS application support location rather than a Linux one.
Both vendor SDKs remain dependencies after one integration was dropped
The dependency list explains more about the project's history than the update log does. It requires Python 3.11 or newer and pulls in both the OpenAI SDK, bounded above by version 3, and the Anthropic SDK, even though an April 2025 note records that support for GPTs over the relay server was removed and only the MCP server is supported from version 5 onward. The rest of the list maps onto the features. pexpect drives the pseudo-terminal that makes interactive commands possible, and pyte parses what comes back. tokenizers counts tokens so files can be chunked, pygit2 handles the git side, tree-sitter with a bash grammar reads repository structure, wcmatch does glob matching, and psutil covers process state. One dependency is pinned to a single exact version, syntax-checker at 0.4.0, while everything else carries a range, so that one will age differently from the rest. Three console scripts are declared, and two of them, wcgw and wcgw_mcp, point at the same server function.
Version 5.6.7 in the manifest, 5.6.6 in the release list
Three release notes say more about where the work is than the updates section does. Version 5.6.6, published on 12 September 2026, is titled MCP session isolation and concurrent tool calls. Version 5.6.5, from 6 August, is a git worktree context fix, and 5.6.4 in late July is a build fix. That last commit is also the last push to the repository. Meanwhile the manifest declares 5.6.7, one patch ahead of the newest tag, so the source tree and the published history differ by a version. The human-readable updates list is the stalest artefact in the repository, since its newest entry is dated 6 October 2025 while releases continued through 2026. Two housekeeping details survive in the tree as well. A .gitmodules file is still present even though the container build states twice that no submodule is cloned any more, and the Dockerfile is generated by Smithery, uses the astral uv image for building and a plain slim Python image for running, installs screen because of the terminal attach feature, drops to a non-root app user, and starts wcgw_mcp from a workspace directory.
Editorial conclusion
wcgw is for a developer who wants an agent to drive a real terminal rather than a sandbox, on a machine where a wrong command costs nothing. It is not for an unattended agent, a shared host or a device holding credentials you cannot rotate, because the default mode has full authorisation and the server adds no filtering of its own. Before you point a client at it, read the warning block rather than skipping it, pick the architect or code-writer mode with explicit paths for any task that touches a repository, and run it inside a container or a disposable machine. If you need an audit trail or a permission gate, this is the wrong tool.
Frequently asked questions
What does wcgw give an MCP client such as Claude?
Unfiltered access to your shell and files plus code editing tools, including a real interactive terminal with key-strokes, arrow keys, interrupts and ANSI handling, and file protections that require a read before an edit and report syntax errors back to the model. The project's own warning states it does not restrict models from executing arbitrary commands.
How do I configure wcgw in Claude Desktop?
Install uv through homebrew, or make sure uv is on a global path such as /usr/bin/, then add an mcpServers entry to claude_desktop_config.json whose command is uvx and whose arguments are --python, 3.12 and wcgw@latest, and restart the app. Add --shell with a shell path to force bash or zsh.
Is wcgw safe to leave running?
Not by default, and the project says so. There is no authentication and no command filtering, the default wcgw mode has full authorisation, and a hallucinated command can do damage. The scope controls are modes: architect for planning, code-writer with explicit paths and wildcards, plus ContextSave checkpoints, and running it inside a container is the practical containment.
How do I serve wcgw over HTTP instead of stdio?
Run uvx --python 3.12 wcgw@latest --transport streamable-http --host 127.0.0.1 --port 8765, which is the documented command for clients and gateways that prefer a long-lived endpoint. The MCP endpoint is then served under http://127.0.0.1:8765/mcp/, and the documentation notes that binding to loopback is the default.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/rusiaaman-wcgw)Star history chart for your README
[](https://hysenlabs.com/projects/rusiaaman-wcgw)Was this useful?