Winx Code Agent
Native Rust MCP server giving coding agents a PTY-backed shell, file IO, and tree-sitter code navigation.
Add to your client
Copy the config for your MCP client and paste it into its config file.
cargo install winx-code-agentPaste into ~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"winx-code-agent": {
"command": "winx-code-agent",
"args": [],
"env": {
"RUST_LOG": "winx_code_agent=info"
}
}
}
}Step-by-step guides: Add to Claude Desktop · Add to Cursor · Add to Windsurf
Before you start
- Rust 1.75+ (via `cargo install winx-code-agent`)
- Linux, macOS, or WSL2
- A real terminal (Winx spawns its own PTY)
About Winx Code Agent
Winx is a native Rust MCP server that gives coding agents one process for the shell, file IO, and PTY-backed interactive sessions. Originally a Rust port of WCGW, it runs everything on a real PTY so cd, Ctrl-C, and background shells behave correctly, with token-aware output cleanup, three workspace permission modes, tree-sitter code navigation, forgiving SEARCH/REPLACE editing, and secret redaction on by default. It supports both local stdio and an optional token-gated Streamable HTTP transport for remote clients.
Tools & capabilities (9)
InitializeBoots the workspace, picks the mode (wcgw/architect/code_writer), and hands back a thread_id. Must be called first or everything else errors out. With no workspace path it spins up a scratch playground; passing task_id_to_resume reopens a saved project root.
BashCommandRuns commands, polls long-running ones, and drives TUIs. Supports is_background, status_check, send_text, send_specials, send_ascii, allow_multi, plus screen (a point-in-time TUI frame, with diff:true for changed lines only) and wait_for_turn. Reports the real exit code parsed from the prompt marker.
ReadFilesReads one or many files with line numbers; append :10-40 (or :10- / :-40) to a path for a range. When the token budget is hit it tells you the exact line and file:N-M syntax to resume from instead of dropping the tail.
FileWriteOrEditFull overwrites or forgiving SEARCH/REPLACE blocks (with optional @start-end line anchors). Validates read coverage and freshness, reports fuzzy tolerances applied, runs a tree-sitter syntax check across 18+ languages, and returns a compact diff of what changed.
MultiFileEditEdits several files all-or-nothing: every file's edit is validated and computed in memory first, and only if all succeed is anything written, so a failed SEARCH in the last file leaves the earlier ones untouched.
UndoEditReverts a file to its content before the last FileWriteOrEdit/MultiFileEdit this session (per-file, last ~10 edits kept in memory). Refused if the file changed on disk since the edit; a brand-new file's creation isn't undoable.
ContextSaveDumps a task description plus file globs into a single text file with workspace context, active files, and git status/diff for clean handoff and task resumption.
ReadImageReturns a native MCP image content block (not base64 text) so multimodal models actually see the image. Confined to the workspace and size-capped.
CodeMapTree-sitter code navigation with two operations: 'outline' gives a token-budgeted symbol map of a file or a relevance-ranked repo map (11 languages); 'references' shows where a name is defined and used across the repo, counting only real identifier occurrences (never inside strings/comments).
When to use it
- Giving a coding agent (Claude, Codex, Cursor, etc.) a reliable shell that handles cd, Ctrl-C, and interactive TUIs without leaking output into the token budget
- Editing code with forgiving SEARCH/REPLACE blocks that survive indentation drift and smart-quote substitutions, with tree-sitter syntax checks and per-session undo
- Restricting an agent to read-only (architect) or an allowlist of commands and write globs (code_writer) for safer autonomous runs
- Navigating a repo semantically with a tree-sitter symbol map and definition/reference lookup
- Saving and resuming a task's context (workspace, active files, git diff) across agent sessions
- Exposing the shell to a remote MCP client like ChatGPT over token-gated Streamable HTTP behind a tunnel
Security notes
A local stdio MCP server with full shell/file access inside the workspace - same blast radius as letting the model into your terminal. Secret redaction is on by default (disable with WINX_NO_REDACT=1) and the PTY process group is killed on teardown. Use `architect` (read-only) or `code_writer` (allowlist) mode, or WINX_SANDBOX=1 (Linux Landlock) for a tighter leash. The optional HTTP transport (`winx serve --http`) puts arbitrary shell/file access on the network: it requires a bearer token, refuses to start without one, binds to loopback by default, and has a DNS-rebinding guard - but anyone with the token gets a shell on your machine, so keep it behind an authenticated tunnel.
Winx Code Agent FAQ
How do I install and run it?
Run `cargo install winx-code-agent` (needs Rust 1.75+); the binary lands in ~/.cargo/bin. Add it to your client with a `mcpServers` entry using command `winx-code-agent`, or for Claude Code run `claude mcp add winx -- winx-code-agent`. The first tool call must always be Initialize.
What are the three workspace modes?
wcgw gives full shell and file access; architect is read-only (no writes, most commands disabled); code_writer lets you allowlist commands and write globs, enforced with tree-sitter so it checks every command on a line including pipelines, subshells, and command substitution.
Can a cloud client like ChatGPT use it?
Yes. Run `winx serve --http --bind 127.0.0.1:8000 --token <secret>` to serve MCP over Streamable HTTP at /mcp. Every request must carry the token as an Authorization: Bearer header; the server refuses to start without a token. Put a tunnel (e.g. cloudflared) in front and allow its hostname through the DNS-rebinding guard.
What does it do about leaked secrets?
Secret redaction is on by default: high-confidence credentials (provider API keys, JWTs, PEM private-key blocks, user:pass@ URLs) are scrubbed from all tool output and saved memory and replaced with [REDACTED:<rule>]. Disable with WINX_NO_REDACT=1 only when you knowingly need a raw value.
Alternatives to Winx Code Agent
Compare all alternatives →
Microsoft's official browser-automation MCP using Playwright's accessibility tree (no vision model).
Up-to-date, version-specific library documentation injected into your coding agent.
Code intelligence engine that indexes repos into a persistent knowledge graph for AI coding agents.
Compare Winx Code Agent with: