✨ 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 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. Multiline scripts and top-level command shorthand both work; NUL bytes are rejected before they reach the shell.
• Workspaces with three modes: wcgw (full access), architect (read-only), code_writer (allowlist of commands and write globs). The command allowlist is parsed with tree-sitter, so it checks every command on the line - pipelines, &&/||/;, command substitution, subshells - not just the first word, and can't be bypassed with ls && curl … | sh or ls $(rm …).
• A resilient PTY: a shell that won't return to a prompt (even after Ctrl-C) is auto-reset at the same cwd/mode, child processes are reaped on drop, and prompt detection is robust to a custom PS1. Opt into zsh with WINX_SHELL=zsh.
• File reads with WCGW-style line ranges (file.rs:10-40, file.rs:10-, file.rs:-40). Active files are tracked and prioritized in the repository context across calls.
• File writes and SEARCH/REPLACE edits that survive ambiguous matches, indentation drift, and the usual unicode quote-mismatches from LLMs. Writes are blocked when the file hasn't been read or the cached content is stale, the success message shows a compact diff of what changed, and recent edits are reversible with UndoEdit. MultiFileEdit applies a change across several files all-or-nothing (validated in memory first, so a failure on the last file leaves the earlier ones untouched).
• Tree-sitter code navigation via CodeMap: a token-budgeted symbol map of a file or the whole repo, or a definition/reference lookup for a symbol name - the semantic view that plain grep can't give you, across 11 languages.
• ContextSave for handing a task summary plus its files to the next session - including workspace context, active files, git status/diff, and terminal sharing for proper resumption. Resuming reopens the saved project root and token-caps the restored memory so it never overflows the context window.
• ReadImage so multimodal clients can pull screenshots, mockups, error PNGs, etc.
• Clean, token-aware shell output: cursor/ANSI noise from interactive programs (REPLs, progress bars) is rendered away through a terminal emulator, and mechanical repetition is collapsed losslessly (line [winx: ×N]) so build/install logs don't blow your context budget. Toggle the collapsing with WINX_NO_COMPRESS. When output still overflows the cap, the dropped head is streamed to a scratch file under .winx/scratch/ the agent can re-read, instead of being lost.
• Secret redaction on by default: provider API keys, JWTs, PEM private-key blocks and user:pass@ URLs are scrubbed from all tool output and saved memory before they reach the model (disable with WINX_NO_REDACT=1). An opt-in Landlock sandbox (WINX_SANDBOX=1, Linux) adds a kernel-enforced second layer that confines writes to the workspace and hides the home directory.
• Two transports: stdio for local clients, plus an optional token-gated Streamable HTTP server (winx serve --http) for remote MCP clients like ChatGPT - see Remote access.

MCP Tools

Winx advertises MCP 2025-11-25. CodeMap publishes an outputSchema for its existing structuredContent, while text content remains available for older clients. MCP Tasks are optional on BashCommand and apply only to a foreground command; include an explicit thread_id and do not combine the protocol-level task object with is_background=true. Task results are retained for the negotiated, bounded TTL and may be fetched repeatedly until expiry.

On local stdio connections, a client that advertises MCP Roots can initialize Winx from its first usable local file:// root. Winx never changes an active workspace after a Roots update. Automatic Roots bootstrap is disabled on the shared HTTP service so one remote client cannot silently select another client's workspace.

Search/Replace editing

Standard block syntax:

<<<<<<< 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
• retries once with \" unescaped when the model over-escapes quotes in SEARCH
• refuses edits that only matched after too much fuzzy fixup, and rejects blocks that match in too many places - so you re-read instead of corrupting the file
• anchor a block to a line number to pin one of several identical snippets - <<<<<<< SEARCH @42 (or a range @42-50); a stale anchor falls back to the normal search, so it never fails an otherwise-valid edit
• tells you on success which tolerances it had to apply (so you learn your SEARCH drifted), and on a miss how close the nearest match was, with ~ marking the lines that diverged

Install

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 mcp add winx -- winx-code-agent

{
  "mcpServers": {
    "winx": {
      "command": "winx-code-agent",
      "env": { "RUST_LOG": "winx_code_agent=info" }
    }
  }
}

{
  "mcpServers": {
    "winx": {
      "command": "winx-code-agent",
      "env": { "RUST_LOG": "winx_code_agent=info" }
    }
  }
}

codex mcp add winx -- winx-code-agent

[mcp_servers.winx]
command = "winx-code-agent"
env = { RUST_LOG = "winx_code_agent=info" }

{
  "mcpServers": {
    "winx": {
      "command": "winx-code-agent",
      "env": { "RUST_LOG": "winx_code_agent=info" }
    }
  }
}

{
  "servers": {
    "winx": {
      "type": "stdio",
      "command": "winx-code-agent"
    }
  }
}

{
  "context_servers": {
    "winx": {
      "source": "custom",
      "command": "winx-code-agent",
      "args": [],
      "env": { "RUST_LOG": "winx_code_agent=info" }
    }
  }
}

{
  "mcpServers": {
    "winx": {
      "command": "winx-code-agent",
      "env": { "RUST_LOG": "winx_code_agent=info" }
    }
  }
}

{
  "mcp": {
    "winx": {
      "type": "local",
      "command": ["winx-code-agent"],
      "enabled": true,
      "environment": { "RUST_LOG": "winx_code_agent=info" }
    }
  }
}

{
  "mcpServers": {
    "winx": {
      "command": "winx-code-agent",
      "args": [],
      "env": { "RUST_LOG": "winx_code_agent=info" }
    }
  }
}

{
  "mcpServers": {
    "winx": {
      "command": "winx-code-agent",
      "env": { "RUST_LOG": "winx_code_agent=info" }
    }
  }
}

mcpServers:
  - name: winx
    command: winx-code-agent
    env:
      RUST_LOG: winx_code_agent=info

{
  "mcpServers": {
    "winx": {
      "command": "winx-code-agent",
      "env": { "RUST_LOG": "winx_code_agent=info" }
    }
  }
}

{
  "winx": {
    "command": "winx-code-agent",
    "env": { "RUST_LOG": "winx_code_agent=info" }
  }
}

{
  "mcpServers": {
    "winx": {
      "type": "stdio",
      "command": "winx-code-agent"
    }
  }
}

{
  "mcpServers": {
    "winx": {
      "command": "winx-code-agent",
      "args": [],
      "env": { "RUST_LOG": "winx_code_agent=info" }
    }
  }
}

git clone https://github.com/gabrielmaialva33/winx-code-agent.git
cd winx-code-agent
cargo install --path .

cargo run --release

Check it's wired up

List MCP tools in your client. You should see nine entries: Initialize, BashCommand, ReadFiles, FileWriteOrEdit, MultiFileEdit, UndoEdit, ContextSave, ReadImage, CodeMap. Start with Initialize unless your local client exposes MCP Roots and Winx bootstraps from them; Winx tracks workspace + mode per thread.

Remote access (ChatGPT & other remote MCP clients)

By default Winx speaks MCP over stdio - the local transport every desktop client (Claude Desktop, Cursor, VS Code) uses. For clients that live in the cloud and can't reach your machine over stdio - like ChatGPT's developer-mode custom connectors - Winx can also serve MCP over Streamable HTTP:

winx serve --http --bind 127.0.0.1:8000 --token "$(openssl rand -hex 24)"

The MCP protocol is served at /mcp. Every request must carry the token in the Authorization: Bearer <token> header (header-only - a ?token= query parameter would leak the secret into proxy/tunnel access logs and browser history). Without a token the server refuses to start - serving a shell over the network without auth is remote code execution waiting to happen. The endpoint also caps request bodies (64 MB) and times out stuck requests (120 s).

Remote clients run in the cloud, so the endpoint has to be reachable over HTTPS - put a tunnel in front of the loopback listener and allow its hostname through the built-in DNS-rebinding guard:

# 1. tunnel first, to learn the public hostname
cloudflared tunnel --url http://localhost:8000
#    -> https://<random>.trycloudflare.com

# 2. start Winx, allowing that host
winx serve --http --bind 127.0.0.1:8000 \
     --token "$(openssl rand -hex 24)" \
     --allowed-host <random>.trycloudflare.com

In ChatGPT (Settings → Apps → Advanced → Developer mode), add a connector with:

• URL: https://<random>.trycloudflare.com/mcp
• Authentication: bearer / API-key token set to <your-token>, so the connector sends it as Authorization: Bearer <your-token> (the token is no longer accepted in the URL)

Remote clients are effectively stateless - they don't reuse the MCP session between tool calls - so the HTTP transport shares one shell session across all requests: the shell Initialize creates stays alive for the lifetime of the server, and later BashCommand calls find it. Reuse the same thread_id across calls.

Environment variables

All optional - Winx works out of the box without any of these.

Hacking on it

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.

Robustness is also fuzzed and model-checked:

• proptest feeds arbitrary/adversarial bytes into the live terminal emulator, the ANSI stripper, and the exit-code parser, asserting they never panic and stay within the viewport. (This is how we found - and worked around - a vt100 underflow on tiny grids and a reflow panic on column shrink that would otherwise crash the panic = "abort" release.)

• loom exhaustively model-checks the session pin counter (the lock-free guard that keeps an in-flight session from being LRU-evicted) across every thread interleaving. It's behind a feature so it doesn't perturb the normal build:

  cargo test --features loom --lib loom_
  

A note on security

By default this is a local (stdio) 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. The optional HTTP transport (--http) extends that reach to the network; see Remote access for the extra precautions it demands.

Two things are on by default to reduce the blast radius: secret redaction scrubs high-confidence credentials from all tool output and saved memory (WINX_NO_REDACT=1 to disable), and the PTY shell's whole process group is killed on teardown so background jobs it spawned don't leak.

If you want a tighter leash:

• architect mode disables writes and most commands;
• code_writer mode lets you allowlist commands and write globs;
• WINX_SANDBOX=1 enables an opt-in Landlock filesystem sandbox (Linux): writes are confined to the workspace plus /tmp, and the home directory is unreadable, so a manipulated agent can't read ~/.ssh/~/.aws or modify files outside the project.

SECURITY.md has the disclosure process and threat model.

License

MIT - Gabriel Maia (@gabrielmaialva33)