rusiaaman/wcgw

What it solves

wcgw provides a way for AI agents (specifically those using the Model Context Protocol, or MCP) to interact directly with a local machine's shell and file system. It bridges the gap between a chat interface and a local development environment, allowing an LLM to write, build, and run code autonomously while providing the user with visibility and control over the process.

How it works

It operates as an MCP server that exposes a set of tools to an LLM. These tools allow the agent to execute bash commands, read and edit files using search-and-replace blocks, and manage project context. To ensure a better developer experience, it integrates with a multiplex terminal (via screen) and an optional VS Code extension, allowing users to attach to the same terminal the AI is using to monitor or intervene in real-time.

Who it’s for

Developers who use MCP-compatible clients (like Claude Desktop) and want an AI agent that can act as a fully-fledged coding assistant capable of executing commands and managing files on their local machine.

Highlights

• Interactive Shell: Supports interactive commands, including arrow keys, interrupts, and ANSI escape sequences.
• Large File Handling: Uses incremental edits and chunking to avoid token limits and prevent accidental overwrites.
• Syntax Validation: Automatically reports syntax errors back to the LLM after file edits so the agent can correct them.
• Operational Modes: Includes 'Architect' (read-only planning), 'Code-writer' (restricted editing), and 'wcgw' (full access) modes.
• Context Checkpointing: The ContextSave tool allows agents to save the state of a task to a file, which can be resumed in a new chat or shared with another AI.
• Terminal Attachment: Users can attach to the AI's active terminal session using screen -x or a VS Code extension.