Weavatrix Refactor

The explicit source-write layer of the Weavatrix ecosystem; Core remains read-only.

Refactor across files without letting the agent guess.

Weavatrix Refactor is a native MCP server for coding agents. It finds a symbol through the repository graph, previews byte-exact edits, reports every same-named occurrence it could not prove, and writes only after an explicit, hash-bound confirmation.

The useful difference is not “AI can rename a word.” It is that the agent gets evidence before the write and a recoverable transaction after it.

Install

Run the native binary through npm:

npx -y weavatrix-refactor mcp /absolute/path/to/repository

Or install it with Cargo:

cargo install weavatrix-refactor --locked
weavatrix-refactor mcp /absolute/path/to/repository

An MCP client can start it directly:

{
  "mcpServers": {
    "weavatrix-refactor": {
      "command": "weavatrix-refactor",
      "args": ["mcp", "/absolute/path/to/repository"],
      "env": {"WEAVATRIX_ALLOW_SOURCE_EDITS": "1"}
    }
  }
}

Leave WEAVATRIX_ALLOW_SOURCE_EDITS unset for preview-only sessions. Preview is a read; only a confirmed apply or rollback requires the gate.

Install as a plugin

The repository also ships one plugin bundle for Cursor, Codex, Claude Code, and Grok Build. The plugin starts the extension-only profile, so it contributes the 11 Refactor methods without repeating Weavatrix Core's 43 read-only method definitions. Install the separate Weavatrix plugin when both surfaces are needed.

The bundled skill is optional and activates only for explicitly requested refactoring work. Its entry point stays short; each method has an individual reference card that is loaded only when needed.

• Cursor: search for Weavatrix Refactor after marketplace approval.
• Codex: add the Weavatrix/weavatrix-refactor marketplace from .agents/plugins, then add weavatrix-refactor@weavatrix-refactor.
• Claude Code: add the same repository marketplace from .claude-plugin, then install weavatrix-refactor@weavatrix-refactor.
• Grok Build: run grok plugin marketplace add Weavatrix/weavatrix-refactor, open /marketplace, and install it.

The plugin opens WEAVATRIX_ALLOW_SOURCE_EDITS=1, but every write still needs the exact preview's short-lived, plan-bound single-use token.

For a rename task, expose only the two tools the agent needs:

weavatrix-refactor mcp /absolute/path/to/repository --profile=rename

The rename profile keeps rename_symbol and rollback_last_apply; every unrelated graph and refactor tool is absent and cannot be called. Omit the option (or use --profile=refactor) for all 11 Refactor methods. The narrower catalog reduces repeated agent context; it does not weaken preview hashes, the write gate, the confirmation token, or rollback checks.

When Weavatrix Core is already installed as a separate MCP, expose only the 11 methods that Refactor adds:

weavatrix-refactor mcp /absolute/path/to/repository --profile=refactor

The refactor profile is the default for MCP and list-tools, including the marketplace plugin. The former full compatibility profile has been removed and is rejected by both commands: Refactor no longer republishes Core methods. Install Weavatrix Core as its own MCP when read-only repository intelligence is also needed.

A safe cros

... View full README on GitHub