# gabrielmaialva33/winx-code-agent [Health: Active]

**Category:** 🤖 Coding Agents  
**Repository:** https://github.com/gabrielmaialva33/winx-code-agent  
**GitHub Stars:** 33  
**Views:** 3  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/gabrielmaialva33-winx-code-agent

## Description
A high-performance Rust reimplementation of WCGW for code agents, providing shell execution and advanced file management capabilities for LLMs via MCP.

## Tools
Capabilities this server exposes over MCP:

- **Initialize** — Boots the workspace, picks the mode, hands you an inseparable `thread_id`/`workspace_root` pair plus a bounded `temporary_artifact_dir` for session-local derived helpers. Call it once unless a local MCP client exposes Roots, in which case Winx can bootstrap automatically. Repeated `first_call` requ…
- **BashCommand** — Runs commands, polls long-running ones, sends Enter/Ctrl-C, and drives TUIs. Related finite fail-fast checks can be composed with `&&` in one call. `wait_policy` is generic: `adaptive` (default) keeps short calls inline and promotes an already-running foreground command when Tasks are available; `u…
- **ReadFiles** — One or many files, with line numbers. Batched reads use a bounded parallel worker pool while preserving request order and read-before-edit coverage. Each file also returns an opaque revision and its exact visible ranges for the default existing-file `line_patch` flow. Append `:10-40` to a path for…
- **EditFiles** — Creates, changes, or undoes one or many files. One edit call may contain up to 100 unique targets and validates the full batch before writing. Each entry selects an explicit mode: revision-bound `line_patch` is the default after `ReadFiles`, `search_replace` is reserved for intentional exact text a…
- **ContextSave** — Dumps task description + file globs into a single text file with workspace context, active files, and git status/diff for clean handoff and task resumption.
- **ReadImage** — Returns validated JPEG, PNG, GIF, or WebP as a native MCP image content block (not base64 text), so multimodal models actually see it. Sources are capped at 50 MiB and bounded by decoded dimensions/allocation; delivery is at most 2 MiB and 2560 px on the long edge, with oversized inputs converted t…
- **CodeMap** — Tree-sitter code navigation, in one tool with two `operation`s. `outline`: a symbol map (functions, types, methods, ...) - a file returns its definitions, a directory (or empty) a relevance-ranked, token-budgeted repo symbol map, in 13 languages including Python and Elixir. `references`: where a `n…

## Claude Desktop Quick Installation
Heuristic fallback — verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low):

```json
"mcpServers": {
  "winx-code-agent": {
    "command": "npx",
    "args": ["-y","gabrielmaialva33-winx-code-agent"]
  }
}
```

## Documentation

## What gabrielmaialva33/winx-code-agent MCP server does

gabrielmaialva33/winx-code-agent MCP server exposes coding-agent operations through MCP. Its toolset covers workspace initialization, shell execution, file reading and editing, context handoff, image delivery, and code navigation. The runtime is implemented in Rust and supports both local stdio clients and Streamable HTTP clients.

The server is designed for tasks that require more than one-off command execution. Shell state can persist within a session, including the current directory, foreground processes, background processes, interactive input, and terminal UI activity. Workspace modes include full access, read-only architect mode, and a code-writer mode with command and write-glob restrictions.

## How it works

For local use, an MCP client launches `winx-code-agent` over stdio. For networked use, the process serves an MCP endpoint such as `/mcp` over Streamable HTTP. HTTP requests are authenticated with a bearer token and are associated with a principal, workspace, and durable session. On Unix, Winx uses a control process and per-session guardians to keep PTYs alive across HTTP disconnects, client restarts, and adapter upgrades.

The `Initialize` tool establishes the workspace relationship and returns a thread identifier, workspace root, and bounded temporary artifact directory. Clients generally call it once, unless their MCP environment provides Roots support for automatic bootstrapping. Shell commands can run in the foreground or background, be polled, and receive input such as Enter or Ctrl-C.

File mutations use a typed workflow. Reads return line-numbered content, visible ranges, and an opaque revision. `EditFiles` can then apply revision-bound patches, exact search-and-replace operations, batches, verification, and undo. Planning and validation happen before writes, and edits use canonical paths and atomic per-file replacement.

## Tools and capabilities

The gabrielmaialva33/winx-code-agent MCP server provides these documented tools:

- `Initialize` for workspace and session setup.
- `BashCommand` for shell commands, polling, interactive input, and terminal UI control.
- `ReadFiles` for single or batched reads with line ranges and revision information.
- `EditFiles` for creating, changing, verifying, and undoing files.
- `ContextSave` for writing task details, file globs, active files, and Git state to a handoff file.
- `ReadImage` for validated JPEG, PNG, GIF, or WebP input as native MCP image content.
- `CodeMap` for Tree-sitter symbol outlines and reference lookup across supported codebases.

`CodeMap` supports outline and reference operations, with repository symbol maps bounded by token budget. The supplied description identifies 13 supported languages, including Python and Elixir.

## Setup and configuration

Install the executable with Cargo:

```bash
cargo install winx-code-agent
```

A local MCP client can launch `winx-code-agent` directly. For HTTP, create a protected token file and start the service with a loopback bind and token-file option:

```bash
winx-code-agent serve --http --bind 127.0.0.1:8000 --token-file ~/.config/winx-http-token
```

Clients connect to `http://127.0.0.1:8000/mcp` and send the token as a bearer credential. Cloud clients require a reachable HTTPS endpoint, typically through a private tunnel, VPN, or authenticated reverse proxy. `WINX_SHELL=zsh` selects zsh instead of the default shell.

## Limitations and notes

HTTP is the primary deployment path, but remote clients cannot use a loopback-only endpoint without an intervening network mechanism. The default HTTP configuration requires a strong bearer token and is intended to remain private unless protected by suitable HTTPS infrastructure. The command and write restrictions depend on the selected workspace mode, so agents needing unrestricted access must use the full-access mode. Image sources are size- and dimension-bounded, and terminal output is bounded before delivery to the model.

_Full upstream README: https://allmcps.com/mcp/gabrielmaialva33-winx-code-agent/readme_