📌Overview

Purpose: This framework aims to empower chat applications to seamlessly code, build, and run tasks on local machines using models like Claude and ChatGPT.

Overview: The Shell and Coding agent integrates a server with Claude and ChatGPT, enabling interactive communication with shell environments across various operating systems (Linux, macOS, Windows on WSL). It provides code editing tools and command execution capabilities while ensuring safety and usability.

Key Features:

Interactive Command Handling: Allows the use of interactive commands with arrow keys and real-time polling for command statuses, enhancing user experience.
File Protection Mechanisms: Ensures safety in file editing by requiring prior reading of a file before edits, chunking to handle large files, and offering spacing-tolerant matching during search/replace operations.
Multi-Mode Operation: Users can switch between ‘architect’, ‘code-writer’, and unrestricted ‘wcgw’ modes, allowing tailored functionality based on specific tasks.
Task Context Management: Features a 'ContextSave' tool that enables saving and resuming project contexts to facilitate knowledge transfer or checkpointing tasks.
Shell Optimization: Only one command can run at a time, providing simplicity in management, with real-time updates and an always-available current working directory.
Incremental File Editing: Efficiently edits large files by determining necessary changes, avoiding token limit issues, and providing feedback on syntax errors during modifications.

Shell and Coding Agent for Claude and ChatGPT

Empowering chat applications to code, build, and run on your local machine.

Claude: MCP server with tightly integrated shell and code editing tools.
ChatGPT: Allows custom GPT to talk to your shell via a relay server (Linux, macOS, Windows on WSL).

⚠️ Warning: Do not allow BashCommand tool without reviewing the command, as it may result in data loss.

Demo

Demo available within the project (no image included here).

Updates

24 Mar 2025: Improved writing and editing experience for sonnet 3.7; CLAUDE.md loads automatically.
16 Feb 2025: You can now attach to the working terminal that the AI uses (see "Attach to terminal" section).
15 Jan 2025: Introduced modes: architect, code-writer, and full wcgw mode.
8 Jan 2025: Added context saving tool for saving relevant file paths with description in a single file for task checkpoint or knowledge transfer.
29 Dec 2024: Syntax checking on file writing/stable edits; improved large file handling and initialize tool utility.
9 Dec 2024: Vscode extension to paste context on Claude app available.

Highlights

Create, Execute, Iterate: Ask Claude to run compiler checks until errors are fixed or monitor long-running commands.
Large file edits: Supports incremental edits to avoid token limit issues, choosing the edit type based on change percentage.
Syntax checking: Provides feedback to the LLM on syntax errors to enable redo.
Interactive command handling: Supports interactive commands using arrow keys, interrupt, and ANSI escape sequences.

File Protections

AI must read a file once before editing it to avoid accidental overwrites.
Large files are chunked based on token length to avoid context overload.
On initialization, workspace directory structure is analyzed with .gitignore and a statistical method to select important files.
File edits use spacing-tolerant matching with warnings for indentation issues and fallback on closest match for correction.
Uses performant Aider-like search and replace instead of tool call-based replacements.

Shell Optimizations

Only one command runs at a time, avoiding rogue processes; single shell instance maintained.
Current working directory is always returned after commands to keep AI context accurate.
Command polling exits quickly to avoid slow feedback but uses wait tolerance on fresh output streaming for good interaction.

Saving Repo Context

The "ContextSave" tool saves detailed task checkpoints in one file; tasks can be resumed later or shared with another AI for knowledge transfer.

Modes

Architect mode: Planning and repo investigation with read-only commands.
Code-writer mode: Code editing with path/glob restrictions and specific allowed commands.
wcgw mode: Default mode; full authorization and no restrictions.

Multiplex Terminal Support

Using screen -x you can attach to the terminal the AI uses to interact with sessions, inspect history, and interrupt processes.

Top Use Cases

Solve programming problems, run test cases, and fix issues in temporary directories.
Search for code behavior instances within repositories.
Clone repositories, understand projects, set up environments, and build.
Create web applications with Golang, HTMX, Tailwind, and validate via browser.
Edit or update large files efficiently.
Develop features in separate branches and use GitHub CLI to create PRs.
Debug failing commands in specific directories.
Run commands in virtual environments.
Build and test Android apps using CLI tools and emulators.
Fix all mypy issues in a repository.
Manage multiple servers using screen, monitor logs, and handle build processes.
Generate repo-wide unittest cases, iterate through files, run tests after updates, and preserve original code.

Claude Setup (Using MCP)

macOS and Linux

Install uv via Homebrew:
```
brew install uv
```
Important: Use Homebrew to install uv or ensure uv is globally accessible (e.g., /usr/bin/).

Create or update claude_desktop_config.json at:
~/Library/Application Support/Claude/claude_desktop_config.json with:

{
  "mcpServers": {
    "wcgw": {
      "command": "uv",
      "args": [
        "tool",
        "run",
        "--from",
        "wcgw@latest",
        "--python",
        "3.12",
        "wcgw_mcp"
      ]
    }
  }
}

Restart the Claude app.

Troubleshooting:

If you encounter "uv ENOENT", confirm uv is installed and replace "uv" in config with the full path from which uv.
Ensure uv tool run --from wcgw@latest --python 3.12 wcgw_mcp runs without output or exit.
Remove ~/.cache/uv folder if issues persist.
Use uv version 0.6.0 for compatibility.

Debug MCP server using:

npx @modelcontextprotocol/inspector@0.1.7 uv tool run --from wcgw@latest --python 3.12 wcgw_mcp

Windows on WSL

This MCP server works only on WSL for Windows.

Install uv as per instructions: https://docs.astral.sh/uv/getting-started/installation/

Update claude_desktop_config.json at %APPDATA%\Claude\claude_desktop_config.json with:

{
  "mcpServers": {
    "wcgw": {
      "command": "wsl.exe",
      "args": [
        "uv",
        "tool",
        "run",
        "--from",
        "wcgw@latest",
        "--python",
        "3.12",
        "wcgw_mcp"
      ]
    }
  }
}

Usage

After setup, Claude can execute shell commands, read files, edit files, run your code, etc.

Task Checkpoint or Knowledge Transfer

Attach a "KnowledgeTransfer" prompt using the "Attach from MCP" button.
Running this calls the "ContextSave" tool, saving task descriptions and file contents in a single file with a task ID.
To resume, start a new chat with:
```
Resume '<task id>'
```
Alternatively, share the saved file with another AI for assistance.

Modes

There are three built-in modes you can ask Claude to use:

Mode	Description	Allows	Denies	Invoke Prompt
Architect	Investigate and understand your repo; read-only commands.	Read-only commands	FileEdit and Write tool	Run in mode='architect'
Code-writer	Code writing and development with path/glob restrictions.	Specified path globs and commands	Edits outside specified paths	Run in code writer mode
wcgw	Default mode with full authorization and no restrictions.	Everything	Nothing	No prompt or "Run in wcgw mode"

Note: In code-writer mode, command restrictions are currently instructional only (WIP).

Attach to the Working Terminal

If screen is installed, wcgw runs in a screen session automatically.

List sessions:
```
screen -ls
```
Attach to the wcgw session named like 93358.wcgw.235521:
```
screen -x 93358.wcgw.235521
```
You can safely interrupt running commands and interact with terminal.
Avoid exiting the session with exit or Ctrl-D. Instead, detach safely with Ctrl-A D.

Optional: VS Code Extension

Available via Visual Studio Marketplace.

Select text, press Cmd+', enter instructions to switch app to Claude with relevant context.

ChatGPT Setup

Read the setup guide at:
https://github.com/rusiaaman/wcgw/blob/main/openai.md

Using MCP Server Over Docker

Build Docker image:

docker build -t wcgw https://github.com/rusiaaman/wcgw.git

Update claude_desktop_config.json (for example, macOS):

{
  "mcpServers": {
    "filesystem": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--mount",
        "type=bind,src=/Users/username/Desktop,dst=/workspace/Desktop",
        "wcgw"
      ]
    }
  }
}

Optional: Local Shell Access with OpenAI or Anthropic API Key

OpenAI

Set environment variables: OPENAI_API_KEY and OPENAI_ORG_ID.

Run:

uvx --from wcgw@latest wcgw_local --limit 0.1

You can write messages directly or press Enter to open vim for multiline input.

Anthropic

Set environment variable: ANTHROPIC_API_KEY.

Run:

uvx --from wcgw@latest wcgw_local --claude

Supports direct messaging or multiline editing in vim.

Tools

The MCP server provides the following tools with parameters:

Shell Operations

Initialize: Reset shell and set up workspace environment
Parameters:
- any_workspace_path (string)
- initial_files_to_read (string[])
- mode_name ("wcgw" | "architect" | "code_writer")
- task_id_to_resume (string)
BashCommand: Execute shell commands with optional timeout
Parameters:
- command (string)
- wait_for_seconds (int, optional)
- send_text (string) or
- send_specials (array of key commands like "Enter", "Key-up", etc.) or
- send_ascii (int[])
- wait_for_seconds (int, optional)

File Operations

ReadFiles: Read content from files
Parameters: file_paths (string[])
WriteIfEmpty: Create or write to empty files
Parameters:
- file_path (string)
- file_content (string)
FileEdit: Edit files via search/replace blocks
Parameters:
- file_path (string)
- file_edit_using_search_replace_blocks (string)
ReadImage: Read images for display or processing
Parameters: file_path (string)

Project Management

ContextSave: Save project context for knowledge transfer or task checkpointing
Parameters:
- id (string)
- project_root_path (string)
- description (string)
- relevant_file_globs (string[])

All tools accept absolute paths and implement protections against common errors. For detailed protocol info, see the MCP specification.

wcgw

📌Overview

Shell and Coding Agent for Claude and ChatGPT

Demo

Updates

Highlights

File Protections

Shell Optimizations

Saving Repo Context

Modes

Multiplex Terminal Support

Top Use Cases

Claude Setup (Using MCP)

macOS and Linux

Troubleshooting:

Windows on WSL

Usage

Task Checkpoint or Knowledge Transfer

Modes

Attach to the Working Terminal

Optional: VS Code Extension

ChatGPT Setup

Using MCP Server Over Docker

Optional: Local Shell Access with OpenAI or Anthropic API Key

OpenAI

Anthropic

Tools

Shell Operations

File Operations

Project Management

End of Document