Patchloom

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

[Why Patchloom?](#why-patchloom) | [Install](#install) | [Quick start](#quick-start) | [Commands](#commands) | [Comparison](#how-patchloom-compares) | [When to use what](#when-to-use-what) | [Architecture](#how-it-works-with-your-ai-agent) | [Status](#status)

---

Why Patchloom?

The problem

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:

1. Syntax corruption. The agent uses text replacement on JSON, YAML, or TOML and produces invalid output (mismatched braces, broken indentation, lost comments).
2. 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.
3. 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

What changes with patchloom

Without patchloom (6 tool calls)

Agent: edit file 1  ─── tool call ───▶  15s

Agent: edit file 2 ─── tool call ───▶ 15s Agent: edit file 3 ─── tool call ───▶ 15s Agent: edit file 4 ─── tool call ───▶ 15s Agent: edit file 5 ─── tool call ───▶ 15s Agent: edit file 6 ─── tool call ───▶ 15s Total: ~90s

With patchloom batch (1 tool call)

Agent: batch with

all 6 edits ─── tool call ───▶ 25s

5 round-trips saved Total: ~25s

Key capabilities

When to use patchloom vs native tools

Patchloom is not a replacement for all file operations. Its instructions tell agents exactly when to use it and when native tools are faster:

Correctness over speed

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)

Task                    PL-CLI    MCP    Native

────────────────────── ────── ────── ────── search 18.5s 12.7s 13.9s ◀ ~same replace 36.1s 26.6s 26.1s ◀ ~same doc_set 30.9s 16.9s 13.7s ◀ native fastest md_table 15.5s 13.5s 15.3s ◀ MCP fastest tx_multi_file 41.4s 28.5s 22.9s ◀ native fastest batch_6_files 50.6s 46.6s 30.3s ◀ native fastest batch_mixed_ops 24.7s 13.6s 20.9s ◀ MCP fastest yaml_comment_preserve 18.1s 11.6s 16.1s ◀ MCP fastest md_insert 15.0s 11.7s 15.7s ◀ MCP fastest file_ops 26.0s 16.6s 17.2s ◀ ~same tidy 45.0s 30.3s 41.7s ◀ MCP fastest ────────────────────── ────── ────── ────── TOTAL 321.9s 228.5s 233.8s

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.

# Homebrew (macOS/Linux)

brew install patchloom/tap/patchloom

crates.io (requires Rust 1.95+, includes MCP server)

cargo install patchloom

npm / npx (downloads the platform binary from GitHub Releases)

npx patchloom --version

or: npm install -g patchloom

# Scoop (Windows; recommended Windows channel)

scoop bucket add patchloom https://github.com/patchloom/scoop-bucket scoop install patchloom/patchloom

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.

• MCP Registry name: mcp-name: io.github.patchloom/patchloom

Editor extension

Install the companion extension for VS Code, Cursor, Windsurf, or VSCodium:

• VS Code Marketplace
• Open VSX Registry

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 a