wcgw Local Coding Terminal
An MCP server that lets chat clients run local shell commands, edit code, and share an interactive terminal.
Per-dimension scores and reasoning
Evidence: README explicitly warns about unrestricted shell access and default mode has no restrictions, but provides architect and code-writer modes to restrict file editing and commands. However, no user confirmation mechanism; tool calls execute commands directly. Data flow transparency is limited, only describing tool functions without explaining data flow. Sensitive data handling not mentioned. Dependencies have version ranges but no security audit. External effects are obvious (executing arbitrary commands), but no rollback mechanism. Source attribution partial: README mentions Aider modification but not full dependency sources. Deductions: lack of user confirmation, sensitive data handling, rollback mechanism.
Evidence: README and test files are consistent; tool list matches tests. Dependencies listed in pyproject.toml but availability not verified. Failure messages partially shown in tests (e.g., invalid bg_command_id), but overall error handling documentation insufficient. Deductions: failure message coverage incomplete.
Evidence: README targets Claude users, provides multiple use cases (shell, file editing, modes). Capability boundaries explained via modes, but command restrictions in code-writer mode not enforced. Trigger precision: tool parameters clear, but mode switching relies on LLM understanding. Environment fit: supports Mac/Linux/WSL, but not native Windows. Deductions: command restrictions not enforced.
Evidence: README structure clear, includes installation, usage, examples. Installation instructions detailed, including Mac/Linux/WSL. Naming stable, tool names consistent. Examples and FAQ partially present. Known limitations mentioned in README (e.g., unrestricted risk). License is Apache-2.0, complete. Version changelog listed in README but no separate CHANGELOG. Maintenance responsibility not explicit. Deductions: no separate CHANGELOG, maintenance responsibility unclear.
Evidence: Output usability: tools return structured output, e.g., bg_command_id. Marginal value: provides interactive shell and file editing, unique value. Cost-benefit: requires installing uv etc., but no performance data. Deductions: cost-benefit lacks data support.
Evidence: Some claims in README are supported by tests (e.g., bash parser tests), but no specific test results provided. Cross-source verification limited, only relying on README and tests. Fact/inference separation: README distinguishes feature descriptions and warnings, but some claims not clearly labeled. Deductions: lack of independent verification and clear fact/inference separation.
- This tool provides unrestricted shell access with no restrictions in default mode, posing risks of malicious use or dangerous commands due to AI hallucination.
- Command restrictions in code-writer mode are not enforced; they rely on LLM compliance and can be bypassed.
- No user confirmation mechanism; tool calls execute commands directly, potentially causing unintended changes.
- No rollback mechanism; destructive commands cannot be automatically undone.
- Sensitive data handling not addressed; lack of protection when handling passwords or other sensitive information.
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 -xto 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
architectmode 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.
FAQ
Does wcgw require an API key?
What can the model access?
Does it run directly on Windows?
wsl.exe to launch uvx.