wcgw: an MCP server that hands the model a real terminal

The gap wcgw fills: an agent that can actually type

Most coding agents treat the shell as a request-response function. They send a command, wait for the process to exit, and read the captured output. That model breaks the moment a command wants input. A prompt from a package manager, a pager waiting for q, a debugger stopped at a breakpoint, or a long build that needs to be interrupted all fall outside it. wcgw's answer is to keep a real interactive terminal alive and let both the model and the human drive it. The README describes the pitch directly: it provides a fully interactive shell experience that you and the agent both can control, including sending keystrokes. The project also ships a VS Code extension that attaches the agent's shell inside the editor, and the README notes you can attach with screen -x instead. That second path matters because it does not require the extension at all. The intended user is someone running Claude Desktop or another MCP client on their own development machine, working in a repository they already trust, who wants the agent to compile, run tests, and iterate rather than hand back a patch to apply manually.

What the model sees: tools, modes, and the read-before-write rule

wcgw is an MCP server, so the client discovers its tools rather than the user invoking them. The README names several: an initialize call that returns a selected view of the workspace directory structure, a ContextSave tool, and the shell and file editing tools themselves. Two behaviours are worth calling out because they shape how the agent behaves. First, the current working directory is returned after every shell command, which stops the model from losing track of where it is after a cd. Second, a file must be read at least once before the agent is allowed to edit or rewrite it. That is a deliberate correctness constraint, not a convenience: it blocks the class of failure where a model rewrites a file it has never seen. Editing itself uses Aider-like search and replace rather than tool-call-based edits, and the README claims better performance for that approach, with spacing-tolerant matching, indentation mismatch warnings, and closest-match feedback when nothing matches. Syntax checking runs on writes and edits and the result is fed back to the model so it can correct itself. Modes change the blast radius. The default is wcgw mode, described as having no restrictions and full authorisation. Architect mode is for planning before any file is touched. Code-writer mode accepts specific paths with wildcard support and prevents other files from being edited. That last one is the only real scoping mechanism the project offers, and it is worth understanding before you start.

Installing it: uvx, one JSON block, and the shell flag

The documented path is short. Install uv with Homebrew on macOS or Linux (brew install uv), and the README stresses using Homebrew so that uv lands in a global location such as /usr/bin/, because the MCP client launches the server outside your shell environment. Then add an entry to claude_desktop_config.json, which on macOS lives at ~/Library/Application Support/Claude/claude_desktop_config.json. The entry the README gives is an mcpServers object with a wcgw key whose command is uvx and whose args are --python, 3.12, and wcgw@latest. Restart the Claude app afterwards. There is an optional --shell argument if you want to pin bash or zsh; the README notes zsh became a supported shell in an October 2025 update. Note the versioning implication of wcgw@latest: every restart can pull a different build, and the release history shows why that matters. 5.6.4 was a build fix and 5.6.5 a git worktree context fix, both within a week of each other. Pinning a specific version instead of @latest is possible with the same uvx invocation, but the README does not walk through it, so you would be working from uv's own documentation rather than wcgw's.

The warning is the design, and that is the main limitation

The README opens with a warning block: the server provides unfiltered access to the machine's shell and files, does not restrict the LLM from executing arbitrary commands or making unintended changes, and can be misused by attackers or run dangerous commands if the AI hallucinates. It tells you to run the repository only if you fully understand and accept the risks of running AI agents with no restrictions. Read that as a statement of architecture rather than legal caution. There is no sandbox, no container boundary, no command allowlist, and no approval prompt described anywhere in the material. The mitigations that exist are about correctness and context, not containment: read-before-write, syntax checking, chunked reads of large files, and the code-writer mode's path globs. Path globs constrain which files an edit tool will touch. They do not constrain what a shell command can do, and the shell is the point of the project. If your threat model includes a prompt-injected instruction arriving through a file the agent reads, wcgw's own documentation says it will not stop it. There is also a practical failure mode around long-running commands: the README describes command polling exiting after a quick timeout, with status checking using wait tolerance based on fresh output streaming. That is a reasonable design, but it means the agent's sense of whether a silent command is still working depends on output arriving. A command that runs for minutes without printing anything is the awkward case.

Background commands, multiplexing, and what happens when you take the keyboard

The interactive model has a real cost, and the README is honest about the mechanism that pays it. wcgw runs in a multiplex terminal. You attach with screen -x, or through the VS Code extension, and then you can read history, interrupt a process, or type into the same terminal the agent is using. This is genuinely different from watching a log. It also means two writers share one terminal. If you type while the agent is mid-command, you are both sending input to the same process, and there is nothing in the material describing a lock or a handoff protocol. The upside is that you can rescue a stuck session without killing it. The README also notes that the model can run multiple commands in the background alongside the main interactive shell, a change listed in the October 2025 updates. Combined with the attach path, that gives a workflow where the agent starts a dev server or a test watcher in the background and you inspect it directly. The cost is state: background processes accumulate, and nothing in the supplied material describes a cleanup or listing command for them.

ContextSave and CLAUDE.md: the parts aimed at long sessions

Two features exist because long agent sessions degrade. ContextSave writes relevant file paths plus a description into a single file, which the README frames as a task checkpoint or a knowledge transfer artifact. The stated workflow is that you later resume by asking the client to resume a given task id in a new chat. That is a manual, file-based persistence layer rather than automatic memory, and it is honest about being one. The second is instruction loading: on initialisation, wcgw looks for CLAUDE.md or AGENTS.md in the project root and sends it as instructions. A global file at ~/.wcgw/CLAUDE.md or ~/.wcgw/AGENTS.md is loaded alongside it. The filename is case sensitive, and CLAUDE.md takes precedence when both exist. This is the standard place to put build commands, test invocations, and style rules, and because it is loaded at initialisation rather than per-message, editing it mid-session will not take effect until you restart. Neither feature is unusual on its own. What is notable is that wcgw treats session continuity as a file format rather than a server-side store, which keeps the project stateless between runs and makes the checkpoint portable to another tool.

How it compares to Aider and to sandboxed agent runners

The README itself points at Aider twice: the search-and-replace edit format is described as Aider-like, and architect mode is credited as inspired by Aider's architect mode. The difference is the shape of the product. Aider is a CLI you run and talk to in your terminal; it owns the conversation and drives the edits. wcgw is an MCP server, so the conversation lives in Claude Desktop or another MCP client and wcgw supplies only the tools. That distinction decides most adoption questions. If you want a self-contained terminal pair-programmer with its own model routing, Aider is the closer fit. If you already pay for a chat client and want that client to reach your machine, wcgw is the adapter. The other comparison worth making is against agent runners that execute inside a container or a VM. Those trade interactivity for containment: you cannot attach with screen -x to a container that has already exited, and you cannot hand-keystrokes to a process the agent started. wcgw makes the opposite trade, and the warning at the top of its README is the price tag. A third option is doing nothing and pasting diffs by hand, which remains the only approach with no execution risk at all.

Maintenance, licensing, and what to check before you commit

The project is Apache-2.0, which permits commercial and private use and includes an explicit patent grant. That is a permissive licence, and it is the same family as MIT with additional terms around patent retaliation and attribution. Nothing here is legal advice; if you are embedding wcgw in a product, read the licence text yourself. On maintenance, the repository is active rather than archived, with a release cadence that has included both feature work and small corrective releases, and CI covering tests, strict mypy, and publishing. The Python version pin in the documented config is 3.12, so the server runs on an interpreter you may not otherwise have installed; uvx handles that, but it means the first launch downloads an interpreter. The upgrade cost is mostly the @latest tag combined with a fast release cadence: a restart can silently move you to a build with changed shell behaviour, and the release notes for 5.6.4 and 5.6.5 suggest that small regressions do ship. If you run wcgw against a repository with uncommitted work, a git worktree, or a long-lived dev server, pin the version and commit before you start a session. The first thing to verify on your own machine is that the agent's shell is genuinely the one you attached to with screen -x, and that code-writer mode's path globs actually block an edit outside the set you named. Both are claims you can test in a scratch repository in a few minutes, and both determine whether the rest of the tool is usable for you.

Editorial conclusion

Adopt wcgw if you already run Claude Desktop or another MCP client and you want the agent operating in your own terminal, with the ability to attach via screen -x and take the keyboard back mid-command. Do not adopt it if you need a sandbox, an approval step before command execution, or a hosted setup: the README states plainly that it provides unfiltered shell and file access and does not restrict the model. Before installing, verify that uvx is on your PATH from a global location, confirm the MCP entry in claude_desktop_config.json points at wcgw@latest with --python 3.12, and decide whether the default wcgw mode is acceptable or whether you want to start in code-writer mode with explicit path globs.

Official sources

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