Patchloom for VS Code

The official VS Code extension for Patchloom. Set up your workspace for AI agent workflows in seconds: detect the CLI, generate agent rules, configure MCP servers, and run structured file operations from the command palette.

---

Install

Install from the VS Code Marketplace or the Open VSX Registry.

Or search for Patchloom in the Extensions view (Ctrl+Shift+X / Cmd+Shift+X).

Get started in 30 seconds

1. Install the Patchloom CLI (or run Patchloom: Install Patchloom from the command palette; recommended: tracks GitHub Releases with checksum verification)

   brew install patchloom/tap/patchloom          # macOS / Linux (Homebrew)
   npm install -g patchloom                      # npm (Node.js; on Windows this is a patchloom.cmd shim)
   curl -LsSf https://github.com/patchloom/patchloom/releases/latest/download/patchloom-installer.sh | sh  # shell script
   cargo install patchloom                        # from source
   scoop bucket add patchloom https://github.com/patchloom/scoop-bucket
   scoop install patchloom                        # Windows (Scoop; preferred PATH channel)

   On Windows, prefer the extension managed installer or Scoop. npm install -g patchloom is supported: it puts patchloom.cmd on PATH, and the extension launches that shim through cmd.exe. A path that ends in a backslash is quoted so cmd.exe does not swallow the next argument. If Show Status says spawn EINVAL, the extension build is one that does not launch .cmd shims. Avoid winget and Chocolatey for install or upgrade: both lag GitHub Releases and often leave you on an old CLI. The extension activates when the window finishes starting, including in a folder that has no AGENTS.md yet. Hiding the status bar does not hide the command palette entries.
2. Open a project and run Patchloom: Setup Workspace

The extension finds the CLI automatically. If it's not on PATH, point patchloom.path to it in settings.

---

Features

One-click workspace setup

Run Patchloom: Setup Workspace to walk through everything your project needs: binary detection, AGENTS.md generation, and MCP server configuration. In a multi-root window it asks for the folder once and uses that folder for both steps. Skipping a step still ends with a summary of what was already present, what ran, and what was skipped.

Agent rules generation

Patchloom: Initialize Project generates an AGENTS.md file from patchloom agent-rules. You pick integration mode (CLI/MCP/all), shell platform, and surface (full document or core pack for system-prompt injection, CLI 0.24+). On CLI 0.29+, --surface core honors --mode the same way the full surface does. If AGENTS.md already exists, the extension opens a diff so you can merge updates manually.

MCP server configuration

Patchloom: Configure MCP injects the Patchloom MCP server into your editor's config. Supports:

• VS Code (.vscode/mcp.json, key servers)
• Portable workspace (.mcp.json, key mcpServers). Prefer this file for current VS Code and Copilot. The Agent Host reads it directly. The entry sets "type": "stdio".
• Cursor (.cursor/mcp.json)
• Windsurf (~/.codeium/windsurf/mcp_config.json)

When configuring, pick Full tool inventory (default) or Core pack. Core sets PATCHLOOM_MCP_SURFACE=core on the server entry. Workspace files (VS Code, portable, and Cursor) store command as patchloom, not a machine path. A stale absolute path is rewritten. The Windsurf user file may still store the resolved binary path. VS Code also starts a native Patchloom server. Writing .vscode/mcp.json adds a second server next to that provider, and the command asks before it writes that file. Skip that file continues with the other selected configs. Dismissing the question cancels the command and writes nothing. The native server follows the patchloom.mcpSurface setting (full or core). Existing servers in JSON or JSONC (// comments, trailing commas) stay in the file. A config that is not an object is left unchanged and the command reports an error. If an existing file cannot be read, the command reports that error and does not replace it. A missing file is still created.

CLI 0.37.5 exposes 66 MCP tools by default (including explain_plan, tidy_check, list_files, apply_fragment, notebook_edit, and operation_schema). The core pack is 12 tools on CLI 0.37+: read_file, search_files, list_files, replace_text, batch_replace, doc_get, doc_set, doc_query, md_replace_section, execute_plan, operation_schema, server_info. doc accepts .jsonc (comments stay on set), plus .env, .ini, and .properties. doc_set accepts if_exists to skip a missing file or selector. apply_patch accepts apply=false for a check-only preview. CLI list-files inventories ignore-aware paths the same way as MCP list_files. search_files accepts files_without_match (CLI 0.29+). apply_patch accepts unified diffs, Codex *** Begin Patch, and Aider SEARCH/REPLACE (CLI 0.30+). doc_query can list object keys and count array or object length (CLI 0.32+). Search, replace, and tidy dests accept cwd-only globs such as *.txt (CLI 0.33+; use **/*.txt or --glob for nested files). Absolute paths that resolve inside the MCP workspace root are allowed; empty paths, ../, and outside paths still reject with stable error_kind peels.

Status bar

The status bar shows MCP and binary readiness at a glance:

• $(plug) Patchloom, with the detected version when known ($(plug) Patchloom v0.37.5), when an MCP config file is configured
• $(check) Patchloom, with the detected version when known, when the binary is ready and MCP is not configured
• $(warning) Patchloom when the binary is missing or needs an upgrade

Click it to run Show Status. That command writes the full report to the Output channel and shows one short line, plus a button when a fix is available. Install does not download until you pick that button. The plug icon means a workspace MCP file is configured. A Windsurf user file alone does not turn on the plug icon, but Show Status still lists it. Saving AGENTS.md, .mcp.json, .vscode/mcp.json, or .cursor/mcp.json, focusing the window, or running Refresh Status updates the item.

Verify MCP Server

Patchloom: Verify MCP Server runs in the workspace folder. If a workspace MCP file names a command, that command is the one probed. With no config file, it probes the resolved CLI. It sends a JSON-RPC initialize handshake and reports the server name and version on success, or a diagnostic error on failure. A bad configured command fails the check.

Quick actions

Patchloom: Quick Action opens an interactive picker with structured editing operations:

Action	What it does
Replace text	Literal text replacement with diff preview before applying
Insert text after match	Line-oriented insert after each match (CLI 0.16+)
Insert text before match	Line-oriented insert before each match (CLI 0.16+)
Apply fragment at anchor	Morph-style freeform fragment at a unique anchor (--after / --before / --old, CLI 0.22+)
Tidy file	Whitespace and newline cleanup with diff preview
Set structured value	Update a JSON, JSONC, YAML, TOML, .env, INI, or .properties key with diff preview
Update matching structured values	Update matching nodes in those formats (doc update, CLI 0.27+)
Search text	Find pattern matches across workspace files (results in output channel)
Search files without match	List files that do not contain the pattern (search -L, CLI 0.29+)
Create file	Scaffold a new file with optional content and open it in the editor
Append to file	Append content to an existing file
Prepend to file	Prepend content to the start of an existing file (CLI 0.9+)
Read structured value	Read a JSON, JSONC, YAML, TOML, .env, INI, or .properties key and copy to clipboard
List structured keys	List object keys at a selector (doc keys, CLI 0.32+; . is the document root)
Count structured length	Count array items or object keys (doc len, CLI 0.32+)
Delete structured value	Remove a key from JSON, JSONC, YAML, TOML, .env, INI, or .properties with diff preview
Delete matching array items	Remove array items matching a predicate (doc delete-where, CLI 0.27+; array path plus key=value predicate)
Merge into structured file	Merge a partial JSON object into a config file (optional multi-doc selector, CLI 0.16+)
Append to array	Append a value to a JSON, JSONC, YAML, TOML, .env, INI, or .properties array
Prepend to array	Prepend a value to a JSON, JSONC, YAML, TOML, .env, INI, or .properties array
Ensure structured value	Idempotent set: write only if the key is missing. A wildcard or predicate is refused (CLI 0.37.4+)
Move/rename key	Move or rename a selector path. An existing destination is already_exists and is not overwritten (CLI 0.37.3+)
Insert after heading	Insert content immediately after a markdown heading line
Insert after section	Insert a sibling markdown section after a full section body (CLI 0.14+)
Insert before heading	Insert content immediately before a markdown heading line
Append table row	Append a row to a markdown table under a heading
Upsert bullet	Add a bullet under a heading if it is not already present. It stays above a child heading (CLI 0.37.3+)
Replace markdown section	Replace content under a markdown heading
Apply patch (unified / Begin Patch / SEARCH-REPLACE)	Apply a unified diff, Codex Begin Patch, or Aider SEARCH/REPLACE (patch apply, CLI 0.30+)
Merge patch (three-way)	Apply a stale patch using three-way merge (v0.2.0+)
Undo last change	Restore the latest backup, one session id, or one workspace path

Content fields open a scratch file so newlines stay newlines. Pattern and anchor fields start with the current selection when it is a single line. Preview copies the file under the workspace and runs the CLI with the workspace as its working directory, so .patchloom.toml format commands and EditorConfig match Apply. The preview copy is removed afterward. The diff uses a patchloom-preview document, which is not an untitled buffer and is not saved. Unsaved edits must be saved before that preview. If the file changes while the preview is open, Apply stops and asks for a new preview. A preview that finds no pattern says so. A command that exits cleanly and changes nothing says the command made no edit. Search still writes its text to the Output channel, and then offers the hits in a list that opens the file at the matching line. Files without a match open at line 1.

Workspace Quick Actions and Batch Apply pass --contain so CLI paths stay inside the workspace root (CLI 0.10+). Containment is relative to the effective working directory (the workspace folder). Patch apply and patch merge ask for a file or the clipboard, copy that text under .patchloom/ (already gitignored), show a dry run, and write only after a second confirmation. A dry run that would change files exits 2 with ok: true and applied: false. That result still reaches the write confirmation. A bad patch or a stale hunk stops before that confirmation. A three-way merge that conflicts, when conflict markers were not allowed, also stops. Nothing is written. Run it again and choose Allow conflict markers to write them. An empty clipboard is an error and does not write. Cancel leaves the files unchanged. A path inside that patch that leaves the workspace is rejected.

Batch operations

Patchloom: Batch Apply opens a line-oriented plan whose example lines are comments, including replace, fuzzy replace, doc.set, JSONC doc.set, multi-match doc.update, doc.delete_where, multi-doc doc.merge, file append, directory file.rename, markdown section inserts, and tidy. Remove the leading # on the lines you want. Apply first runs the plan without --apply and shows that result. A preview that would change files exits 2 with ok: true and applied: false, including when another replace in the same plan is refused. That dry run still offers the write confirmation. A parse error or a plan that matches nothing does not. Confirming the write runs that same plan with --apply. If the open plan changed after the dry run, Apply stops and asks for another dry run. A hard error rolls the plan back. A formatter failure (format_failed) does not: that write may already be on disk, and Undo restores it. A replace that matches nothing, or a structured delete that removes nothing, is reported, other successful writes stay, and the completion message names those operations. A line whose first non-whitespace character is # is a comment. Blank lines and comments are not operations. A plan that contains only those lines is not applied.

Output channel

Search hits, search -L, undo restore details, patch-merge results (including failures), and batch-apply results always appear in the Patchloom output channel. Diagnostic command traces (invocations, arguments, and other CLI I/O) follow patchloom.trace.server (off by default; set verbose to dump every command). Run Patchloom: Show Output to open it.

Compatibility diagnostics

The extension detects outdated CLI builds and warns with upgrade guidance. It requires Patchloom 0.3.0 or newer.

---

Commands

Command	Description
Patchloom: Setup Workspace	Guided walkthrough for binary, AGENTS.md, and MCP readiness
Patchloom: Initialize Project	Generate or diff AGENTS.md from patchloom agent-rules (mode, platform, surface full/core)
Patchloom: Configure MCP	Inject Patchloom MCP server config (full or core tool surface) into editor config files
Patchloom: Quick Action	Build a Patchloom CLI command from an interactive picker
Patchloom: Batch Apply	Open a batch plan, apply it, and report refused operations
Patchloom: Show Output	Open the Patchloom output channel for CLI logs and diagnostics
Patchloom: Show Status	Write the full readiness report to the Output channel and show one short line
Patchloom: Refresh Status	Re-check the CLI and workspace files and update the status bar
Patchloom: Verify MCP Server	Probe the configured MCP command, or the resolved CLI, with a JSON-RPC initialize request
Patchloom: Install Patchloom	Download and install the Patchloom CLI with checksum verification
Patchloom: Update Patchloom	Check for a managed update, ask before download, then install
Patchloom: Reinstall Patchloom	Re-download and reinstall the managed Patchloom binary
Patchloom: Open Settings	Jump to Patchloom extension settings
Patchloom: Open Documentation	Open the Patchloom documentation site in a browser
Patchloom: Open Releases	Open the Patchloom releases page in a browser

Settings

Setting	Default	Description
patchloom.path	""	Absolute path to the Patchloom binary. When empty, the extension searches PATH and then the managed install location.
patchloom.showStatusBar	true	Show the status bar item. Hiding it does not hide command palette entries. Click runs Show Status.
patchloom.enable	true	Enable the extension. When disabled, the status bar is hidden and automatic update checks are skipped. Command palette entries stay available.
patchloom.mcpSurface	"full"	Tool pack for the native MCP server (full or core).
patchloom.trace.server	"off"	Diagnostic CLI trace level (off, messages, verbose). User-facing search, undo, patch-merge, and batch-apply streams always go to Output.
patchloom.env	{}	Extra PATCHLOOM_* variables for the CLI (for example {"PATCHLOOM_LOG": "debug"}). Workspace values apply only in a trusted folder.
patchloom.managedInstall.autoUpdate	true	Automatically check for CLI updates on activation.

---

Remote and multi-root workspaces

• In multi-root workspaces, commands target the active editor's workspace folder. If no editor is active, you pick the folder.
• Remote sessions (WSL, SSH, dev containers, Codespaces) stay focused on workspace-scoped flows. User-scoped MCP config targets are hidden in remote environments.
• Unknown remote environments are surfaced as unverified so failures are explicit.

---

Troubleshooting

Patchloom not found Set patchloom.path in settings, or add the CLI to your PATH.

CLI compatibility warning / upgrade path The extension requires Patchloom 0.3.0 or newer; 0.37.5 is recommended. Which fix to use depends on how the CLI was resolved (status shows Source):

1. Source: managed install → Patchloom: Update Patchloom (checksum-verified GitHub release into extension storage)
2. Source: PATH → upgrade that install in place (Scoop scoop update patchloom on Windows; Homebrew / npm / cargo / the official installer elsewhere). Managed Install will not override a PATH binary.
3. Source: patchloom.path → Open Settings and point at a current binary, or clear the setting so PATH/managed resolution can take over

Do not rely on winget or Chocolatey to stay current. Those community packages lag moderation and Microsoft publish, so upgrades often stay stuck on older CLI versions.

Path rejected by workspace guard Quick Actions and Batch Apply pass --contain so paths stay inside the open workspace folder. On CLI 0.18+, sandbox escapes report error_kind: guard_rejected (not a generic invalid_input). Keep targets under the workspace root, or open the folder that owns the files.

Empty or blank path On CLI 0.28+, empty, whitespace-only, or format-character-only paths fail early with error_kind: invalid_input and message path must not be empty (they no longer look like workspace-root failures). Prefer a real relative or workspace-absolute path.

Create or rename parent is not a directory On CLI 0.31+, create and rename check each parent of the destination before staging. A parent that is a regular file (or a dangling / file symlink) reports error_kind: invalid_input and parent path is not a directory. Create the missing directory first, or pick a destination whose parents are directories.

Numeric or negated doc selector On CLI 0.30+, selectors accept !=, >, >=, <, <=, and [!key] (for example servers[port>8000]). A non-numeric compare reports error_kind: invalid_input. Use a number on the right-hand side, or a concrete index path.

Search files without match On CLI 0.29+, search -L / --files-without-match lists files that do not contain the pattern. Combining it with --files-with-matches or --count is invalid_input. When that list is empty, the CLI exits 3 with error_kind: no_matches and no files without matches for 'PATTERN' in SCOPE. An empty folder, a glob that matches nothing, and a folder where every file contains the pattern all look the same. The Quick Action says no files lack the pattern. On CLI 0.37.1, search --files-without-match --assert-count counts the files listed. The Quick Action does not pass --assert-count. An exclude pattern such as _* no longer skips every directory; directories that still contain files you asked to edit are walked.

YAML mapping alias stayed an alias On CLI 0.31+, doc set on a mapping that is only service_a: *shared writes a merge key plus local fields (<<: *shared and your new keys) instead of inlining the whole object. Sequence items (- *shared) still expand or stay not-applied. CLI 0.32+ also keeps the merge key when you grow an inherited array, delete an inherited field, or write an empty object.

On CLI 0.32+, List structured keys and Count structured length run doc keys and doc len. Use . for the document root. An array on doc keys is type_error. A wildcard or predicate (items[*]) is ambiguous.

On CLI 0.33+, a search, replace, or tidy dest of *.txt matches files in the current directory only. sub/*.txt stays in that directory. Use **/*.txt or --glob '*.txt' when you want nested files. That dest glob is not the same as the Search Quick Action --glob field, which still walks nested files.

Empty or whitespace-only edit payload On CLI 0.34+, empty or whitespace-only create, replace, markdown, rename, and AST mutate payloads report error_kind: invalid_input instead of writing junk. "\n" still writes a blank-line file. Empty "" create still writes a 0-byte file.

Invalid dest or --glob On CLI 0.34+, a bad dest glob or --glob is error_kind: invalid_input (not a parse error), so --json callers can switch on error_kind.

AST parse timed out On CLI 0.34+, an AST parse that runs longer than five seconds reports error_kind: parse_timeout and exit 4. Narrow the file or pick an explicit language. Unknown explicit language is invalid_input.

JSONC and key-value documents On CLI 0.35+, Quick Actions accept .jsonc (comments stay on doc set), plus .env / .env.*, .ini, and .properties. Use doc --as when the extension is not enough. .properties keys are flat (a name like app.name is one key, not nested app then name); run List structured keys to see the literal names.

Directory rename and undo On CLI 0.35+, rename moves a real directory and undo puts it back. Dry-run undo reports the rename-back without writing. Batch plans use file.rename FROM TO.

Doc set if the key already exists On CLI 0.35+, doc set --if-exists (MCP doc_set.if_exists) succeeds and writes nothing when the file or selector is missing. Ensure structured value is the inverse: write only when the key is absent.

Undo one path from a session On CLI 0.35+, undo --path restores only those session paths. An unknown path is error_kind: no_matches and does not restore the rest of the session.

SEARCH/REPLACE and Begin Patch markers On CLI 0.36+, a SEARCH/REPLACE document with CRLF line endings matches an LF file. A trailing *** on Begin Patch, End Patch, and dest markers is ignored. Dest-less SEARCH/REPLACE is still invalid_input on the CLI and on MCP. Pass a dest line.

INI and properties values On CLI 0.37+, doc set on .properties and .ini writes the value as text. It does not wrap the value in quotes. A leading space is escaped. doc get returns that text.

Replace a markdown section On CLI 0.37+, md replace-section keeps a body line whose text matches the heading. A leading # Title in the replacement is still removed so the heading is not duplicated.

Notebook cells and plan hashes On CLI 0.37+, MCP notebook_edit replaces one Jupyter cell's source by cell_id and leaves the cell type and outputs. A missing id is no_matches. Two cells with the same id are ambiguous. There is no Quick Action for this. Plan read can return sha256 of the whole file. expected_sha256 on the plan map refuses the plan with stale and writes nothing when that hash does not match. On CLI 0.37.2+, the same key on one operation warns and the write still happens. agent_preset: true on a plan forces unique replace with a fuzzy floor of 0.90. A command_position replace stays an exact command-token match.

Smaller execute_plan schema On CLI 0.37+, the published execute_plan schema lists version and operations. Fetch one operation's fields with operation_schema. The server still accepts ops in place of operations. The full inventory is 66 tools. The core pack is 12 and includes operation_schema.

Tidy a directory On CLI 0.37+, plan tidy.fix on a directory includes dotfiles such as .gitignore. .git is still skipped.

Formatter timeout On CLI 0.37.1, a post-write formatter that exits non-zero, or that runs past its deadline (30 seconds unless you set another value), exits 1 with error_kind: format_failed. Closing stderr, or leaving a background process holding stderr, does not drop that deadline. The same deadline applies to --format, [defaults] format, [format] command, and [format.by_extension]. The file may already be written. The error names a backup session and says to run patchloom undo. Patchloom: Undo last change restores it. Quick Actions and Batch Apply wait 45 seconds so this error can come back. A format deadline longer than that can still be cut off. A per-extension formatter that exits non-zero still warns, and the write stays.

Format commands outside a git repository On CLI 0.37.1, write policy from a parent .patchloom.toml still applies when there is no .git directory above the start path. Format commands from that parent ([defaults] format, [format] command, auto, and by_extension) are dropped. A symlink .patchloom.toml is refused and its target is not read. A parse error names the config path and the first error line. Put the format command in the working directory or in the repository root.

Literal $ in replacement text On CLI 0.37.1, the Replace text Quick Action keeps $ as text. On the CLI, regex mode still treats $1 as a capture. On CLI 0.37.5, replace --regex refuses a group the pattern does not contain (replacement group $9 is not in the pattern when the pattern is (a)). That is invalid_input and the file stays unchanged. Regex and whole-line matches honor before_context and after_context.

Incomplete patch hunk On CLI 0.37.1, a hunk that ends before its line counts are satisfied is error_kind: parse_error (exit 4). It is not applied as a shorter edit. A git copy that also has hunks keeps the source file and applies the hunks to the copy.

Path checked before it is read On CLI 0.37.1, --contain checks these reads before loading bytes: git copy-from, Begin Patch check, patch merge check, markdown lint, markdown dedupe, and a batch @path payload (ast.insert content, ast.wrap wrapper or preamble, and ast.group preamble when the token is exactly @path). An outside path is still guard_rejected.

Structured and markdown edit edges On CLI 0.37.1, a JSONC block comment between numbers stays a comment. A YAML comment after the last list entry stays after the list. Markdown section edits recognize setext headings, a leading BOM, closing hashes, and a blank line between sections. md dedupe-headings says would remove in the dry-run text. There is no Quick Action for dedupe.

Move onto an existing key On CLI 0.37.3+, doc move onto a key that already has a value returns error_kind: already_exists and leaves the file unchanged. [0], 0, and 00 name the same array slot. Move to a free key, or delete the destination first. Move/rename key shows that error.

INI notes, env lines, and padded integers On CLI 0.37.3+, doc set on port = 8080 ; primary keeps the spaces around = and the note. A value that a space before ; or # would shorten on read-back is invalid_input and the file stays unchanged. On CLI 0.37.2+, an ini header that never closes ([broken) is parse_error (exit 4). A .env value that would split onto another line is invalid_input. On CLI 0.37.4+, doc set of unquoted 01 or 007 stores a decimal string (id = "01"). A single 0 stays the number zero. On CLI 0.37.2+, a TOML integer above 9223372036854775807 stays bare digits.

Upsert a bullet On CLI 0.37.3+, Upsert bullet puts the item in that heading's own list, before the first child heading. A bullet that exists only under the child is not treated as already present. A second upsert of the same item does not add it again.

YAML yes, no, on, and off On CLI 0.37.3+, unquoted yes, no, on, and off stay strings. Quote them only when you want a string that would otherwise be a number or a boolean (true, false, null).

HTTP MCP Host allowlist The extension's MCP server is stdio. If you bind Streamable HTTP yourself (patchloom mcp-server --http), non-loopback binds keep the Host allowlist. Add extra names with --allowed-host. Loopback still starts without --allow-unauthenticated.

Patch apply formats On CLI 0.30+, patch apply (and MCP apply_patch) accepts unified diffs, Codex *** Begin Patch, and Aider SEARCH/REPLACE. Update and SEARCH matches must be unique unless you pass --replace-all (SEARCH/REPLACE only). On CLI 0.37.5, two exact SEARCH/REPLACE matches are error_kind: ambiguous and the file stays unchanged. The message names --replace-all for the CLI, replace_all: true for MCP apply_patch, and unique: false for a plan. The Quick Action Apply patch (unified / Begin Patch / SEARCH-REPLACE) builds patch apply. Merge patch (three-way) is still patch merge for stale unified diffs.

Batch replace shape Batch lines use replace PATH OLD NEW (and optional flags such as --fuzzy). Do not paste CLI form replace OLD --new NEW path into a batch plan; CLI 0.18+ returns a clear parse error with the PATH OLD NEW hint. --insert-after is not a batch flag. The Quick Action Insert text after match uses it. In a batch plan that token is the new text, so the matched line is replaced. Prepend with file.prepend PATH "text".

Batch doc.update / delete_where shape Batch lines use doc.update PATH SELECTOR VALUE and doc.delete_where PATH SELECTOR PREDICATE. These are dotted batch ops (path, then selector, then value or predicate).

Create or rename destination already exists On CLI 0.19+, create/rename conflicts report error_kind: already_exists (not a generic invalid_input). Use the force flag when overwriting is intentional, or pick a free destination path.

Binary, invalid UTF-8, or non-regular file On CLI 0.20+, sole-path loads of binary or invalid UTF-8 files report error_kind: binary or invalid_encoding (not a soft no_matches). On CLI 0.26+, FIFOs and other special nodes refuse with multi-path refused[].reason: not_regular_file (not a permission error). Use a regular text file, or force-create when overwriting non-text is intentional.

Fuzzy match span refused On CLI 0.22+, over-wide fuzzy matches can report error_kind: fuzzy_span_suspicious. Prefer an exact old string, structured doc/md/ast edits, or apply-fragment with a unique anchor.

Doc selector needs multi-match op On CLI 0.27+, doc set / doc ensure / doc delete with a predicate or wildcard selector stay error_kind: invalid_input and may include suggested_op. Standalone CLI is doc update / doc delete-where; batch plans use doc.update / doc.delete_where. The extension surfaces that hint in notifications; full CLI text for search, undo, patch-merge, and batch apply is in the Output channel. Use the multi-match op (or a concrete index path such as items.0.val). The matching Quick Actions are Update matching structured values and Delete matching array items. On CLI 0.37.4+, doc ensure refuses a wildcard or predicate before it looks for a match. The error still names doc update.

Ambiguous markdown heading On CLI 0.25+, section ops that match the same heading more than once report error_kind: ambiguous. Make the heading unique or use a level-qualified query (for example ## Rules). A heading that is absent is reported as not found, and the Quick Action preview shows that error.

MCP config not injected Run Patchloom: Configure MCP and select the target editor config.

Managed install failure persists after restart Run Patchloom: Show Status to see persisted diagnostic details. If the managed binary is present but not usable, choose Reinstall Patchloom (or the status-bar action) to re-download from GitHub Releases.

Debugging CLI errors Run Patchloom: Show Output to inspect the channel. Search, search -L, undo restore details, patch-merge results (including failures), and batch-apply streams are always written there; set patchloom.trace.server to verbose for other CLI invocations, arguments, stdout, and stderr.

---

Security model

The managed installer work is intentionally conservative:

• Downloads must come from https://github.com/patchloom/patchloom/releases/download/...
• Each archive must match a published SHA-256 checksum before the extension trusts it
• Checksum failures stop the install before any managed binary is used
• A failed install never replaces an already working binary
• Binary promotion creates a backup before swapping; failures restore the backup
• Failure records persist across extension reloads for diagnostics

---

Reporting issues

File bugs and feature requests at patchloom/patchloom-vscode/issues. Include the output of Patchloom: Show Status and your VS Code version.

---

Requirements

• VS Code 1.90 or newer (or compatible editors: Cursor, Windsurf, VSCodium)
• Patchloom CLI 0.3.0 or newer (0.37.5+ recommended for JSONC / .env / INI / .properties doc edits, directory rename with undo, doc set --if-exists, CLI list-files, MCP explain_plan / tidy_check / notebook_edit / operation_schema / apply_patch apply=false, HTTP MCP Host allowlist, 66 MCP tools, empty or whitespace-only edit payloads as invalid_input, AST parse_timeout (exit 4), dest/--glob mistakes as invalid_input, dest globs on search/replace/tidy (*.txt is cwd-only), doc keys / doc len, YAML merge-key edits that keep <<: and comments, Windows dest/--cwd rules, charset / EditorConfig charset, YAML alias-to-merge on doc set, create/rename parent path is not a directory, numeric selector compares (servers[port>8000]), search -L / files_without_match, Codex Begin Patch and Aider SEARCH/REPLACE on patch apply, agent-rules --surface core honoring --mode, empty-path fail-closed (path must not be empty), suggested_op on fail-closed doc navigation, not_regular_file soft peels, ambiguous markdown headings, list_files MCP inventory, apply-fragment, full error_kind peels (binary / invalid_encoding / fuzzy_span_suspicious / already_exists / guard_rejected / ambiguous / parse_timeout / no_matches), optional PATCHLOOM_MCP_SURFACE=core 12-tool pack, multi-doc doc merge --selector, line-oriented inserts, batch replace PATH OLD NEW hints, and agent-facing JSON envelopes, plus CLI 0.37.1 formatter timeouts as format_failed with Undo when the write already landed, parent format commands dropped outside a git repository, literal $ in replacement text, incomplete hunks as parse_error, and setext or closing-hash markdown headings, plus CLI 0.37.2 through 0.37.5 exact TOML integers, padded integers stored as strings, ini notes kept, doc move onto an existing key as already_exists, YAML yes/no/on/off staying strings, upsert-bullet staying above a child heading, and a regex group the pattern does not contain refused with the file unchanged)

Contributing

See CONTRIBUTING.md for the full guide. Quick start:

npm install
npm run check          # full gate: compile + test + package

Open the repo in VS Code and press F5 to launch the Extension Development Host.