wcgw
Shell and coding agent for Claude and other MCP clients with tightly integrated shell and file-editing tools.
Add to your client
Copy the config for your MCP client and paste it into its config file.
uvx --python 3.12 wcgw@latestPaste into ~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"wcgw": {
"command": "uvx",
"args": [
"--python",
"3.12",
"wcgw@latest"
]
}
}
}Requires `uv` (the Python package runner). Install it from https://docs.astral.sh/uv/ if `uvx` is not found.
Step-by-step guides: Add to Claude Desktop · Add to Cursor · Add to Windsurf
Before you start
- uv (install via Homebrew on Mac/Linux: brew install uv)
- Python 3.12 (managed automatically by uvx)
- On Windows, only works under WSL
- Optional: screen, for attaching to the agent's working terminal
- Optional: the wcgw VS Code extension (AmanRusia.wcgw)
About wcgw
wcgw is an MCP server with tightly integrated shell and code-editing tools that lets chat applications code, build, and run on your local machine. It offers a fully interactive shell that both the user and agent can control, smart large-file editing with syntax checking, multiple operating modes (architect/code-writer/wcgw), and task checkpointing for knowledge transfer.
Tools & capabilities (7)
InitializeReset shell and set up workspace environment. Parameters: any_workspace_path, initial_files_to_read, mode_name ('wcgw'|'architect'|'code_writer'), task_id_to_resume.
BashCommandExecute shell commands with timeout control, or send interactive input (text, special keys like Enter/Key-up, or ASCII codes) to a running command. Parameters include command, send_text, send_specials, send_ascii, wait_for_seconds.
ReadFilesRead content from one or more files. Parameters: file_paths (string[]).
WriteIfEmptyCreate new files or write to empty files. Parameters: file_path, file_content.
FileEditEdit existing files using search/replace blocks. Parameters: file_path, file_edit_using_search_replace_blocks.
ReadImageRead image files for display/processing. Parameters: file_path.
ContextSaveSave project context and files for knowledge transfer or saving task checkpoints to be resumed later. Parameters: id, project_root_path, description, relevant_file_globs.
When to use it
- Give Claude a full local shell to build, run, and debug projects iteratively (e.g. keep running compiler checks until all errors are fixed)
- Smart editing of large files with syntax checking and search/replace, avoiding accidental overwrites
- Run interactive commands that need arrow keys, interrupts, or password input, with the option to attach to the same terminal the AI uses
- Plan first in 'architect' (read-only) mode, then switch to code-writing mode for execution
- Checkpoint a task with ContextSave and resume it in a new chat, or hand the saved context to another AI
Security notes
This MCP server provides unfiltered access to your machine's shell and files. It 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. Run only if you fully understand and accept the risks of running AI agents with no restrictions. 'architect' and 'code-writer' modes offer some restriction, but in code-writer mode the allowed-commands list is only an instruction to Claude and is not actually enforced (WIP).
wcgw FAQ
Does this restrict what the AI can do on my machine?
No. By default (wcgw mode) it provides unfiltered access to your shell and files with no restrictions. 'architect' mode is read-only and 'code-writer' mode limits editable paths, but in code-writer mode the allowed-commands list is only an instruction to Claude and is not actually enforced. Run only if you accept the risks.
Does it work on Windows?
Only under WSL. Configure claude_desktop_config.json to launch via wsl.exe with the uvx/uv command.
How do I attach to the terminal the AI is using?
If 'screen' is installed, wcgw runs on a screen instance automatically. List sessions with 'screen -ls', then attach with 'screen -x <session>'. Detach with Ctrl+a+d (not exit). The wcgw VS Code extension can also attach automatically when the workspace path matches.
Can I run it via Docker?
Yes. Build with 'docker build -t wcgw https://github.com/rusiaaman/wcgw.git', then configure the command as 'docker' with run/--rm/--mount args binding the directories you want to expose.
Alternatives to wcgw
Compare all alternatives →
Microsoft's official browser-automation MCP using Playwright's accessibility tree (no vision model).
Up-to-date, version-specific library documentation injected into your coding agent.
Code intelligence engine that indexes repos into a persistent knowledge graph for AI coding agents.