# rusiaaman/wcgw architecture

> Architecture diagram of the GitHub repository rusiaaman/wcgw, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rusiaaman/wcgw
- Repository: https://github.com/rusiaaman/wcgw

## Overview

##### Project type and purpose
- This is an open‑source Python tool (“wcgw”) that exposes a Model Context Protocol (MCP) server and a lightweight relay server to let LLMs (Claude, ChatGPT) interact with your local shell and filesystem. It provides a CLI entrypoint, a library of “tools” (shell commands, file ops, context saving), and two server modes:
- An MCP server (for Claude) tightly integrated with shell and file‑editing tools.
- A relay server (for ChatGPT) that proxies between ChatGPT webhooks and the same tool set.
- The README confirms it is not a front‑end/backend webapp but a developer‑facing automation/runtime service.

##### File‑structure analysis
- Top‑level: Dockerfile, CI configs, pyproject.toml, README, LICENSE, static assets, tests, and two src modules:
- src/wcgw: core library
– client/: MCP server implementation, tool definitions (BashCommand, ReadFiles, FileEdit, ContextSave), state management (bash_state, memory), repo‑ops, encoder, prompts
– relay/: HTTP/WebSocket relay service (serve.py) and client stubs
- src/wcgw_cli: CLI wrapper that wires together the core library with OpenAI/Anthropic clients, parses arguments, and launches either the local relay or an interactive “local” mode
- tests/: unit tests covering parser, file ops, server behavior
- config: gpt_action_json_schema.json drives the schema for tool calls

##### Key README insights
- System runs in three “modes” (architect, code‑writer, wcgw) toggled at initialization.
- Tools are exposed via MCP calls: Initialize, BashCommand, ReadFiles, WriteIfEmpty, FileEdit, ContextSave.
- For ChatGPT, messages flow through a relay server; for Claude, directly via MCP.
- Emphasis on correctness (syntax checks, chunking large files, single shell instance).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User-facing Layer
    subgraph "CLI Layer"
        direction TB
        CLI1["CLI Entrypoint\n(src/wcgw_cli/__main__.py)"]:::user
        CLI2["CLI Module\n(src/wcgw_cli/cli.py)"]:::user
        CLI3["OpenAI Client\n(src/wcgw_cli/openai_client.py)"]:::user
        CLI4["Anthropic Client\n(src/wcgw_cli/anthropic_client.py)"]:::user
    end

    %% Protocol Endpoints
    subgraph "Protocol Servers" 
        direction TB
        MCP["MCP Server\n(src/wcgw/client/mcp_server/server.py)"]:::server
        Relay["Relay Server\n(src/wcgw/relay/serve.py)"]:::server
        RelayClient["Relay Client Stub\n(src/wcgw/relay/client.py)"]:::server
    end

    %% Core Engine
    subgraph "Tool Engine & State Manager"
        direction TB
        Gate["Mode Enforcement\n(architect/code-writer/wcgw)"]:::engine
        Tools["Tool Engine\n(src/wcgw/client/tools.py)"]:::engine
        FileDiff["Diff & Edit\n(src/wcgw/client/file_ops/diff_edit.py)"]:::engine
        SearchReplace["Search & Replace\n(src/wcgw/client/file_ops/search_replace.py)"]:::engine
        RepoTree["Display Tree\n(src/wcgw/client/repo_ops/display_tree.py)"]:::engine
        FileStats["File Stats\n(src/wcgw/client/repo_ops/file_stats.py)"]:::engine
        PathProb["Path Probability\n(src/wcgw/client/repo_ops/path_prob.py)"]:::engine
        RepoCtx["Repo Context\n(src/wcgw/client/repo_ops/repo_context.py)"]:::engine
        Prompts["Tool Prompts\n(src/wcgw/client/tool_prompts.py)"]:::engine
        BashState["Bash State\n(src/wcgw/client/bash_state/bash_state.py)"]:::engine
        Parser["Bash Parser\n(src/wcgw/client/bash_state/parser/bash_statement_parser.py)"]:::engine
        Memory["Memory\n(src/wcgw/client/memory.py)"]:::engine
    end

    %% OS Services
    subgraph "OS Services"
        direction TB
        Shell["Shell Process\n(cog)"]:::os
        FS["Filesystem\n(cylinder)"]:::os
    end

    %% External LLMs
    Claude["Claude (via MCP)"]:::external
    ChatGPT["ChatGPT (via HTTP/WebSocket)"]:::external

    %% Static & Config
    Schema["Action Schema\n(gpt_action_json_schema.json)"]:::utils
    Common["Common Utils\n(src/wcgw/client/common.py)"]:::utils
    Types["Type Definitions\n(src/wcgw/types_.py)"]:::utils

    %% Tests and Metadata (collapsed)
    subgraph "Tests & Config"
        direction TB
        PyProj["pyproject.toml"]:::meta
        DockerF["Dockerfile"]:::meta
        README["README.md"]:::meta
        LICENSE["LICENSE"]:::meta
        Tests["tests/"]:::meta
    end

    %% Connections
    CLI1 --> CLI2
    CLI2 -->|"config & mode"| Gate
    CLI2 -->|"init"| MCP
    CLI2 -->|"init"| Relay
    CLI2 -->|"send prompts"| CLI3
    CLI2 -->|"send prompts"| CLI4

    Claude -->|JSON-RPC| MCP
    ChatGPT -->|HTTP/WebSocket| Relay

    MCP -->|dispatch| Gate
    RelayClient -->|dispatch| Gate

    Gate -->|invoke| Tools
    Tools -->|calls| FileDiff
    Tools -->|calls| SearchReplace
    Tools -->|calls| RepoTree
    Tools -->|calls| FileStats
    Tools -->|calls| PathProb
    Tools -->|calls| RepoCtx
    Tools -->|uses| Prompts

    Gate -->|state access| BashState
    BashState -->|parse| Parser
    Gate -->|state access| Memory

    FileDiff -->|"stdout"| Shell
    Shell -->|output| Tools
    SearchReplace -->|I/O| FS
    RepoTree -->|I/O| FS
    FileStats -->|I/O| FS
    PathProb -->|I/O| FS
    RepoCtx -->|I/O| FS

    FS -->|file data| Tools

    Tools -->|response| MCP
    Tools -->|response| RelayClient

    %% Utilities & Schema linkage
    Gate -->|validate| Schema
    Tools -->|common routines| Common
    Tools -->|type checks| Types

    %% Click Events
    click CLI1 "https://github.com/rusiaaman/wcgw/blob/main/src/wcgw_cli/__main__.py"
    click CLI2 "https://github.com/rusiaaman/wcgw/blob/main/src/wcgw_cli/cli.py"
    click CLI3 "https://github.com/rusiaaman/wcgw/blob/main/src/wcgw_cli/openai_client.py"
    click CLI4 "https://github.com/rusiaaman/wcgw/blob/main/src/wcgw_cli/anthropic_client.py"
    click MCP "https://github.com/rusiaaman/wcgw/blob/main/src/wcgw/client/mcp_server/server.py"
    click Relay "https://github.com/rusiaaman/wcgw/blob/main/src/wcgw/relay/serve.py"
    click RelayClient "https://github.com/rusiaaman/wcgw/blob/main/src/wcgw/relay/client.py"
    click Tools "https://github.com/rusiaaman/wcgw/blob/main/src/wcgw/client/tools.py"
    click FileDiff "https://github.com/rusiaaman/wcgw/blob/main/src/wcgw/client/file_ops/diff_edit.py"
    click SearchReplace "https://github.com/rusiaaman/wcgw/blob/main/src/wcgw/client/file_ops/search_replace.py"
    click RepoTree "https://github.com/rusiaaman/wcgw/blob/main/src/wcgw/client/repo_ops/display_tree.py"
    click FileStats "https://github.com/rusiaaman/wcgw/blob/main/src/wcgw/client/repo_ops/file_stats.py"
    click PathProb "https://github.com/rusiaaman/wcgw/blob/main/src/wcgw/client/repo_ops/path_prob.py"
    click RepoCtx "https://github.com/rusiaaman/wcgw/blob/main/src/wcgw/client/repo_ops/repo_context.py"
    click Prompts "https://github.com/rusiaaman/wcgw/blob/main/src/wcgw/client/tool_prompts.py"
    click BashState "https://github.com/rusiaaman/wcgw/blob/main/src/wcgw/client/bash_state/bash_state.py"
    click Parser "https://github.com/rusiaaman/wcgw/blob/main/src/wcgw/client/bash_state/parser/bash_statement_parser.py"
    click Memory "https://github.com/rusiaaman/wcgw/blob/main/src/wcgw/client/memory.py"
    click Common "https://github.com/rusiaaman/wcgw/blob/main/src/wcgw/client/common.py"
    click Types "https://github.com/rusiaaman/wcgw/blob/main/src/wcgw/types_.py"

    %% Styling
    classDef user fill:#c6f5c6,stroke:#2d8f2d
    classDef server fill:#cce5ff,stroke:#3399ff
    classDef engine fill:#fff3b0,stroke:#ffcc00
    classDef os fill:#f0f0f0,stroke:#999999
    classDef external fill:#f9d5e5,stroke:#e91e63
    classDef utils fill:#e0e0e0,stroke:#555555
    classDef meta fill:#dddddd,stroke:#aaaaaa
```
