Use this command to install Patchloom with WinGet:
winget install --id=Patchloom.Patchloom -e
Patchloom is a single-binary CLI tool designed to enable safe, structured file editing for AI coding agents. It simplifies operations like search and replace, unified diffs, parser-backed JSON/YAML/TOML document edits, markdown section modifications, AST-aware renames, multi-file transactions, and undo capabilities. Patchloom ensures consistency across Linux, macOS, and Windows.
Key Features:
Parser-Backed File Editing: Safely edit structured files like JSON, YAML, and TOML by selector without syntax corruption.
Multi-File Batch Edits: Combine multiple file operations into a single tool call to reduce round-trip times.
Markdown and AST Operations: Edit markdown sections and perform AST-aware code operations across 20 programming languages.
Atomic Transactions with Rollback: Ensure all changes are atomic, with strict rollback on failure.
MCP Server Integration: Expose Patchloom’s capabilities as structured MCP tool calls for seamless integration.
Cross-Platform Support: A single static binary that works identically on Linux, macOS, and Windows.
Target Audience and Benefits:
Ideal for developers and AI coding agents who need reliable, efficient file editing. Patchloom reduces the number of round-trips to AI models by batching operations, preserves syntax and comments in structured files, and ensures consistent behavior across platforms. Its MCP server enables seamless integration into existing workflows, while Winget deployment simplifies installation.
Patchloom is a critical tool for anyone automating code edits with AI, offering a robust solution that combines safety, efficiency, and cross-platform compatibility. Install Patchloom via Winget to streamline your development workflow and enhance collaboration between AI agents and structured files.
README
Patchloom
One binary. Every platform. Structured file edits for AI agents.
Patchloom is a single-binary CLI that gives AI coding agents safe, structured file editing on any operating system. It edits JSON, YAML, and TOML by selector (not regex), preserves comments, understands code structure across 20 languages, batches multiple file edits into one tool call, and works identically on Linux, macOS, and Windows.
Not a generic filesystem MCP. Default MCP filesystem servers read/write files as text. Patchloom adds dry-run previews, parser-backed config and markdown edits, AST ops, multi-file batch/tx with undo, and stable error_kind peels for hosts. Full coding agents (Claude Code, Codex, Cursor) own the loop; Patchloom is the tool layer they (or a Rust embedder) call.
# Edit a YAML value by selector without breaking comments or formatting
patchloom doc set config.yaml database.port 5432 --apply
# Batch 6 file edits into a single tool call
patchloom batch --apply <<'EOF'
doc.set package.json version "2.0.0"
doc.set config.yaml app.version "2.0.0"
doc.set config.toml project.version "2.0.0"
replace README.md "1.0.0" "2.0.0"
replace CHANGELOG.md "1.0.0" "2.0.0"
file.create VERSION "2.0.0"
EOF
AI agents edit files through tool calls. Each call is a round-trip back to the LLM. When a task touches config files, that process has three failure modes:
Syntax corruption. The agent uses text replacement on JSON, YAML, or TOML and produces invalid output (mismatched braces, broken indentation, lost comments).
Round-trip tax. Editing 6 files means 6 separate tool calls. Each one waits for the LLM to generate, execute, read the result, and plan the next call.
Platform fragmentation. On Linux the agent uses sed, jq, grep. On Windows, none of those exist. The agent falls back to verbose PowerShell or makes errors with unfamiliar syntax.
How patchloom solves each one
Problem
How patchloom solves it
Syntax corruption
doc commands parse the file, change the value by selector path, and write valid output. Comments and formatting are preserved. No regex needed.
Round-trip tax
batch and tx combine N operations into 1 tool call. Six file edits become one command with atomic rollback on failure.
Platform fragmentation
Single static binary with zero dependencies. Same commands, same flags, same behavior on Linux, macOS, and Windows.
Patchloom is not faster than native tools for simple, single-file edits. Use native tools for those. But native text replacement cannot safely edit structured files: a sed on YAML can corrupt indentation, strip comments, or produce invalid syntax. doc set parses the file, changes the value by selector, and writes valid output. That guarantee is the point.
Where patchloom is faster is multi-file batching. Six file edits via native tools means six round-trips to the LLM. One batch call does the same work in a single round-trip.
Benchmark details (Claude Opus 4 via Grok Build, 11 tasks)
MCP mode wins overall (228.5s vs 233.8s native) because structured tool calls skip shell syntax construction entirely. MCP wins 5/11 tasks; native wins 3/11; 3 are ties. CLI mode is always slowest due to shell construction overhead.
Install
Prefer channels that track each GitHub Release (Homebrew, Scoop, crates,
npm, Releases). On Windows, Scoop is recommended. winget
(Patchloom.Patchloom) is published per release and is usually current
after Microsoft's publish pipeline (winget source update if search is
stale). Chocolatey often lags while community moderation runs.
Pre-built binaries for Linux, macOS, and Windows are on the
Releases page.
See Installation for shell
installer scripts, source builds, shell completions, and winget /
Chocolatey notes.
The extension auto-discovers the CLI (or installs it for you), generates
AGENTS.md, configures MCP servers, and adds Quick Actions to the command
palette. See the Editor Extension guide for details.
Quick start
1. Set up your project
patchloom init
This creates AGENTS.md in a new project or appends the rules to an existing agent instructions file, offers shell completions, and detects MCP configuration opportunities. Pass -y to skip confirmation prompts.
If you only want the rules text:
patchloom agent-rules >> AGENTS.md
# Or tailor the output:
patchloom agent-rules --mode mcp >> AGENTS.md # MCP-only (no CLI examples)
patchloom agent-rules --platform windows >> AGENTS.md # Windows-only syntax
If .vscode/ or .cursor/ exists, init also prints ready-to-copy .vscode/mcp.json or .cursor/mcp.json snippets.
Your AI agent reads AGENTS.md and learns when to use patchloom vs native tools.
2. Edit a config file safely
# Parser-backed: changes the value, preserves comments and formatting
patchloom doc set config.yaml database.port 5432 --apply
tx plans are trusted input. format and validate run their cmd fields through the host shell (sh -c on Unix, cmd /C on Windows), so only run plans you trust.
4. Or use MCP for structured tool calls (no shell syntax)
MCP-capable agents call patchloom tools directly as structured JSON, with no shell quoting or command construction. The agent sends {"path": "config.json", "selector": "version", "value": "2.0"} instead of building patchloom doc set config.json version '"2.0"' --apply.
Coding agents: set PATCHLOOM_MCP_SURFACE=core for an 11-tool pack (list_files, search/read/replace, doc/md, execute_plan, server_info) so schemas stay small. Product default remains full inventory when the env is unset. Prefer Patchloom MCP alone for list+edit (no second filesystem MCP). See the MCP setup guide for Cursor / Claude / Codex paste configs and the full security model.
> Using VS Code, Cursor, or Windsurf? The Patchloom extension handles setup automatically: it installs the binary, runs init, and configures your editor's MCP settings.
As a Rust library
Host teams embedding Patchloom instead of a private edit stack: see the
embedder host case study
(for_agent, peels, fuzzy refuse, apply_fragment, path-only ops).
Add patchloom as a dependency (omit CLI/MCP/AST with default-features = false):
use patchloom::api::{self, ApplyMode, ReplaceOptions, edit_error_kind, EditErrorKind};
use std::path::Path;
// Replace text (preview only, no disk write)
let result = api::replace_text(
Path::new("src/config.rs"),
"old_value", "new_value",
&ReplaceOptions::default(),
ApplyMode::Preview,
None,
)?;
println!("{}", result.diff);
// Agent hosts: shared primary+fallback policy (unique, require_change, fuzzy @ 0.90)
let opts = ReplaceOptions::for_agent();
// Fail closed: zero matches become EditErrorKind::NoMatch
match api::replace_in_content("body", "missing", "x", &opts) {
Ok(r) => println!("changed={}", r.changed),
Err(e) => assert_eq!(edit_error_kind(&e), Some(EditErrorKind::NoMatch)),
}
// for_agent auto-refuses over-wide fuzzy; custom options use api::fuzzy_span_suspicious
// Buffer multi-op + host write: api::refuse_batch_if_suspicious_fuzzy after apply_content_edits
// Invalid options and bad regex peel InvalidInput (CLI/tx typed errors included)
match api::replace_in_content("body", "", "x", &ReplaceOptions::default()) {
Err(e) => assert_eq!(edit_error_kind(&e), Some(EditErrorKind::InvalidInput)),
Ok(_) => panic!("empty pattern must error"),
}
// Set a value in a JSON file
api::doc_set(
Path::new("config.json"),
"version",
serde_json::json!("2.0"),
ApplyMode::Apply,
None,
)?;
// Multi-doc YAML: merge into document 0 (selector None = root only)
api::doc_merge(
Path::new("stream.yaml"),
serde_json::json!({"env": "prod"}),
ApplyMode::Apply,
None,
Some("0"),
)?;
// Sole-path text load: binary → EditErrorKind::Binary; invalid UTF-8 → InvalidEncoding
let _text = api::load_text(Path::new("notes.md"))?;
All API types are Send + Sync. Beyond the api module, utility modules are also public: containment (workspace path guarding), exec (shell command execution), files (file-walking, load_text_strict, binary detection), backup (restore_path_from_latest_backup for post-Apply validate/revert), and write (atomic file writes with policy transformations). Library users needing temp dirs (e.g. agents) can use PathGuard::builder(cwd).allow_temp_directory() (handles /tmp on macOS); see the containment and api module rustdocs. Multi-doc bare keys and wrong-root merges peel to EditErrorKind::TypeError via edit_error_kind. Create/rename dest-exists peels to EditErrorKind::AlreadyExists (or api::is_already_exists / api::error_kind_str for CLI-stable "already_exists" strings). Fine-grained kinds also have bool peels (is_not_found, is_conflicts, is_changes_detected, is_type_error, is_format_failed, is_guard_rejected, is_invalid_input, is_no_match, is_ambiguous) matching edit_error_kind.
Replace fail-closed / shell-token options: CLI replace --require-change and --command-position (also plan/MCP fields and ReplaceOptions on the library). Agent hosts: ReplaceOptions::for_agent() on primary and fallback replace paths (auto span refuse); custom options still call api::fuzzy_span_suspicious / FuzzySpanPolicy after fuzzy Apply; buffer multi-op hosts call api::refuse_batch_if_suspicious_fuzzy after apply_content_edits (#2064). Library-only AST mutators: ast_rename / ast_replace_in_symbol / ast_rename_batch (feature ast + files), and FunctionSigEdit::parse_rust. Ordered host onboarding: Embedder host checklist (#2009). Full surface: docs.rs/patchloom.
Fast literal or regex search across text files (supports --glob/--exclude/--ignore-file for layered custom ignore files, --max-results, -C context, etc.)
replace
Mechanical string replacement across text files with diff preview
apply-fragment
Freeform fragment with required anchors (MorphLLM-style markers stripped; no cloud merge)
patchloom adds parser-backed structured edits; batching; never produces invalid JSON/YAML
comby
Structural code patterns
patchloom targets config files and agent workflows, not source code pattern matching
The key difference: patchloom is designed for AI agent workflows. One batch or tx call replaces N sequential tool calls, cutting round-trips and eliminating partial-failure states.
vs agent-native editing tools
The table above compares patchloom to human CLI tools. But agents already have built-in editing: Claude Code's edit_file, Cursor's apply, Grok Build's search_replace, Aider's /code blocks. Why add patchloom on top?
Agent-native tools use text matching. They find a block of text and replace it. This works for source code but fails on structured config files:
The agent replaces port: 5432 with port: 5433. Result depends on implementation. Many agents lose the inline comment, break indentation, or fail to match because of surrounding context changes.
Agent uses patchloom doc set
patchloom doc set config.yaml \
database.port 5433 --apply
The YAML parser changes the value at the selector path. Comments, indentation, key ordering, and all other formatting are preserved. The output is always valid YAML.
Limitation of agent-native tools
How patchloom addresses it
Comment destruction
CST-level YAML/TOML editing preserves all comments
One file per tool call
batch/tx edit N files in 1 call (6.7x faster in benchmarks)
No rollback
tx with strict: true reverts all files if validation fails
Platform-dependent
Same binary and syntax on Linux, macOS, Windows
Stale context risk
patch apply uses fuzz matching to handle context drift
When to keep using native tools: Single-file reads, simple text search, single-file text replacement where comments don't matter. Patchloom's agent-rules tell agents exactly when to use each approach.
Official MCP Registry name io.github.patchloom/patchloom (stdio; crates.io / npm packages; see server.json). Local MCPB for Smithery / desktop hosts: make pack-mcpb (mcpb/). Glama listing (glama.json; keep description aligned with server.json, see MCP setup)
For local verification before opening a pull request, run make check. It matches the main Linux CI gate: formatting, clippy, unit tests (including feature-matrix jobs), integration tests, PTY tests, release-notes structure, test hygiene, and generated-doc freshness (check-patchloom-md, check-readme). While iterating locally, make check-fast is the same except it skips only check-patchloom-md (it still runs check-readme so a drifted test-count badge fails before CI).
All commits must be signed off with git commit -s.
Agent integration tests
make agent-test runs 19 pytest scenarios that verify AI agents correctly use patchloom when given instructions. make bench-agent runs 3-way benchmarks (CLI vs MCP vs native) across 11 tasks. Use MODEL=X to switch models and RUNS=N for variance reduction. Requires an LLM API key. Not part of make check. See tests/agent/README.md for details.
Security
For current security reporting guidance, see SECURITY.md.
