Patchloom

Append content to an existing file. Inserts the file's line ending first when the file does not already end with one. Example: {"content":"#[test]\nfn new_test() {}\n","path":"tests/test.rs"}

Constrained freeform fragment apply (#2018). Strips Morph-style // ... existing code ... marker lines from fragment, then inserts or replaces at a required unique anchor (exactly one of after, before, old). Fail-closed: no anchor-less Morph model merge. Prefer for lazy-snippet agent output when anchors are known; use replace/ast for precise edits. Morph-class freeform fragment with required placement (exactly one of after/before/old). Lazy // ... existing code ... lines are stripped; no model merge without anchors (#2018). Example: {"fragment":"// ... existing code ...\n bar();\n// ... existing code ...\n","path":"src/lib.rs","after":"fn foo() {"}

Apply a unified diff, a Codex *** Begin Patch document, or an Aider SEARCH/REPLACE / DiffFenced document. Default apply=true writes (same as CLI patch apply --apply). Set apply=false for check-only preview (CLI patch check; disk is unchanged). The diff parameter is the full unified diff text, a *** Begin Patch ... *** End Patch envelope (Add/Update/Delete/Move), or <<<<<<< SEARCH / ======= / >>>>>>> REPLACE blocks (dest path above ------- after SEARCH). SEARCH/REPLACE is unique by default (multi-match is ambiguous, no write); set replace_all=true to update every exact match. Empty-hunk +++ /dev/null (git deleted file mode, no hunks) unlinks. A hunked delete applies minus lines first; leftover bytes rewrite the file (preview --diff). Stale minus lines are ambiguous and the file is not removed; regenerate minus lines or use file.delete for path-only unlink. Use on_stale=merge for three-way merge on stale unified-diff context; allow_conflicts=true writes conflict markers. Never commit files containing conflict markers. Example: {"diff": "--- a/file.txt\n+++ b/file.txt\n@@ -1 +1 @@\n-old\n+new", "on_stale": "fail"}

Delete a whole symbol span, including leading doc comments and attributes, and collapse surrounding blank lines to one. Deletes the full symbol span (docs and attributes included) and collapses surrounding blank lines. Example: {"symbol":"unused_helper","path":"src/lib.rs"}

Extract import/dependency statements from source files. Supports Rust, Python, JS/TS, Go, Java, C/C++, Ruby, PHP. Use reverse=true to find what imports a file. Example: {"path": "src/main.rs"}

Structural diff between two versions of a file. Shows added, removed, and modified symbols (not line-level diff). Compares against git refs. Example: {"path": "src/lib.rs", "from": "HEAD~1"}

Extract a symbol (module, function, struct) to a separate file. For modules with unwrap=true, content is un-indented. Example: {"source": "src/lib.rs", "symbol": "tests", "target": "src/lib_tests.rs", "replacement": "mod tests;", "prepend": "use super::*;"}

Group symbols into a named module within a file. Creates the module if it doesn't exist, or appends to it. Example: {"path": "src/tests.rs", "module": "line_endings", "symbols": ["test_crlf", "test_lf"], "preamble": "use super::*;"}

Transitive impact analysis: what symbols are affected by changing a given symbol. Traces the reference graph to find all direct and indirect dependents. Example: {"symbol": "parse_config", "path": "src/", "depth": 3}

Manage import/use statements: add (idempotent), remove, deduplicate. With no mutation args, lists existing imports. Example: {"path": "src/main.rs", "add": ["use std::collections::HashMap;"]}

Insert code at a structurally-aware position: inside a module/impl/struct (at start or end), or after/before a named symbol. Indentation is auto-detected. Example: {"path": "src/lib.rs", "content": "fn new_fn() {}", "after": "existing_fn"}

List symbol definitions (functions, classes, structs, enums, methods, etc.) in a file or directory. Supports 20 languages. Example: {"path": "src/"} or {"path": "main.py", "kind": "function,class"}

Generate a ranked repository map using PageRank over the symbol reference graph. Shows the most important symbols with token-budget-aware output. Example: {"path": "src/", "max_tokens": 2048}

Move symbols between files. Removes from source, inserts into target (creating it if needed). Example: {"path": "src/big.rs", "target": "src/helpers.rs", "symbols": ["helper_fn"], "target_prepend": "use super::*;"}

Read a specific symbol's source code by name from a file. Uses AST parsing to find the exact definition. Example: {"path": "src/main.rs", "symbol": "run"}

Find all references to a symbol across files using AST analysis. Distinguishes definitions from references. Example: {"symbol": "process_data", "path": "src/"}

Rename identifiers across files using AST-aware renaming (skips strings and comments). Example: {"path": "src/", "old": "process_data", "new": "transform_data"}

Reorder symbols within a file or scope by name, kind, or custom order. Example: {"path": "src/lib.rs", "order": "alphabetical"} or {"path": "src/lib.rs", "order": ["Struct", "impl Struct", "helper"], "inside": "mod tests"}

Replace text only within a specific symbol's body using AST scoping. Precise: only changes code inside the named symbol, leaving everything else untouched. Example: {"path": "src/lib.rs", "symbol": "parse_config", "old": "unwrap()", "new": "expect(\"parse failed\")"}

Replace a whole symbol span, including leading doc comments and attributes, with new source re-indented to the symbol column. Replaces the full symbol span (docs and attributes included). Example: {"content":"fn default_timeout() -> u64 { 60 }","path":"src/lib.rs","symbol":"default_timeout"}

Rewrite a function signature with structured fields (visibility, parameters, return_type) or a full new_signature string. Multi-language via tree-sitter. Example: {"path": "src/lib.rs", "old": "process", "parameters": "(x: i32)", "return_type": "-> String"}

Structural search using AST queries. Use S-expression syntax or set pattern=true for code patterns with $VAR meta-variables (pattern must be valid source after substitution, e.g. fn $NAME() {}). Literal tokens match exactly. $$$MULTI is not implemented. Example: {"query": "(function_item name: (identifier) @name)", "path": "src/"}

Split a file into multiple target files by distributing symbols. Atomic: all targets succeed or all roll back. Example: {"source": "src/big.rs", "targets": [{"path": "src/types.rs", "symbols": ["Config", "Mode"], "prepend": "use super::*;"}], "keep_in_source": ["main"], "source_suffix": "mod types;"}

Validate syntax of source files. Returns parse errors with line numbers. Supports 20 languages. Example: {"path": "src/main.rs"}

Wrap existing code in a structural block (module, impl, cfg, etc.). Specify symbols by name or a line range. Example: {"path": "src/lib.rs", "symbols": ["helper_fn", "HelperStruct"], "wrapper": "mod helpers"}

Replace the same text across multiple files in one call. Engine staging is atomic for applied writes (all written files succeed or none change). Pattern misses are soft by default: matching files still apply and total misses appear in refused[]; set require_change=true to fail the whole batch if any file has no match. Canonical field is files (array); singular file is accepted as an alias for one path. Optional fuzzy enables similarity fallback; when exact old is absent, refuse by default unless allow_absent_old=true (#1758). JSON reports match_mode (exact/fuzzy/anchored), optional match_score, optional matched_text, match_count per change and aggregate (#1674). Example: {"files": ["Cargo.toml", "README.md"], "old": "0.1.0", "new": "0.2.0"}

Fix whitespace in multiple files in one call: trims trailing spaces and ensures final newline. Atomic: all files succeed or none change. Canonical field is files (array); singular file is accepted as an alias for one path. Example: {"files": ["src/main.rs", "src/lib.rs"]}

Create a new file with specified content. Fails if the file exists unless force=true. Example: {"content":"{\"version\": \"1.0\"}","path":"config.json"}

Delete a file. Default fails with not_found if the path is missing. Set if_exists=true to soft-skip a missing file (no write, success). Set if_exists=true to soft-skip when the file is missing. Example: {"path":"tmp/scratch.txt"}

Append a value to an array at a selector path. Example: {"value":"new_item","path":"data.json","selector":"items"}

Delete a value at a selector path in a JSON, YAML, or TOML file. CLI --json and MCP/tx success include changed and removed (0 on missing key; exit 0 / ok is idempotent). Example: {"selector":"deprecated_key","path":"config.json"}

Delete array elements matching a key=value predicate via --predicate (CLI) or the predicate field (plans). For scalar arrays use .=x, _=x, or value=x. Different from doc.update, which filters inside the selector path. CLI --json and MCP/tx success include changed and removed (0 when no elements match; exit 0 / ok is idempotent). For object arrays: predicate='role=admin'. For simple arrays: predicate='_=value'. Nested paths: predicate='settings.theme=dark'. Example: {"predicate":"value=a","path":"config.toml","selector":"tags"}

Compare two structured files (JSON, YAML, or TOML) and show differences. Example: {"file_a": "old.json", "file_b": "new.json"}

Set a value only if the selector path does not already exist. Example: {"value":30,"path":"config.json","selector":"timeout"}

Read a value from a JSON, YAML, or TOML file by selector path. Example: {"path": "package.json", "selector": "version"}

Deep-merge a JSON object into a document root, or into a selector path (e.g. multi-doc YAML `0` / `[0]`). Example: {"value":{"database":{"host":"localhost","port":5432}},"path":"config.yaml"}

Move a value from one selector path to another within the same file. Example: {"to":"new_key","path":"config.json","from":"old_key"}

Prepend a value to the beginning of an array at a selector path.

Query a JSON, YAML, or TOML file. Actions: "has" (exists, true/false), "keys" (keys of one object; omit selector for `.`; e.g. database or items[0]), "len" (length of one object or array; omit selector for `.`; e.g. items or database), "select" (filter via selector predicates, e.g. users[role=admin]; no separate predicate field), "flatten" (leaf paths). keys need one object; len needs one object or array; items[*] is fail-closed ambiguous (use items[0] / items[1]). Example: {"action": "has", "path": "config.json", "selector": "database.host"}

Set a value at a single concrete selector path in a JSON, JSONC, YAML, TOML, .env, .ini, or .properties file (keys and indexes such as server.port or items.0.v). Parser-backed; output is always valid. Not for predicates or wildcards (items[name=foo].v, items[*].v); use doc.update for multi-match writes. Default creates a missing key and fails with not_found if the file is missing. Set if_exists=true to soft-skip when the file is missing or the selector is not present (does not create the key). Single concrete path only (keys/indexes). For selector predicates or wildcards (items[name=foo].v, items[*].v) use doc_update / plan doc.update. Set if_exists=true to soft-skip a missing file or missing selector (does not create the key). Example: {"value":"2.0.0","path":"package.json","selector":"version"}

Set a new value at every location matching a selector. Use wildcards (items[*].enabled) or selector predicates (items[name=foo].v). Not a separate --where flag; the filter is part of the selector string. Multi-match writes: use selector predicates or wildcards (items[name=foo].v, items[*].enabled). Prefer this over doc_set when filtering by field. Example: {"value":7,"path":"config.toml","selector":"items[name=a].v"}

Execute a multi-step transaction plan atomically (MCP equivalent of `patchloom tx`). Provide an inline plan object or a plan_path. plan requires version and operations (alias ops). Each operation requires string op. Other plan and op fields are allowed. Call operation_schema with the op name for that operation's fields. Optional plan.cwd must be a relative path under the server workspace. Absolute plan.cwd and ../ escapes are rejected. Do not set both plan.cwd and for_each. plan.format/validate are ignored on MCP. Example: {"plan": {"version": 1, "operations": [{"op": "doc.set", "path": "app.yaml", "selector": "name", "value": "x"}]}}

Explain a tx plan in structured JSON (same as CLI `patchloom explain --json`). Provide inline plan text (`plan`) or a plan file (`path`). Format hint optional (json/yaml/toml). Read-only: does not execute the plan. Example: {"plan": "{\"version\": 1, \"operations\": [{\"op\": \"file.create\", \"path\": \"a.txt\", \"content\": \"x\"}]}"}

Normalize whitespace in a file or directory. A directory path expands with the same ignore-aware walker as CLI tidy fix (one write per text file). When op fields are omitted, defaults match CLI tidy fix (trim trailing whitespace + ensure final newline; mixed line endings flatten to the dominant style; uniform CRLF/LF stays). Set normalize_eol to keep to opt out of flattening. Precedence: defaults → plan write_policy → op fields. Plan write_policy is not re-applied at commit for paths last written by tidy.fix so op fields stick (#1840, #1847). Defaults: trim trailing whitespace and ensure final newline when those fields are omitted. Example: {"trim_trailing_whitespace":true,"path":"src/main.rs","ensure_final_newline":true}

Show uncommitted file changes vs git HEAD. Returns lists of modified, created, and deleted files. Omits .patchloom/ backup paths from --apply undo sessions. No parameters required.

Takes no parameters.

List files under the workspace (or given roots) with the same ignore/exclude/glob rules as search. Use this instead of a generic filesystem MCP list_dir/tree. Caps results (default max_results=500) and reports truncated+total_matched when capped. max_depth prunes the walk at each root (does not enter deeper dirs). max_results still counts all in-depth matches then truncates (total_matched remains honest). Prefer relative paths. Example: {"path": "src/", "exclude_patterns": ["target/**"], "max_results": 100, "max_depth": 3}

Remove later whole sections whose heading text+level already appeared (heading and body until next same-or-higher heading; unique second-section content is discarded). Removes later whole sections with the same heading level+text (body under the second heading is discarded, not merged).

Insert content immediately after a markdown heading line (before any existing body). For a sibling section after the full body, use md.insert_after_section. Inserts immediately under the heading line (before existing body). For a sibling ## section after the full body, use md_insert_after_section.

Insert content after the full section body (sibling placement). Use when adding a new ## section after this section's content. Prefer md.insert_after_heading for content under the heading line. Inserts after the full section body (sibling placement). Prefer md_insert_after_heading for content under the heading. Example: {"content":"## FAQ\n\nCommon questions.\n","path":"README.md","heading":"## Config"}

Insert content immediately before a markdown heading line.

Lint a markdown rules file for duplicate headings, dangerous git commands, and missing final newline. Returns object envelope {ok, path, issue_count, issues} (CLI lint-agents --json parity; not a bare array). isError stays false when issues are present; branch on ok / issue_count. Example: {"path": "AGENTS.md"}

Move a markdown heading section to a new position (same file reorder or cross-file). Exactly one of before or after is required. Omit to for same-file reorder. Example: {"path": "spec.md", "heading": "## Appendix", "to": "notes.md", "before": "## References"}

Replace the body of a markdown section identified by heading (section ends at the next same-or-higher-level heading; nested lower-level headings are included). Section ends at the next same-or-higher-level heading; nested lower-level headings are included in the replaced range. Prefer peer-level headings when siblings must survive. Example: {"content":"Run `npm install`.\n","path":"README.md","heading":"## Installation"}

Append a row to a markdown table under a heading. Example: {"row":"| GET | /health | Health check |","path":"README.md","heading":"## API"}

Insert or update a bullet point under a markdown heading. Idempotent: skipped if the bullet is already present. Example: {"bullet":"- Added new feature","path":"CHANGELOG.md","heading":"## Changes"}

Rename (move) a file. Use force=true to overwrite an existing destination. Example: {"to":"new.txt","from":"old.txt"}

Replace the source of one Jupyter notebook cell by its id. Pass the new cell body as one string. It is stored as an nbformat array of lines. Cell type, outputs, and the rest of the file stay put. A missing id is no_matches. A duplicate id is ambiguous. This does not run the cell. Address the cell by its id, not by index. source is the whole new cell body as one string. Does not run the cell. Example: {"source":"import pandas as pd\ndf.head()\n","path":"analysis.ipynb","cell_id":"load"}

Return the JSON schema for one plan operation. Pass op, for example doc.set. Use this for execute_plan field names. Does not run the operation. Example: {"op": "doc.set"}

Prepend content to an existing file. Inserts the file's line ending after the new text when that text does not already end with one. Example: {"content":"// Copyright 2026\n","path":"src/main.rs"}

Read file contents with optional line range. Optional lines range uses start:end (1-based).

Replace text in a file. Literal by default; set regex=true for regex. Options: nth, insert_before, insert_after, case_insensitive, multiline, if_exists, whole_line, range, word_boundary, fuzzy, min_fuzzy_score, allow_absent_old. Set word_boundary=true to match only whole words (prevents 'SetupFile' matching inside 'BenchSetupFile'). Set whole_line=true to replace entire lines containing a match (use with new="" to delete lines). Fuzzy: when exact old is absent, refuse by default even if score ≥ min_fuzzy_score (#1758); set allow_absent_old=true only for deliberate approximate recovery. Prefer ast_rename for identifiers. Example: {"path": "README.md", "old": "1.0.0", "new": "2.0.0"}. Insert after anchor (mutually exclusive with new): {"path": "src/main.rs", "old": "use std::io;", "insert_after": "use std::fs;"}

Search text files for a pattern (regex by default, use literal=true for exact match). Supports advanced layered ignores for LLM agents: globs (include), exclude_patterns, custom_ignore_filenames (e.g. .agentignore), max_results. Other options: files_with_matches, files_without_match, count, case_insensitive, multiline, invert_match, assert_count, before/after_context. Canonical multi-root field is paths (array); singular path is accepted as an alias for one root (same as paths:[path]). Example: {"pattern": "TODO", "paths": ["src/"], "literal": true, "custom_ignore_filenames": [".agentignore"], "exclude_patterns": ["target/**"], "max_results": 20}

Return server identity and workspace root: cwd, surface (full|core), tool_count, package version, MCP protocol_version from handshake, and optional recommendation (coding agents may prefer core). Prefer relative path parameters under cwd; absolute paths are allowed only when they resolve inside the workspace (AllowIfContained). Outside-workspace and ../ escapes are rejected.

Takes no parameters.

Scan files for missing final newline, mixed EOL, and trailing whitespace (CLI `tidy check`). Read-only: does not rewrite files. Canonical field is paths (array); singular path is accepted as an alias for one root. Empty issues is ok:true. Issues present still return a tool success with error_kind changes_detected. Example: {"path": "src/"}

List backup sessions created by --apply (including nested monorepo roots). Same as CLI `patchloom undo --list`. Returns items (timestamp, project_root, file_count, entries) plus warnings. Empty tree is error_kind no_matches. Example: {}

Takes no parameters.

Preview or restore files from a --apply backup session. Default is dry-run (applied:false, error_kind:changes_detected). Set apply=true to restore. Omit session to use the newest. Optional path[] restores only those session files (unknown path is no_matches). Paths stay inside the MCP workspace (AllowIfContained). Example: {"session": "<id-from-undo_list>", "apply": true}