{
  "markdown": "# Weavatrix Refactor\n\n[![CI](https://github.com/Weavatrix/weavatrix-refactor/actions/workflows/ci.yml/badge.svg)](https://github.com/Weavatrix/weavatrix-refactor/actions/workflows/ci.yml)\n[![npm](https://img.shields.io/npm/v/weavatrix-refactor.svg)](https://www.npmjs.com/package/weavatrix-refactor)\n[![crates.io](https://img.shields.io/crates/v/weavatrix-refactor.svg)](https://crates.io/crates/weavatrix-refactor)\n[![docs.rs](https://docs.rs/weavatrix-refactor/badge.svg)](https://docs.rs/weavatrix-refactor)\n[![MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n\nThe explicit source-write layer of the [Weavatrix ecosystem](https://weavatrix.com/ecosystem); Core remains read-only.\n\n**Refactor across files without letting the agent guess.**\n\nWeavatrix Refactor is a native MCP server for coding agents. It finds a symbol through the\nrepository graph, previews byte-exact edits, reports every same-named occurrence it could not\nprove, and writes only after an explicit, hash-bound confirmation.\n\nThe useful difference is not “AI can rename a word.” It is that the agent gets evidence before\nthe write and a recoverable transaction after it.\n\n## Install\n\nRun the native binary through npm:\n\n```bash\nnpx -y weavatrix-refactor mcp /absolute/path/to/repository\n```\n\nOr install it with Cargo:\n\n```bash\ncargo install weavatrix-refactor --locked\nweavatrix-refactor mcp /absolute/path/to/repository\n```\n\nAn MCP client can start it directly:\n\n```json\n{\n  \"mcpServers\": {\n    \"weavatrix-refactor\": {\n      \"command\": \"weavatrix-refactor\",\n      \"args\": [\"mcp\", \"/absolute/path/to/repository\"],\n      \"env\": {\"WEAVATRIX_ALLOW_SOURCE_EDITS\": \"1\"}\n    }\n  }\n}\n```\n\nLeave `WEAVATRIX_ALLOW_SOURCE_EDITS` unset for preview-only sessions. Preview is a read; only a\nconfirmed apply or rollback requires the gate.\n\n### Install as a plugin\n\nThe repository also ships one plugin bundle for Cursor, Codex, Claude Code,\nand Grok Build. The plugin starts the extension-only profile, so it contributes\nthe 11 Refactor methods without repeating Weavatrix Core's 43 read-only method\ndefinitions. Install the separate Weavatrix plugin when both surfaces are\nneeded.\n\nThe bundled skill is optional and activates only for explicitly requested\nrefactoring work. Its entry point stays short; each method has an individual\nreference card that is loaded only when needed.\n\n- Cursor: search for **Weavatrix Refactor** after marketplace approval.\n- Codex: add the `Weavatrix/weavatrix-refactor` marketplace from\n  `.agents/plugins`, then add `weavatrix-refactor@weavatrix-refactor`.\n- Claude Code: add the same repository marketplace from `.claude-plugin`, then\n  install `weavatrix-refactor@weavatrix-refactor`.\n- Grok Build: run `grok plugin marketplace add\n  Weavatrix/weavatrix-refactor`, open `/marketplace`, and install it.\n\nThe plugin opens `WEAVATRIX_ALLOW_SOURCE_EDITS=1`, but every write still needs\nthe exact preview's short-lived, plan-bound single-use token.\n\nFor a rename task, expose only the two tools the agent needs:\n\n```bash\nweavatrix-refactor mcp /absolute/path/to/repository --profile=rename\n```\n\nThe `rename` profile keeps `rename_symbol` and `rollback_last_apply`; every\nunrelated graph and refactor tool is absent and cannot be called. Omit the\noption (or use `--profile=refactor`) for all 11 Refactor methods. The narrower\ncatalog reduces repeated agent context; it does not weaken preview hashes, the\nwrite gate, the confirmation token, or rollback checks.\n\nWhen Weavatrix Core is already installed as a separate MCP, expose only the 11\nmethods that Refactor adds:\n\n```bash\nweavatrix-refactor mcp /absolute/path/to/repository --profile=refactor\n```\n\nThe `refactor` profile is the default for MCP and `list-tools`, including the\nmarketplace plugin. The former `full` compatibility profile has been removed\nand is rejected by both commands: Refactor no longer republishes Core methods.\nInstall Weavatrix Core as its own MCP when read-only repository intelligence is\nalso needed.\n\n## A safe cross-file rename in three calls\n\nSuppose two files declare `resolveTarget`. A bare name is ambiguous, so the server refuses to\npick one and returns exact ids:\n\n```json\n// rename_symbol\n{\"symbol\":\"resolveTarget\",\"new_name\":\"locateTarget\",\"output_format\":\"json\"}\n\n{\n  \"status\": \"NOT_FOUND\",\n  \"reason\": \"the name matches more than one symbol; pass one of the candidate ids\",\n  \"candidates\": [\n    \"symbol:src/core.ts#function:resolveTarget@2:1\",\n    \"symbol:src/shadow.ts#function:resolveTarget@3:1\"\n  ]\n}\n```\n\nRetry with the intended id. The result is still read-only: it contains the edit plan, content\nhashes, the proven edit count, and the references the backend refused to guess at.\n\n```json\n// rename_symbol\n{\n  \"symbol\": \"symbol:src/core.ts#function:resolveTarget@2:1\",\n  \"new_name\": \"locateTarget\",\n  \"output_format\": \"json\"\n}\n\n{\n  \"status\": \"PLANNED\",\n  \"completeness\": \"PARTIAL\",\n  \"renamedEdits\": 7,\n  \"uncertainReferences\": [\"... three named locations ...\"],\n  \"confirmToken\": \"single-use-token\",\n  \"plan\": {\"schemaVersion\":\"weavatrix.edit-plan.v1\",\"files\":[\"...\"]}\n}\n```\n\nAfter reviewing the plan, repeat the same operation with the same inputs and its token:\n\n```json\n// rename_symbol\n{\n  \"symbol\": \"symbol:src/core.ts#function:resolveTarget@2:1\",\n  \"new_name\": \"locateTarget\",\n  \"mode\": \"apply\",\n  \"confirm_token\": \"single-use-token\",\n  \"output_format\": \"json\"\n}\n\n{\"status\":\"APPLIED\"}\n```\n\nThis exact flow is exercised against the real stdio MCP server. The repository fixture requires\nseven edits across three files, preserves four traps (a longer identifier, string, comment, and\nunrelated shadow), and must still compile; it scores **12/12**.\n\n## What is automatic today\n\nThe eleven tools do not all claim the same level of automation:\n\n| Level | Tools | What the agent receives |\n| --- | --- | --- |\n| Complete preview/apply workflow | `rename_symbol`, `rename_related_symbols` | A generated plan and token, then a confirmed write by repeating the same operation |\n| Plan-producing | `change_signature`, `edit_symbol`, `bulk_replace`, `organize_imports`, `move_file` | Byte-exact edits or a review plan; use `apply_edit_plan` where an edit-plan envelope is returned |\n| Advisory | `move_symbol`, `delete_readiness` | Blast radius, cycle/architecture risks, or a deletion verdict; no automatic source write |\n| Safety infrastructure | `apply_edit_plan`, `rollback_last_apply` | Verification/application of an edit-plan envelope and drift-safe restoration |\n\nRefactor uses the Rust Weavatrix graph internally for evidence but never\nexports Core methods. Install the separate Weavatrix plugin for read-only\nrepository intelligence. The Refactor MCP owns exactly its 11 extension\nmethods; `--profile=rename` is an optional narrower two-method workflow.\n\n## Safety model and exact limits\n\n- Ambiguous names fail with candidate ids instead of selecting the first match.\n- `PARTIAL` means the graph proved the edits in the plan but did **not** prove that no other\n  semantic references exist. `uncertainReferences` names the places requiring review.\n- Every file in a plan carries a content hash. A changed working tree makes the preview stale\n  instead of applying the old coordinates.\n- Apply requires `WEAVATRIX_ALLOW_SOURCE_EDITS=1` plus a short-lived, single-use token bound to\n  that repository and exact recomputed plan.\n- `rollback_last_apply` refuses to overwrite files that drifted after the transaction.\n- Multi-file writes are journaled and crash-recoverable. They are not observationally atomic to\n  unrelated processes: another process may briefly observe an intermediate filesystem state.\n\nOnly edits with proven provenance are applied. A lexical or graph backend is deliberately more\nconservative than a language server and must not be read as a claim of full compiler semantics.\n\n## Measured benchmark, with unlike layers kept separate\n\nThe checked-in August 2026 benchmark uses equivalent adversarial TypeScript, Rust, and Python\nfixtures. Each has seven required edits, four traps, and a build/test gate. Protocol runs count\nexact `o200k_base` initialization, catalog, request, and response tokens. Agent runs use the\nactual cumulative usage reported by Codex CLI with pinned `gpt-5.6-sol` / medium reasoning.\nNo byte proxy or estimated tokens-per-second conversion is used.\n\nThe new rename-only profile kept all nine protocol runs at 12/12 while reducing fixed MCP context\nfrom 9,331 to 485 tokens. Its guided TypeScript agent A/B is:\n\n| Arm | Correctness | Median end-to-end | Median input tokens |\n| --- | ---: | ---: | ---: |\n| Naked Codex | **12/12 x3** | **42,602 ms** | **72,169** |\n| Weavatrix 1.0.6 `--profile=rename` | **12/12 x3** | 48,389 ms | 108,155 |\n| Weavatrix 1.0.5 full surface | **12/12 x3** | 58,719 ms | 275,784 |\n| Serena | **12/12 x3** | 68,728 ms | 388,271 |\n\nThe full agent matrix is 12/12 in all 27 TypeScript/Rust/Python runs; every run also completed\noperationally and passed the sanitized edit-channel audit. The deterministic protocol\nmatrix also exposed a language-specific Serena defect: its suggested `find_symbol` →\n`rename_symbol` flow scored 7/12 on TypeScript in all three runs, while Rust and Python passed.\nIt also found and drove fixes for Rust macro calls and Python f-string/module-level call evidence.\n\nOn this toy TypeScript repository naked Codex is still faster and cheaper than the narrowed\nprofile. Weavatrix's demonstrated value is preview-before-write, named uncertainty, stale-plan\nrefusal, explicit authorization, and rollback—not a universal small-repository token win.\n\nSee the [full methodology, all language medians, raw-result links, and limitations](docs/benchmarks/refactor-vs-competitors-2026-08.md).\n\n## Contract\n\nThe 11 Refactor tool names, schemas, and result states are frozen in\n[`contract/refactor-tools.v1.json`](contract/refactor-tools.v1.json). All refactor operations are\nnative Rust; the host uses the read-only\n[`weavatrix-rust`](https://github.com/Weavatrix/weavatrix-rust) engine\ninternally for graph evidence without exporting its methods on the default\nsurface.\n\nVersions 0.1.x used the JavaScript engine. That line continues as\n[`weavatrix-refactor-js`](https://github.com/Weavatrix/weavatrix-refactor-js) and keeps a\nseparate state directory, token store, and rollback journal.\n\n## License\n\nMIT.\n",
  "bytes": 10301,
  "sha": "3bbb3a6f2b540c4a5a909e908b4c81b26b2150f454b7ad9b98f963ecb7ef1fc7",
  "repo_slug": "weavatrix/weavatrix-refactor",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_weavatrix_weavatrix_refactor_6609e6c6/readme"
}