SuperAPI AI Directory
Partner with us中文AI newsFavorites
All toolsAI agentswcgw

wcgw

wcgw is a Shell and coding agent (MCP server) for MCP clients, designed to let chat applications write, build, and run code on your local machine. It provides tools tightly integrated with the shell, code editing, and file operations, and supports MCP-enabled clients such as Claude. Key features include: interactive command handling (supporting arrow keys, interrupts, and ANSI escape sequences), background multi-command execution, incremental editing of large files, syntax checking on edit, file protection (files must be read before editing), search-replace based editing, automatic loading of CLAUDE.md/AGENTS.md, three run modes (architect, code-writer, wcgw), and context save and resume. Before use, note: this server provides unfiltered access to the machine's shell and files, does not restrict the LLM from executing arbitrary commands or making unintended modifications, may be abused by attackers or trigger dangerous operations due to AI hallucinations, and should only be used if you fully understand and accept the risks.

Open website

About this tool

Purpose

wcgw is an MCP (Model Context Protocol) server that provides Shell and coding agent capabilities for chat applications such as Claude, enabling AI to write code, build projects, and run commands on the local machine.

Main capabilities

  • Create, execute, iterate: Lets Claude continuously run compilation checks until all errors are fixed, or poll long-running commands until completion.
  • Large file editing: Supports incremental editing of large files to avoid token limit issues, intelligently choosing small edits or large rewrites based on the percentage of change needed.
  • Edit syntax checking: If an edit has a syntax error, feeds it back to the LLM so it can redo it.
  • Interactive command handling: Supports interactive commands using arrow keys, interrupts, and ANSI escape sequences.
  • File protection: AI must read a file at least once before editing or rewriting it, avoiding accidental overwrites; when reading very large files, processes them in chunks to avoid context overflow; at initialization, returns the workspace directory structure (selecting important files based on .gitignore and statistical methods). File editing is based on search-replace; if there are multiple matches, it looks for the correct block based on the previous search block, otherwise it fails; supports whitespace-tolerant matching, and warns when indentation does not match; when there is no match, returns the closest match for the AI to correct. Uses Aider-like search-replace, with better performance than tool-call-based search-replace.
  • Shell optimization: Always returns the current working directory after any shell command, preventing the AI from getting lost; command polling exits after a quick timeout, and status checking waits tolerantly based on new output streams; supports multiple concurrent background commands.
  • Context saving: The ContextSave tool saves the task description and file contents in a single file and generates a task ID, which can be used to resume the task in a new conversation with "Resume <id>", or for knowledge transfer.
  • Mode switching: Supports three modes: architect (planning), code-writer (code editing and project building), and wcgw (unrestricted full authorization). code-writer mode can provide wildcard path restrictions on editable files.
  • Multiplexed terminal: Can attach to the terminal run by the AI via the VSCode extension or screen -x to view history, interrupt processes, or interact.
  • Automatic loading of CLAUDE.md/AGENTS.md: Automatically loads at initializationCLAUDE.md or AGENTS.md files in the project root as instructions; instructions in the global paths ~/.wcgw/CLAUDE.md or ~/.wcgw/AGENTS.md are also loaded. File names are case-sensitive, with CLAUDE.md taking priority.

Usage

Claude setup (using MCP)

  1. Install uv using Homebrew:brew install uv(Important: install using Homebrew to ensure uv is in a global location such as /usr/bin/).
  2. Create or update claude_desktop_config.json(Path: ~/Library/Application Support/Claude/claude_desktop_config.json).
  3. Restart the Claude app.

Optional: To force a specific shell (bash or zsh), add --shell parameter.

Optional: Streamable HTTP transport is available. wcgw_mcp uses stdio by default; for clients or gateways that are better suited to long-lived HTTP MCP endpoints, you can run the relevant command, and the MCP endpoint is http://127.0.0.1:8765/mcp/ . Binding to the loopback address keeps the server local while allowing HTTP-capable local gateways to multiplex requests without sharing a single stdio pipe.

Common troubleshooting

  • If you get a "uv ENOENT" error, make sure uv is installed, run in the terminal which uv, and replace "uv" in the configuration with its output.
  • If there are still problems, check uv tool run --python 3.12 wcgw run in the terminal with no output and no exit.
  • Try removing the ~/.cache/uv folder.
  • Try using uv version 0.6.0 (the version this tool was tested with).
  • Use npx @modelcontextprotocol/inspector@0.1.7 uv tool run --python 3.12 wcgw to debug the MCP server.

Windows support

This MCP server only works on Windows via WSL. After installing uv, update the configuration file %APPDATA%\Claude\claude_desktop_config.json. In the command prompt, run wsl uv --python 3.12 wcgw. If it says uv is not found, you need to find the uv installation path and replace it with the full path in the configuration.

Usage workflow

After successful configuration, you can ask Claude to execute shell commands, read files, edit files, run code, and so on. By attaching the "KnowledgeTransfer" prompt via the "Attach from MCP" button, you can perform task checkpoints or knowledge transfer, which calls the ContextSave tool to save the task description and all file contents to a single file and generate a task ID. In a new conversation, you can say "Resume '<id>'", and the AI will call Initialize to load the context. You can also directly open the generated file and share it with other AIs.

Attach to the terminal

If the screen command is installed, wcgw automatically runs in a screen instance. List the screen sessions and note the wcgw screen name (for example, 93358.wcgw.235521), use screen -x 93358.wcgw.235521 to attach. You can safely interrupt any running command and interact safely with the terminal (for example, entering a password or text; warning: running a new command will interrupt any new LLM command). Do not use exit or Ctrl-d to quit; instead use ctrl+a+d to detach safely without destroying the screen session. It is recommended to include the relevant configuration in ~/.screenrc for a better scrolling experience.

VSCode extension (optional)

Available from the Visual Studio Marketplace (itemName=AmanRusia.wcgw). Select text and press cmd+' and then enter an instruction, and it will switch to Claude and paste text containing the instruction, file path, workspace directory, and selected text.

Run the MCP server with Docker

First build the Docker image:docker build -t wcgw https://github.com/rusiaaman/wcgw.git, then update the configuration file.

Provided MCP Tools

Shell Operations

  • Initialize: Reset the shell and set up the workspace environment. Parameters: any_workspace_path (string), initial_files_to_read (string[]), mode_name ("wcgw"|"architect"|"code_writer"), task_id_to_resume (string), thread_id (string; empty only on the first call).
  • BashCommand: Execute shell commands and control timeouts. Parameters: command (string), wait_for_seconds (int, optional), thread_id (string); or parameters: send_text (string) or send_specials (["Enter"|"Key-up"|...]) or send_ascii (int[]), wait_for_seconds (int, optional).

File Operations

  • ReadFiles: Read the contents of one or more files. Parameters: file_paths (string[]), thread_id (string).
  • WriteIfEmpty: Create a new file or write to an empty file. Parameters: file_path (string), file_content (string).
  • FileEdit: Edit an existing file using search/replace blocks. Parameters: file_path (string), file_edit_using_search_replace_blocks (string).
  • ReadImage: Read an image file for display/processing. Parameters: file_path (string), thread_id (string).

Project Management

  • ContextSave: Save project context and files for knowledge transfer or task checkpoints for later resumption. Parameters: id (string), project_root_path (string), description (string), relevant_file_globs (string[]), thread_id (string).

All tools support absolute paths and have built-in protection against common errors.

Use Cases

  • Developers who want chat applications such as Claude to execute coding, build, and run tasks locally.
  • Users who need an AI agent to perform interactive shell operations and file editing on their local machine.
  • Scenarios that require task checkpoints or knowledge transfer between different AIs.

Limitations

  • This MCP server provides unfiltered access to the machine's shell and files, does not restrict the LLM from executing arbitrary commands or making unintended modifications, may be abused by attackers or trigger dangerous operations due to AI hallucinations, and should only be run if you fully understand and accept the risks.
  • This server only works on Windows via WSL.
  • The code-writer mode currently either allows all commands or allows none; if an allowed command list is provided, Claude is instructed to run only those commands, but there is no actual enforcement (WIP).

Related tools

Browse category