{"id":27779904,"url":"https://github.com/gabrielmaialva33/winx-code-agent","last_synced_at":"2026-05-24T00:01:20.509Z","repository":{"id":288373875,"uuid":"967824112","full_name":"gabrielmaialva33/winx-code-agent","owner":"gabrielmaialva33","description":"✨ A high-performance code agent written in Rust, combining the best features of WCGW for maximum efficiency and semantic capabilities. 🦀","archived":false,"fork":false,"pushed_at":"2026-05-23T16:09:54.000Z","size":2519,"stargazers_count":27,"open_issues_count":3,"forks_count":8,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-23T16:28:25.139Z","etag":null,"topics":["autonomous","code-agent","computer","control","execution","llm-agent","llm-code","mcp","rust","serena","shell","vibe-coding","vibecoding","wcgw"],"latest_commit_sha":null,"homepage":"https://crates.io/crates/winx-code-agent","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gabrielmaialva33.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-04-17T04:07:28.000Z","updated_at":"2026-05-23T16:09:57.000Z","dependencies_parsed_at":"2025-04-17T18:49:14.377Z","dependency_job_id":"80e37576-5820-4ef9-94cf-c9994db056d0","html_url":"https://github.com/gabrielmaialva33/winx-code-agent","commit_stats":null,"previous_names":["gabrielmaialva33/winx-code-agent"],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/gabrielmaialva33/winx-code-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gabrielmaialva33%2Fwinx-code-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gabrielmaialva33%2Fwinx-code-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gabrielmaialva33%2Fwinx-code-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gabrielmaialva33%2Fwinx-code-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gabrielmaialva33","download_url":"https://codeload.github.com/gabrielmaialva33/winx-code-agent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gabrielmaialva33%2Fwinx-code-agent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33416315,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-23T22:14:44.296Z","status":"ssl_error","status_checked_at":"2026-05-23T22:14:43.778Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["autonomous","code-agent","computer","control","execution","llm-agent","llm-code","mcp","rust","serena","shell","vibe-coding","vibecoding","wcgw"],"created_at":"2025-04-30T10:56:11.017Z","updated_at":"2026-05-24T00:01:20.500Z","avatar_url":"https://github.com/gabrielmaialva33.png","language":"Rust","funding_links":[],"categories":["AI Agents","پیاده‌سازی‌های سرور","📦 Other"],"sub_categories":["Code Assistants","🤖 \u003ca name=\"coding-agents\"\u003e\u003c/a\u003eعامل‌های کدنویسی"],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\".github/assets/fairy.png\" alt=\"Winx fairy mascot\" width=\"160\" /\u003e\n\u003c/p\u003e\n\n# ✨ Winx - MCP Server for Shell \u0026 Coding Agents ✨\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003e🦀 Native Rust implementation inspired by WCGW, built for local code-agent workflows\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/language-Rust-orange?style=flat\u0026logo=rust\" alt=\"Language\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/license-MIT-blue?style=flat\" alt=\"License\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/MCP-compatible-purple?style=flat\" alt=\"MCP\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/transport-stdio-2f855a?style=flat\" alt=\"stdio transport\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cem\u003eA local MCP server you can hand to a coding agent and stop worrying about the shell.\u003c/em\u003e\n\u003c/p\u003e\n\nWinx is the MCP server I wanted while running Claude, Codex, and friends against real repos: one process that handles\nthe shell, file IO, and PTY-backed interactive sessions, written in Rust so it doesn't fight you on stdio.\n\nIt started as a Rust port of [WCGW](https://github.com/rusiaaman/wcgw) but isn't a Python wrapper. Everything runs on a\nreal PTY (via `portable-pty`), `cd` actually sticks, `Ctrl+C` actually interrupts, and background shells survive\nlong-running TUIs without leaking output buffers into your token budget.\n\n## What you get\n\n- A stateful bash session per thread with proper PTY semantics — foreground, background, status checks, text input,\n  Enter/Ctrl-C/Ctrl-D, raw ASCII.\n- Workspaces with three modes: `wcgw` (full access), `architect` (read-only), `code_writer` (allowlist of commands and\n  write globs).\n- File reads with WCGW-style line ranges (`file.rs:10-40`, `file.rs:10-`, `file.rs:-40`).\n- File writes and SEARCH/REPLACE edits that survive ambiguous matches, indentation drift, and the usual unicode\n  quote-mismatches from LLMs.\n- `ContextSave` for handing a task summary plus its files to the next session.\n- `ReadImage` so multimodal clients can pull screenshots, mockups, error PNGs, etc.\n\n## MCP Tools\n\n| Tool              | What it does                                                                                                                                                   |\n|-------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `Initialize`      | Boots the workspace, picks the mode, hands you a `thread_id`. Call this first or everything else errors out.                                                   |\n| `BashCommand`     | Runs commands, polls long-running ones, sends Enter/Ctrl-C, drives TUIs. Supports `is_background`, `status_check`, `send_text`, `send_specials`, `send_ascii`. |\n| `ReadFiles`       | One or many files, with line numbers. Append `:10-40` to a path for a range.                                                                                   |\n| `FileWriteOrEdit` | Full overwrites or SEARCH/REPLACE blocks. Refuses to write a file you haven't read yet.                                                                        |\n| `ContextSave`     | Dumps task description + file globs into a single text file for resume/handoff.                                                                                |\n| `ReadImage`       | Base64 + MIME, for clients that can render images.                                                                                                             |\n\n## Search/Replace editing\n\nStandard block syntax:\n\n```text\n\u003c\u003c\u003c\u003c\u003c\u003c\u003c SEARCH\nold content\n=======\nnew content\n\u003e\u003e\u003e\u003e\u003e\u003e\u003e REPLACE\n```\n\nThings the matcher forgives so you don't have to babysit the model:\n\n- atomic: ambiguous or missing matches abort without touching the file\n- adjusts replacement indentation when the LLM gets the leading whitespace wrong\n- strips `ReadFiles` line numbers if they leak into a SEARCH block\n- normalizes the usual \"smart quote\" / em-dash / ellipsis substitutions\n- uses neighboring blocks to disambiguate when the same snippet appears twice\n- single-line substring edits work — you don't need the whole line in SEARCH\n\n## Install\n\n```bash\ncargo install winx-code-agent\n```\n\nBinary lands in `~/.cargo/bin` — every config snippet below assumes that's on `$PATH`. If your MCP client launches with\na sterile env, swap `winx-code-agent` for the absolute path (`which winx-code-agent`).\n\nNeeds Rust 1.75+, Linux/macOS/WSL2, and a real terminal (any modern one — Winx spawns its own PTY).\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eClaude Code (CLI)\u003c/b\u003e\u003c/summary\u003e\n\nOne-liner via the CLI (stdio is the default transport):\n\n```bash\nclaude mcp add winx -- winx-code-agent\n```\n\nOr drop a `.mcp.json` in your project root:\n\n```json\n{\n  \"mcpServers\": {\n    \"winx\": {\n      \"command\": \"winx-code-agent\",\n      \"env\": { \"RUST_LOG\": \"winx_code_agent=info\" }\n    }\n  }\n}\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eClaude Desktop\u003c/b\u003e\u003c/summary\u003e\n\nAdd to your config file (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, `%APPDATA%\\Claude\\claude_desktop_config.json` on Windows):\n\n```json\n{\n  \"mcpServers\": {\n    \"winx\": {\n      \"command\": \"winx-code-agent\",\n      \"env\": { \"RUST_LOG\": \"winx_code_agent=info\" }\n    }\n  }\n}\n```\n\nRestart Claude Desktop after saving.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eCodex (OpenAI CLI)\u003c/b\u003e\u003c/summary\u003e\n\nOne-liner:\n\n```bash\ncodex mcp add winx -- winx-code-agent\n```\n\nOr edit `~/.codex/config.toml`:\n\n```toml\n[mcp_servers.winx]\ncommand = \"winx-code-agent\"\nenv = { RUST_LOG = \"winx_code_agent=info\" }\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eCursor\u003c/b\u003e\u003c/summary\u003e\n\nAdd to `~/.cursor/mcp.json` (or `.cursor/mcp.json` for project-local):\n\n```json\n{\n  \"mcpServers\": {\n    \"winx\": {\n      \"command\": \"winx-code-agent\",\n      \"env\": { \"RUST_LOG\": \"winx_code_agent=info\" }\n    }\n  }\n}\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eVS Code (Copilot Chat / MCP)\u003c/b\u003e\u003c/summary\u003e\n\nAdd to `.vscode/mcp.json`:\n\n```json\n{\n  \"servers\": {\n    \"winx\": {\n      \"type\": \"stdio\",\n      \"command\": \"winx-code-agent\"\n    }\n  }\n}\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eZed\u003c/b\u003e\u003c/summary\u003e\n\nAdd to your Zed settings (`~/.config/zed/settings.json`):\n\n```json\n{\n  \"context_servers\": {\n    \"winx\": {\n      \"source\": \"custom\",\n      \"command\": \"winx-code-agent\",\n      \"args\": [],\n      \"env\": { \"RUST_LOG\": \"winx_code_agent=info\" }\n    }\n  }\n}\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eWindsurf\u003c/b\u003e\u003c/summary\u003e\n\nAdd to `~/.codeium/windsurf/mcp_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"winx\": {\n      \"command\": \"winx-code-agent\",\n      \"env\": { \"RUST_LOG\": \"winx_code_agent=info\" }\n    }\n  }\n}\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eOpenCode\u003c/b\u003e\u003c/summary\u003e\n\nAdd to `opencode.json`:\n\n```json\n{\n  \"mcp\": {\n    \"winx\": {\n      \"type\": \"local\",\n      \"command\": [\"winx-code-agent\"],\n      \"enabled\": true,\n      \"environment\": { \"RUST_LOG\": \"winx_code_agent=info\" }\n    }\n  }\n}\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eGemini CLI\u003c/b\u003e\u003c/summary\u003e\n\nAdd to `~/.gemini/settings.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"winx\": {\n      \"command\": \"winx-code-agent\",\n      \"args\": [],\n      \"env\": { \"RUST_LOG\": \"winx_code_agent=info\" }\n    }\n  }\n}\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eagy (Google Antigravity CLI)\u003c/b\u003e\u003c/summary\u003e\n\n`agy` is Google's new Gemini-powered CLI (Go binary, usually at `~/.local/bin/agy`). No `mcp add` subcommand yet — it\nreads MCP servers from JSON.\n\nEdit `~/.gemini/config/mcp_config.json` (also `~/.gemini/antigravity/mcp_config.json` if you run the Antigravity IDE\nalongside):\n\n```json\n{\n  \"mcpServers\": {\n    \"winx\": {\n      \"command\": \"winx-code-agent\",\n      \"env\": { \"RUST_LOG\": \"winx_code_agent=info\" }\n    }\n  }\n}\n```\n\nIf `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`).\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eContinue.dev\u003c/b\u003e\u003c/summary\u003e\n\nAdd to your `~/.continue/config.yaml`:\n\n```yaml\nmcpServers:\n  - name: winx\n    command: winx-code-agent\n    env:\n      RUST_LOG: winx_code_agent=info\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eKiro\u003c/b\u003e\u003c/summary\u003e\n\nAdd to `~/.kiro/settings/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"winx\": {\n      \"command\": \"winx-code-agent\",\n      \"env\": { \"RUST_LOG\": \"winx_code_agent=info\" }\n    }\n  }\n}\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eWarp\u003c/b\u003e\u003c/summary\u003e\n\n**Settings → MCP Servers → Add MCP Server**:\n\n```json\n{\n  \"winx\": {\n    \"command\": \"winx-code-agent\",\n    \"env\": { \"RUST_LOG\": \"winx_code_agent=info\" }\n  }\n}\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eRoo Code\u003c/b\u003e\u003c/summary\u003e\n\nAdd to your Roo Code MCP config:\n\n```json\n{\n  \"mcpServers\": {\n    \"winx\": {\n      \"type\": \"stdio\",\n      \"command\": \"winx-code-agent\"\n    }\n  }\n}\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eOther clients (generic stdio)\u003c/b\u003e\u003c/summary\u003e\n\nAny client that speaks stdio MCP works with this shape:\n\n```json\n{\n  \"mcpServers\": {\n    \"winx\": {\n      \"command\": \"winx-code-agent\",\n      \"args\": [],\n      \"env\": { \"RUST_LOG\": \"winx_code_agent=info\" }\n    }\n  }\n}\n```\n\nIf your client launches Winx with an empty `$PATH`, swap `command` for the absolute path (\n`~/.cargo/bin/winx-code-agent`).\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eBuild from source\u003c/b\u003e\u003c/summary\u003e\n\nFor unreleased changes or a custom build:\n\n```bash\ngit clone https://github.com/gabrielmaialva33/winx-code-agent.git\ncd winx-code-agent\ncargo install --path .\n```\n\nOr run it without installing:\n\n```bash\ncargo run --release\n```\n\u003c/details\u003e\n\n### Check it's wired up\n\nList MCP tools in your client. You should see six entries: `Initialize`, `BashCommand`, `ReadFiles`, `FileWriteOrEdit`,\n`ContextSave`, `ReadImage`. The first call always has to be `Initialize` — Winx tracks workspace + mode per thread.\n\n## Hacking on it\n\n```bash\ncargo fmt --all\ncargo clippy --all-targets --all-features -- -D warnings\ncargo test --all-features\n```\n\nCI runs the same three. If you touch `src/state/pty.rs` or anything in `src/tools/bash_command.rs`, the regression suite\nat `tests/bash_pty_regression_test.rs` is what protects against the usual TUI/PTY foot-guns — run it first.\n\n## A note on security\n\nThis is a local MCP server. Anything connected to it can read files, edit files, and run shell commands inside the\nworkspace — same blast radius as letting the model into your terminal.\n\nIf you want a tighter leash:\n\n- `architect` mode disables writes and most commands;\n- `code_writer` mode lets you allowlist commands and write globs.\n\n[SECURITY.md](SECURITY.md) has the disclosure process and threat model.\n\n## License\n\nMIT - Gabriel Maia ([@gabrielmaialva33](https://github.com/gabrielmaialva33))\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgabrielmaialva33%2Fwinx-code-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgabrielmaialva33%2Fwinx-code-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgabrielmaialva33%2Fwinx-code-agent/lists"}