wcgw Local Coding Terminal
An MCP server that lets chat clients run local shell commands, edit code, and share an interactive terminal.
What does this agent do, and when should you use it?
wcgw is a local MCP server for Claude and other MCP clients with integrated shell and code-editing tools. Once configured, a client can initialize a workspace, run commands, read files, create empty files, and edit existing files through search-and-replace blocks. When screen is available, commands run in a multiplexed terminal that a user can join through `screen -x` or the accompanying VS Code extension. Its ContextSave tool stores a task description and selected project files in one file for later resumption or knowledge transfer. The repository explicitly grants unfiltered access to the machine's shell and files, so it is suited to developers who accept that local-execution risk and want hands-on terminal control.
Initialize resets the shell, prepares a workspace, optionally reads initial files, and can resume a task_id_to_resume. BashCommand runs shell commands and can send interactive input through send_text, send_specials, or send_ascii. ReadFiles reads one or more files; WriteIfEmpty creates files or writes only to empty ones; FileEdit changes existing files with search/replace blocks; and ReadImage reads image files. Initialization returns a filtered repository structure and can load project or global CLAUDE.md/AGENTS.md; large files are chunked by token length. ContextSave records a description, project root, and relevant file globs as a resumable task context.
- A Claude Desktop user working in a local repository who wants the model to run tests, compile code, and poll a long-running command.
- An engineer who needs to join the terminal used by the model through the VS Code extension or `screen -x` to inspect output or provide interactive input.
- A maintainer changing a large source file who wants incremental search-and-replace edits after the model has read the file, with syntax-error feedback.
- A developer investigating an unfamiliar codebase who wants to request the read-only `architect` mode before any edits are made.
- A user handing off or resuming development work who needs ContextSave to preserve a task description and relevant files under a task ID.
What are this agent's strengths and limitations?
- BashCommand supports interactive input, arrow keys, interrupts, and ANSI escape sequences rather than only one-shot command execution.
- It supports multiple concurrent background commands alongside the main interactive shell and returns the current working directory after commands.
- FileEdit uses search/replace blocks with multi-match checks, whitespace-tolerant matching, and near-match feedback; edit and write flows report syntax errors.
- screen integration and the VS Code extension let a person join the exact terminal used by the model for observation, interruption, or input.
- ContextSave packages a task description and relevant files for checkpoints and knowledge transfer.
- The repository warns that it gives the model unfiltered shell and filesystem access; hallucinated or malicious instructions can run dangerous commands or make unintended changes.
- The documented Claude Desktop setup depends on uv and Python 3.12, while Windows support is limited to WSL.
- In code-writer mode, allowed-command lists are only an instruction to Claude and are not actually enforced; the documentation marks this as WIP.
- GPT relay support was removed in version 5 and later, and the supplied documentation has no current ChatGPT setup path.
- Shared-terminal access depends on screen being installed, and running a new command in that session can interrupt new LLM commands.
How do you install or deploy this agent?
On macOS or Linux, install uv with brew install uv. Add "wcgw": {"command":"uvx","args":["--python","3.12","wcgw@latest"]} under mcpServers in ~/Library/Application Support/Claude/claude_desktop_config.json, then restart Claude Desktop. On Windows, the documented path is WSL only: install uv and configure %APPDATA%\Claude\claude_desktop_config.json with wsl.exe and args ["uvx","--python","3.12","wcgw@latest"]. The supplied setup does not require an API key or other credential.
How do you use this agent?
After restarting Claude Desktop and waiting for its MCP icon, ask Claude to execute commands, read files, edit files, or run code. To force a shell, append --shell and a path such as /bin/bash to the uvx arguments. Request architect, code-writer, or the default wcgw mode as appropriate. To join a running terminal, use screen -ls to find the wcgw session and run screen -x <session-name>. For Docker, build with docker build -t wcgw https://github.com/rusiaaman/wcgw.git, then configure an MCP server that invokes Docker run.
How does this agent compare with similar options?
The documentation describes its search-and-replace editing as Aider-like and says its architect mode was inspired by Aider's architect mode; it does not provide a systematic feature or performance comparison.