https://github.com/gabrielmaialva33/winx-code-agent

✨ A high-performance code agent written in Rust, combining the best features of WCGW for maximum efficiency and semantic capabilities. 🦀
https://github.com/gabrielmaialva33/winx-code-agent

autonomous code-agent computer control execution llm-agent llm-code mcp rust serena shell vibe-coding vibecoding wcgw

Last synced: 9 days ago
JSON representation

✨ A high-performance code agent written in Rust, combining the best features of WCGW for maximum efficiency and semantic capabilities. 🦀

• Host: GitHub
• URL: https://github.com/gabrielmaialva33/winx-code-agent
• Owner: gabrielmaialva33
• License: mit
• Created: 2025-04-17T04:07:28.000Z (about 1 year ago)
• Default Branch: main
• Last Pushed: 2026-05-23T16:09:54.000Z (9 days ago)
• Last Synced: 2026-05-23T16:28:25.139Z (9 days ago)
• Topics: autonomous, code-agent, computer, control, execution, llm-agent, llm-code, mcp, rust, serena, shell, vibe-coding, vibecoding, wcgw
• Language: Rust
• Homepage: https://crates.io/crates/winx-code-agent
• Size: 2.4 MB
• Stars: 27
• Watchers: 0
• Forks: 8
• Open Issues: 3
• Metadata Files:
  • Readme: README.md
  • Contributing: CONTRIBUTING.md
  • License: LICENSE
  • Code of conduct: CODE_OF_CONDUCT.md
  • Security: SECURITY.md

Awesome Lists containing this project

• awesome-mcp - gabrielmaialva33/winx-code-agent - powered code agent for development ☆`23` (AI Agents / Code Assistants)
• awesome-mcp-servers - gabrielmaialva33/winx-code-agent - یک پیاده‌سازی مجدد Rust با کارایی بالا از WCGW برای عامل‌های کد، که اجرای shell و قابلیت‌های پیشرفته مدیریت فایل را برای LLMها از طریق MCP فراهم می‌کند. (پیاده‌سازی‌های سرور / 🤖 <a name="coding-agents"></a>عامل‌های کدنویسی)
• awesome-mcp-servers - **gabrielmaialva33/winx-code-agent 🦀 🏠** - A high-performance Rust reimplementation of WCGW for code agents, providing shell execution and advanced file management capabilities for LLMs via MCP. `file` `http` `ai` `llm` `git` (📦 Other)

README

          


  



# ✨ Winx - MCP Server for Shell & Coding Agents ✨



  🦀 Native Rust implementation inspired by WCGW, built for local code-agent workflows





  

  

  

  





  A local MCP server you can hand to a coding agent and stop worrying about the shell.



Winx is the MCP server I wanted while running Claude, Codex, and friends against real repos: one process that handles

the shell, file IO, and PTY-backed interactive sessions, written in Rust so it doesn't fight you on stdio.

It started as a Rust port of [WCGW](https://github.com/rusiaaman/wcgw) but isn't a Python wrapper. Everything runs on a

real PTY (via `portable-pty`), `cd` actually sticks, `Ctrl+C` actually interrupts, and background shells survive

long-running TUIs without leaking output buffers into your token budget.

## What you get

- A stateful bash session per thread with proper PTY semantics — foreground, background, status checks, text input,

  Enter/Ctrl-C/Ctrl-D, raw ASCII.

- Workspaces with three modes: `wcgw` (full access), `architect` (read-only), `code_writer` (allowlist of commands and

  write globs).

- File reads with WCGW-style line ranges (`file.rs:10-40`, `file.rs:10-`, `file.rs:-40`).

- File writes and SEARCH/REPLACE edits that survive ambiguous matches, indentation drift, and the usual unicode

  quote-mismatches from LLMs.

- `ContextSave` for handing a task summary plus its files to the next session.

- `ReadImage` so multimodal clients can pull screenshots, mockups, error PNGs, etc.

## MCP Tools

| Tool              | What it does                                                                                                                                                   |

|-------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------|

| `Initialize`      | Boots the workspace, picks the mode, hands you a `thread_id`. Call this first or everything else errors out.                                                   |

| `BashCommand`     | Runs commands, polls long-running ones, sends Enter/Ctrl-C, drives TUIs. Supports `is_background`, `status_check`, `send_text`, `send_specials`, `send_ascii`. |

| `ReadFiles`       | One or many files, with line numbers. Append `:10-40` to a path for a range.                                                                                   |

| `FileWriteOrEdit` | Full overwrites or SEARCH/REPLACE blocks. Refuses to write a file you haven't read yet.                                                                        |

| `ContextSave`     | Dumps task description + file globs into a single text file for resume/handoff.                                                                                |

| `ReadImage`       | Base64 + MIME, for clients that can render images.                                                                                                             |

## Search/Replace editing

Standard block syntax:

```text

<<<<<<< SEARCH

old content

=======

new content

>>>>>>> REPLACE

```

Things the matcher forgives so you don't have to babysit the model:

- atomic: ambiguous or missing matches abort without touching the file

- adjusts replacement indentation when the LLM gets the leading whitespace wrong

- strips `ReadFiles` line numbers if they leak into a SEARCH block

- normalizes the usual "smart quote" / em-dash / ellipsis substitutions

- uses neighboring blocks to disambiguate when the same snippet appears twice

- single-line substring edits work — you don't need the whole line in SEARCH

## Install

```bash

cargo install winx-code-agent

```

Binary lands in `~/.cargo/bin` — every config snippet below assumes that's on `$PATH`. If your MCP client launches with

a sterile env, swap `winx-code-agent` for the absolute path (`which winx-code-agent`).

Needs Rust 1.75+, Linux/macOS/WSL2, and a real terminal (any modern one — Winx spawns its own PTY).

Claude Code (CLI)

One-liner via the CLI (stdio is the default transport):

```bash

claude mcp add winx -- winx-code-agent

```

Or drop a `.mcp.json` in your project root:

```json

{

  "mcpServers": {

    "winx": {

      "command": "winx-code-agent",

      "env": { "RUST_LOG": "winx_code_agent=info" }

    }

  }

}

```

Claude Desktop

Add to your config file (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, `%APPDATA%\Claude\claude_desktop_config.json` on Windows):

```json

{

  "mcpServers": {

    "winx": {

      "command": "winx-code-agent",

      "env": { "RUST_LOG": "winx_code_agent=info" }

    }

  }

}

```

Restart Claude Desktop after saving.

Codex (OpenAI CLI)

One-liner:

```bash

codex mcp add winx -- winx-code-agent

```

Or edit `~/.codex/config.toml`:

```toml

[mcp_servers.winx]

command = "winx-code-agent"

env = { RUST_LOG = "winx_code_agent=info" }

```

Cursor

Add to `~/.cursor/mcp.json` (or `.cursor/mcp.json` for project-local):

```json

{

  "mcpServers": {

    "winx": {

      "command": "winx-code-agent",

      "env": { "RUST_LOG": "winx_code_agent=info" }

    }

  }

}

```

VS Code (Copilot Chat / MCP)

Add to `.vscode/mcp.json`:

```json

{

  "servers": {

    "winx": {

      "type": "stdio",

      "command": "winx-code-agent"

    }

  }

}

```

Zed

Add to your Zed settings (`~/.config/zed/settings.json`):

```json

{

  "context_servers": {

    "winx": {

      "source": "custom",

      "command": "winx-code-agent",

      "args": [],

      "env": { "RUST_LOG": "winx_code_agent=info" }

    }

  }

}

```

Windsurf

Add to `~/.codeium/windsurf/mcp_config.json`:

```json

{

  "mcpServers": {

    "winx": {

      "command": "winx-code-agent",

      "env": { "RUST_LOG": "winx_code_agent=info" }

    }

  }

}

```

OpenCode

Add to `opencode.json`:

```json

{

  "mcp": {

    "winx": {

      "type": "local",

      "command": ["winx-code-agent"],

      "enabled": true,

      "environment": { "RUST_LOG": "winx_code_agent=info" }

    }

  }

}

```

Gemini CLI

Add to `~/.gemini/settings.json`:

```json

{

  "mcpServers": {

    "winx": {

      "command": "winx-code-agent",

      "args": [],

      "env": { "RUST_LOG": "winx_code_agent=info" }

    }

  }

}

```

agy (Google Antigravity CLI)

`agy` is Google's new Gemini-powered CLI (Go binary, usually at `~/.local/bin/agy`). No `mcp add` subcommand yet — it

reads MCP servers from JSON.

Edit `~/.gemini/config/mcp_config.json` (also `~/.gemini/antigravity/mcp_config.json` if you run the Antigravity IDE

alongside):

```json

{

  "mcpServers": {

    "winx": {

      "command": "winx-code-agent",

      "env": { "RUST_LOG": "winx_code_agent=info" }

    }

  }

}

```

If `winx-code-agent` is not on the agy process `$PATH`, swap `command` for the absolute path (`~/.cargo/bin/winx-code-agent` after `cargo install winx-code-agent`).

Continue.dev

Add to your `~/.continue/config.yaml`:

```yaml

mcpServers:

  - name: winx

    command: winx-code-agent

    env:

      RUST_LOG: winx_code_agent=info

```

Kiro

Add to `~/.kiro/settings/mcp.json`:

```json

{

  "mcpServers": {

    "winx": {

      "command": "winx-code-agent",

      "env": { "RUST_LOG": "winx_code_agent=info" }

    }

  }

}

```

Warp

**Settings → MCP Servers → Add MCP Server**:

```json

{

  "winx": {

    "command": "winx-code-agent",

    "env": { "RUST_LOG": "winx_code_agent=info" }

  }

}

```

Roo Code

Add to your Roo Code MCP config:

```json

{

  "mcpServers": {

    "winx": {

      "type": "stdio",

      "command": "winx-code-agent"

    }

  }

}

```

Other clients (generic stdio)

Any client that speaks stdio MCP works with this shape:

```json

{

  "mcpServers": {

    "winx": {

      "command": "winx-code-agent",

      "args": [],

      "env": { "RUST_LOG": "winx_code_agent=info" }

    }

  }

}

```

If your client launches Winx with an empty `$PATH`, swap `command` for the absolute path (

`~/.cargo/bin/winx-code-agent`).

Build from source

For unreleased changes or a custom build:

```bash

git clone https://github.com/gabrielmaialva33/winx-code-agent.git

cd winx-code-agent

cargo install --path .

```

Or run it without installing:

```bash

cargo run --release

```

### Check it's wired up

List MCP tools in your client. You should see six entries: `Initialize`, `BashCommand`, `ReadFiles`, `FileWriteOrEdit`,

`ContextSave`, `ReadImage`. The first call always has to be `Initialize` — Winx tracks workspace + mode per thread.

## Hacking on it

```bash

cargo fmt --all

cargo clippy --all-targets --all-features -- -D warnings

cargo test --all-features

```

CI runs the same three. If you touch `src/state/pty.rs` or anything in `src/tools/bash_command.rs`, the regression suite

at `tests/bash_pty_regression_test.rs` is what protects against the usual TUI/PTY foot-guns — run it first.

## A note on security

This is a local MCP server. Anything connected to it can read files, edit files, and run shell commands inside the

workspace — same blast radius as letting the model into your terminal.

If you want a tighter leash:

- `architect` mode disables writes and most commands;

- `code_writer` mode lets you allowlist commands and write globs.

[SECURITY.md](SECURITY.md) has the disclosure process and threat model.

## License

MIT - Gabriel Maia ([@gabrielmaialva33](https://github.com/gabrielmaialva33))