wcgw Local Coding Terminal
An MCP server that lets chat clients run local shell commands, edit code, and share an interactive terminal.
- Source repo
- rusiaaman/wcgw
- Stars
- ★ 678
- Last updated
- 1mo ago
- License
- Apache-2.0
- Primary language
- Python
- FA score
- 45/100 · Major gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformClaude.ai
- Cost
- Free software; you pay for model usage
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- A Claude Desktop user working in a local repository who wants the model to run tests, compile code, and poll a long-running command.
- Not a fit if
- Teams that cannot allow an AI unfiltered shell and filesystem access
- Windows users who cannot or will not run WSL
- Users who want ChatGPT or other non-MCP clients, since relay support was removed
- Source review
- 45/100 · Major gaps 3 safety controls not found
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.
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.
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 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.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| wcgw Local Coding Terminal This agent | 45 · Major gaps | MCP serverFree + model costs | ★ 678 | 1mo ago | Python | Claude.ai |
| DevSpace | 50 · Major gaps | CLIFree + model costs | ★ 5.4k | 4d ago | TypeScript | ChatGPT |
| GitMCP: Live Documentation MCP Server for Any GitHub Project | 47 · Major gaps | Hosted serviceFree | ★ 8.5k | 6mo ago | TypeScript | ChatGPT · Claude Code · Claude.ai |
| Kode CLI | 44 · Major gaps | CLIFree + model costs | ★ 5.2k | 3d ago | TypeScript | OpenAI API · Claude API |
How does FollowAgents rate this agent?
Why each dimension lost points
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.
- Not found in source: confirmation before actingTurn on (or add) a confirmation step before it acts, and try it in a sandbox or test environment before real data.
- Not found in source: sensitive-data handlingUse dedicated, low-privilege, revocable API keys — never production credentials — and keep secrets out of logs.
- Not found in source: rollback or recovery pathBack up first, or work on a git branch or snapshot, so its changes can be undone.
- 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.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
5.6.6 5.6.6: MCP session isolation and concurrent tool calls
Release notes excerpt
What's Changed * Estimate tokens using len(chars)/3.5 instead of loading pretrained tokenizers by @rusiaaman in https://github.com/rusiaaman/wcgw/pull/111 * Add Streamable HTTP MCP transport by @brandonp2412 in https://github.com/rusiaaman/wcgw/pull/116 New Contributors * @brandonp2412 made their first contribution in https://github.com/rusiaaman/wcgw/pull/116 Full Changelog: https://github.com/rusiaaman/wcgw/compare/5.6.5...5.6.6View on GitHub ↗ -
5.6.5 5.6.5: git worktree context fix
-
5.6.4 5.6.4: build fix
FAQ
Does wcgw require an API key?
What can the model access?
Does it run directly on Windows?
wsl.exe to launch uvx.