SuperAPI AI Directory
Partner with us中文AI newsFavorites
All toolsAI codingpatchloom

patchloom

Structured file edits for agents: JSON, YAML and TOML by selector, Markdown and AST edits, dry runs and multi-file transactional batches.

Open website

About this tool

Purpose

Patchloom is a single-binary CLI that provides AI coding agents with safe, structured file editing capabilities and runs on any operating system. It edits JSON, YAML, and TOML based on selectors (rather than regex), preserves comments, understands the code structure of 20 languages, can merge multiple file edits into a single tool call, and behaves consistently on Linux, macOS, and Windows.

It is not a general-purpose filesystem MCP. The default MCP filesystem server reads and writes files as text. Patchloom adds dry-run previews, parser-backed configuration and Markdown editing, AST operations, multi-file batch/transactions with undo, and stable error_kind stripping for hosts. The full coding agent (Claude Code, Codex, Cursor) handles the loop; Patchloom is the tool layer they (or Rust embedders) call.

Key Capabilities

AI agents edit files through tool calls, and each call is a round trip back to the LLM. When the task involves configuration files, this process has three failure modes:

  • Syntax corruption: agents use text replacement on JSON, YAML, or TOML, producing invalid output (mismatched brackets, broken indentation, lost comments).
  • Round-trip tax: editing 6 files means 6 separate tool calls, each requiring waiting for the LLM to generate, execute, read the result, and plan the next call.
  • Platform fragmentation: on Linux, agents use sed, jq, grep; on Windows, none of these exist, and agents fall back to verbose PowerShell or make mistakes using unfamiliar syntax.

Patchloom solves these problems through structured editing, batch calls, and cross-platform consistency.

Key capabilities include:

  • Editing JSON, YAML, and TOML via selectors, preserving comments and formatting.
  • Parser-backed Markdown editing.
  • AST operations across 20 languages.
  • Multi-file batch/transactions (batch / tx) with undo.
  • Dry-run previews.
  • Stable error_kind stripping for easier host handling.
  • MCP mode, supporting structured tool calls without shell syntax.

Usage

Installation

PrebuiltBuild binaries are available for Linux, macOS, and Windows on the Releases page. Installation methods include Homebrew, Scoop, crates, npm, Releases, and more. On Windows, Scoop is recommended. winget (Patchloom.Patchloom) is released per version and usually stays up to date after the Microsoft release pipeline (if search is stale, run winget source update). Chocolatey tends to lag during community review.

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 automatically discovers the CLI (or installs it for you), generates AGENTS.md, configures the MCP server, and adds Quick Actions to the command palette.

Quick start

  1. Set up the project: run the init command to create AGENTS.md in a new project, or append rules to an existing agent instruction file, provide shell completion, and detect MCP configuration opportunities. Use -y to skip confirmation prompts. If you only need the rule text, you can get it separately. If .vscode/ or .cursor/ exists, init also prints a ready-to-copy .vscode/mcp.json or .cursor/mcp.json snippet. After your AI agent reads AGENTS.md, it will know when to use patchloom versus native tools.

  2. Safely edit configuration files: use the doc set command to modify values via selectors; the parser preserves comments, indentation, key order, and other formatting, and the output is always valid.

  3. Batch multiple edits into a single call: values are JSON-first, and an unquoted 2.0 becomes a number. In a Unix shell, you can force it to be a string with nested quotes. In Windows PowerShell (no bash heredoc), write the operations to a file. Or use a JSON plan with format and validate for the lifecycle. Note: 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): after installing MCP support, start the server. MCP-capable agents call patchloom tools directly with structured JSON, with no shell quoting or command construction. The agent sends {"path": "config.json", "selector": "version", "value": "2.0"} instead of constructing patchloom doc set config.json version '"2.0"' --apply. Coding agents can set PATCHLOOM_MCP_SURFACE=core to get a 12-tool kit (list_files, search/read/replace, doc/md, execute_plan, operation_schema, server_info), keeping the schema lean. When the environment variable is not set, the product still defaults to the full manifest. It is recommended to use only the Patchloom MCP for listing + editing (no need for a second filesystem MCP).

As a Rust library

Host teams that want to embed Patchloom instead of a private editing stack can refer to the embedder host case study (for_agent, peels, fuzzy refuse, apply_fragment, path-only operations). Add patchloom as a dependency (use default-features = false to omit CLI/MCP/AST). All API types are Send + Sync. In addition to the api module, the tools module is also public: containment (workspace path guard), exec (shell command execution), files (file traversal, load_text_strict, binary detection), backup (restore_path_from_latest_backup for post-Apply verification/rollback), write (with policyAtomic file writes for conversions). Library users who need a temporary directory (such as agents) can use PathGuard::builder(cwd).allow_temp_directory() (handles /tmp on macOS).

Applicable scenarios

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

  • Correctness takes priority over speed: For simple single-file edits, Patchloom is not faster than native tools, and native tools should be used. But native text replacement cannot safely edit structured files: running sed on YAML may corrupt indentation, strip comments, or produce invalid syntax. doc set parses the file, changes values through selectors, and writes valid output; this guarantee is precisely its point.
  • Multi-file batching is faster: Six file edits through native tools means six LLM round trips. A single batch call can do the same work in a single round trip.
  • MCP mode wins overall (228.5s vs 233.8s native), because structured tool calls skip shell syntax construction entirely. MCP won 5 out of 11 tasks; native won 3; 3 were ties. CLI mode is always the slowest due to shell construction overhead.

When to keep native tools: single-file reads, simple text searches, single-file text replacement where comments are irrelevant. Patchloom's agent rules tell agents when to use each method.

Limitations

  • For simple, single-file edits, Patchloom is not faster than native tools.
  • CLI mode is always the slowest due to shell construction overhead.
  • tx plans are trusted input; format and validate will run their cmd fields through the host shell, so only trusted plans should be run.
  • Some installation channels (such as Chocolatey) may lag.
  • Official materials do not provide detailed information on fees, pricing, or platform restrictions.

Status

5800+ tests, covering 25 commands. Tested with Grok 4.3, GPT-5.4, and Claude Opus 4.6. For the full command reference, see Command Reference (also available at docs/reference/README.md). License: MIT or Apache License, Version 2.0, at your option.

Related tools

Browse category