<p align="center">
<img src=".github/assets/fairy.png" alt="Winx fairy mascot" width="160" />
</p>
# ✨ Winx - MCP Server for Shell & Coding Agents ✨
<p align="center">
<strong>🦀 Native Rust implementation inspired by WCGW, built for local code-agent workflows</strong>
</p>
<p align="center">
<img src="https://img.shields.io/badge/language-Rust-orange?style=flat&logo=rust" alt="Language" />
<img src="https://img.shields.io/badge/license-MIT-blue?style=flat" alt="License" />
<img src="https://img.shields.io/badge/MCP-compatible-purple?style=flat" alt="MCP" />
<img src="https://img.shields.io/badge/transport-stdio-2f855a?style=flat" alt="stdio transport" />
</p>
<p align="center">
<em>A local MCP server you can hand to a coding agent and stop worrying about the shell.</em>
</p>
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
| `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).
<details>
<summary><b>Claude Code (CLI)</b></summary>
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" }
}
}
}
```
</details>
<details>
<summary><b>Claude Desktop</b></summary>
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.
</details>
<details>
<summary><b>Codex (OpenAI CLI)</b></summary>
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" }
```
</details>
<details>
<summary><b>Cursor</b></summary>
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" }
}
}
}
```
</details>
<details>
<summary><b>VS Code (Copilot Chat / MCP)</b></summary>
Add to `.vscode/mcp.json`:
```json
{
"servers": {
"winx": {
"type": "stdio",
"command": "winx-code-agent"
}
}
}
```
</details>
<details>
<summary><b>Zed</b></summary>
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" }
}
}
}
```
</details>
<details>
<summary><b>Windsurf</b></summary>
Add to `~/.codeium/windsurf/mcp_config.json`:
```json
{
"mcpServers": {
"winx": {
"command": "winx-code-agent",
"env": { "RUST_LOG": "winx_code_agent=info" }
}
}
}
```
</details>
<details>
<summary><b>OpenCode</b></summary>
Add to `opencode.json`:
```json
{
"mcp": {
"winx": {
"type": "local",
"command": ["winx-code-agent"],
"enabled": true,
"environment": { "RUST_LOG": "winx_code_agent=info" }
}
}
}
```
</details>
<details>
<summary><b>Gemini CLI</b></summary>
Add to `~/.gemini/settings.json`:
```json
{
"mcpServers": {
"winx": {
"command": "winx-code-agent",
"args": [],
"env": { "RUST_LOG": "winx_code_agent=info" }
}
}
}
```
</details>
<details>
<summary><b>agy (Google Antigravity CLI)</b></summary>
`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`).
</details>
<details>
<summary><b>Continue.dev</b></summary>
Add to your `~/.continue/config.yaml`:
```yaml
mcpServers:
- name: winx
command: winx-code-agent
env:
RUST_LOG: winx_code_agent=info
```
</details>
<details>
<summary><b>Kiro</b></summary>
Add to `~/.kiro/settings/mcp.json`:
```json
{
"mcpServers": {
"winx": {
"command": "winx-code-agent",
"env": { "RUST_LOG": "winx_code_agent=info" }
}
}
}
```
</details>
<details>
<summary><b>Warp</b></summary>
**Settings → MCP Servers → Add MCP Server**:
```json
{
"winx": {
"command": "winx-code-agent",
"env": { "RUST_LOG": "winx_code_agent=info" }
}
}
```
</details>
<details>
<summary><b>Roo Code</b></summary>
Add to your Roo Code MCP config:
```json
{
"mcpServers": {
"winx": {
"type": "stdio",
"command": "winx-code-agent"
}
}
}
```
</details>
<details>
<summary><b>Other clients (generic stdio)</b></summary>
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`).
</details>
<details>
<summary><b>Build from source</b></summary>
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
```
</details>
### 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))