Patchloom

Patchloom

1つのバイナリで、あらゆるプラットフォームに対応。AI エージェント向けの構造化ファイル編集。

Patchloom は、あらゆるオペレーティングシステムで AI コーディングエージェントが安全に構造化ファイルを編集できるようにする、単一バイナリの CLI です。セレクター（正規表現ではありません）で JSON、YAML、TOML を編集し、コメントを保持します。また、20 の言語でコード構造を理解し、複数ファイルの編集を1回のツール呼び出しにまとめられ、Linux、macOS、Windows で同じように動作します。

汎用ファイルシステム MCP ではありません。 デフォルトの MCP ファイルシステムサーバーは、ファイルをテキストとして読み書きします。Patchloom は、ドライランのプレビュー、パーサーを利用した設定ファイルや Markdown の編集、AST 操作、undo に対応した複数ファイルの batch／tx、ホスト向けの安定した error_kind 分類を追加します。完全なコーディングエージェント（Claude Code、Codex、Cursor）がループを管理し、Patchloom はそれら（または Rust に組み込むユーザー）が呼び出すツールレイヤーです。

# 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

Patchloom を選ぶ理由 | インストール | クイックスタート | コマンド | 比較 | 用途に応じた選び方 | AI エージェントとの連携 | ステータス

Patchloom を選ぶ理由

問題

AI エージェントはツール呼び出しを通じてファイルを編集します。呼び出しのたびに LLM との往復が発生します。設定ファイルに関わるタスクでは、このプロセスに 3 つの失敗要因があります。

1. 構文の破損。 エージェントが JSON、YAML、TOML にテキスト置換を使い、無効な出力を生成します（波括弧の不整合、インデントの崩れ、コメントの消失）。
2. 往復コスト。 6 つのファイルを編集するには、ツール呼び出しが 6 回必要です。それぞれで、LLM が生成し、実行し、結果を読み取り、次の呼び出しを計画するまで待つことになります。
3. プラットフォームの分断。 Linux ではエージェントは sed、jq、grep を使います。Windows ではこれらは使えません。エージェントは冗長な PowerShell に頼るか、慣れない構文でエラーを起こします。

patchloom がそれぞれを解決する方法

patchloom で何が変わるか

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

Agent: batch with
  all 6 edits     ─── tool call ───▶  25s



                  5 round-trips saved
                                    Total: ~25s

主な機能

patchloom とネイティブツールの使い分け

Patchloom はあらゆるファイル操作を置き換えるものではありません。その指示により、エージェントはいつ patchloom を使い、いつネイティブツールを使ったほうが速いかを正確に判断できます。

速度より正確性

シンプルな単一ファイルの編集では、Patchloom はネイティブツールより速くありません。そのような場合はネイティブツールを使ってください。しかし、ネイティブのテキスト置換では構造化ファイルを安全に編集できません。YAML に対して sed を実行すると、インデントが崩れたり、コメントが削除されたり、構文が無効になったりする可能性があります。doc set はファイルを解析し、セレクターで値を変更して、有効な形式で出力します。この保証こそが重要な点です。

Patchloom がより速いのは、複数ファイルの一括処理です。ネイティブツールで6つのファイルを編集する場合、LLM との往復は6回必要です。batch を1回呼び出せば、同じ作業を1回の往復で行えます。

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

インストール

GitHub の各リリースを追跡する配布チャネル（Homebrew、Scoop、crates、 npm、Releases）を優先してください。Windows では Scoop を推奨します。winget （Patchloom.Patchloom）はリリースごとに公開され、通常は Microsoft の公開 パイプラインの後に最新になります（検索結果が古い場合は winget source update を実行してください）。Chocolatey はコミュニティによる審査の間、更新が遅れることがよくあります。

# 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

Linux、macOS、Windows 用のビルド済みバイナリは Releases ページにあります。 シェルインストーラースクリプト、ソースからのビルド、シェル補完、winget / Chocolatey に関する注意事項については、インストールを参照してください。

• MCP Registry の名前：mcp-name: io.github.patchloom/patchloom

エディター拡張機能

VS Code、Cursor、Windsurf、または VSCodium 用のコンパニオン拡張機能をインストールしてください。

• VS Code Marketplace
• Open VSX Registry

この拡張機能は CLI を自動検出（またはインストール）し、AGENTS.md を生成して、MCP サーバーを設定し、コマンドパレットにクイックアクションを追加します。詳しくは、エディター拡張機能ガイドを参照してください。

クイックスタート

1. プロジェクトをセットアップする

patchloom init

新しいプロジェクトでは AGENTS.md を作成し、既存のエージェント指示ファイルがある場合はルールを追記します。また、シェル補完を提案し、MCP 設定の機会を検出します。確認プロンプトを省略するには -y を渡してください。

ルールのテキストだけが必要な場合：

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

.vscode/ または .cursor/ が存在する場合、init はコピーしてすぐ使える .vscode/mcp.json または .cursor/mcp.json のスニペットも出力します。

AI エージェントは AGENTS.md を読み、patchloom とネイティブツールを使い分けるタイミングを学習します。

2. 設定ファイルを安全に編集する

# Parser-backed: changes the value, preserves comments and formatting
patchloom doc set config.yaml database.port 5432 --apply

3. 複数の編集を1回の呼び出しにまとめる

patchloom batch --apply <<'EOF'
doc.set config.json version '"2.0.0"'
md.upsert_bullet AGENTS.md "Rules" "- Always test"
replace src/main.rs "v1" "v2"
EOF

値は JSON が基本です。引用符なしの 2.0 は数値になります。文字列にするには、上記のように引用符を重ねてください（Unix シェルの場合）。

bash のヒアドキュメントが使えない Windows PowerShell では、ops をファイルに書き込みます。

@'
doc.set config.json version "\"2.0.0\""
md.upsert_bullet AGENTS.md "Rules" "- Always test"
replace src/main.rs "v1" "v2"
'@ | Set-Content ops.txt -Encoding utf8
patchloom batch --apply ops.txt

または、format と validate のライフサイクルを含む JSON プランを使います。

{
  "version": 1,
  "operations": [
    { "op": "doc.set", "path": "config.json", "selector": "version", "value": "2.0.0" },
    { "op": "md.upsert_bullet", "path": "AGENTS.md", "heading": "Rules", "bullet": "- Always test" },
    { "op": "replace", "path": "src/main.rs", "old": "v1", "new": "v2" }
  ],
  "format": [{ "cmd": "cargo fmt --all" }],
  "validate": [{ "cmd": "cargo test", "required": true }]
}

patchloom tx plan.json --apply

tx プランは信頼できる入力として扱われます。format と validate は cmd フィールドをホストのシェル（Unix では sh -c、Windows では cmd /C）経由で実行するため、信頼できるプランだけを実行してください。

4. または、MCP を使って構造化ツール呼び出しを行う（シェル構文は不要）

MCP サポートを有効にしてインストールした後、サーバーを起動します。

PATCHLOOM_MCP_SURFACE=core patchloom mcp-server

MCP 対応エージェントは、シェルのクォートやコマンドの組み立てを行わず、構造化 JSON として patchloom ツールを直接呼び出します。エージェントは patchloom doc set config.json version '"2.0"' --apply を組み立てる代わりに、{"path": "config.json", "selector": "version", "value": "2.0"} を送信します。

コーディングエージェント： 12 ツールのパック（list_files、検索／読み取り／置換、doc/md、execute_plan、operation_schema、server_info）を使うには、PATCHLOOM_MCP_SURFACE=core を設定します。これにより、スキーマを小さく保てます。環境変数が未設定の場合、製品のデフォルトでは引き続き全インベントリが使用されます。リストと編集には Patchloom MCP のみを使うことを推奨します（2 つ目のファイルシステム MCP は不要です）。Cursor / Claude / Codex の貼り付け用設定とセキュリティモデルの全容については、MCP セットアップガイドをご覧ください。

VS Code、Cursor、または Windsurf をお使いですか？ Patchloom 拡張機能がセットアップを自動的に処理します。バイナリをインストールし、init を実行して、エディターの MCP 設定を構成します。

Rust ライブラリとして

プライベートな編集スタックの代わりに Patchloom を組み込むホストチーム向け：
組み込みホストのケーススタディをご覧ください （for_agent、peels、fuzzy refuse、apply_fragment、path-only ops）。

patchloom を依存関係として追加します（CLI/MCP/AST を省略するには default-features = false を指定します）。

[dependencies]
patchloom = { version = "0.37.6", 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"))?;

すべての API 型は Send + Sync です。api モジュールに加えて、ユーティリティモジュールも公開されています。containment（ワークスペースのパスガード）、exec（シェルコマンドの実行）、files（ファイルの走査、load_text_strict、バイナリ検出）、backup（Apply 後の検証／復元用 restore_path_from_latest_backup）、write（ポリシー変換を伴うアトミックなファイル書き込み）があります。一時ディレクトリを必要とするライブラリユーザー（エージェントなど）は、PathGuard::builder(cwd).allow_temp_directory() を使用できます（macOS の /tmp に対応します）。containment および api モジュールの rustdoc をご覧ください。複数ドキュメントの裸のキーと、ルートが異なるマージは、edit_error_kind を介して EditErrorKind::TypeError に変換されます。作成／名前変更時に宛先がすでに存在する場合は、EditErrorKind::AlreadyExists に変換されます（または CLI と安定して互換性のある "already_exists" 文字列を返す api::is_already_exists / api::error_kind_str を使用できます）。細分化された種別には、edit_error_kind に対応する bool 形式の判定関数（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）もあります。

fail-closed の置換オプション／シェルトークンオプション：CLI の replace --require-change と --command-position（plan/MCP のフィールド、およびライブラリの ReplaceOptions も同様）。エージェントホストでは、主要な置換パスとフォールバックの置換パスの両方で ReplaceOptions::for_agent() を使います（スパンが自動的に拒否されます）。カスタムオプションでは、fuzzy Apply 後に api::fuzzy_span_suspicious / FuzzySpanPolicy を呼び出してください。複数オペレーションをバッファリングするホストでは、apply_content_edits の後に api::refuse_batch_if_suspicious_fuzzy を呼び出します（#2064）。ライブラリ専用の AST ミューテーター：ast_rename / ast_replace_in_symbol / ast_rename_batch（feature ast + files）、および FunctionSigEdit::parse_rust。順序に沿ったホスト導入手順：組み込みホストのチェックリスト（#2009）。全機能：docs.rs/patchloom。

はじめに

コマンド

エージェント向けに最適化（ネイティブツールより高速または安全です）

汎用（スクリプトや CI でも便利です）

patchloom との比較

重要な違いは、patchloom が AI エージェントのワークフロー向けに設計されていることです。1 回の batch または tx 呼び出しで N 回の連続したツール呼び出しを置き換え、往復を減らし、部分的な失敗状態をなくします。

エージェントネイティブな編集ツールとの比較

上の表では、patchloom と人間向けの CLI ツールを比較しています。しかし、エージェントにはすでに組み込みの編集機能があります。Claude Code の edit_file、Cursor の apply、Grok Build の search_replace、Aider の /code ブロックなどです。では、なぜ patchloom を追加するのでしょうか？

エージェントネイティブなツールはテキストマッチングを使用します。 テキストのブロックを見つけて置換します。これはソースコードでは機能しますが、構造化された設定ファイルではうまくいきません。

database:
  # Production settings
  host: db.prod.internal
  port: 5432  # PostgreSQL default
  pool_size: 10

patchloom doc set config.yaml \
  database.port 5433 --apply

ネイティブツールを使い続ける場合： 単一ファイルの読み取り、簡単なテキスト検索、コメントが重要でない単一ファイルのテキスト置換。Patchloom のエージェントルールでは、それぞれの方法を使うタイミングをエージェントに正確に指示します。

使い分け

詳しい説明はこちらです：比較 · エンベッダーホストのチェックリスト · MCP のセットアップ

ライブラリホスト： エンベッダーホストのチェックリスト：デュアルパスの ReplaceOptions::for_agent()（プライマリ＋フォールバック。refuse_suspicious_fuzzy を含む）、#[non_exhaustive] の _ アームを使用して edit_error_kind／is_*／is_fuzzy_span_suspicious で判定、バッファー上の複数操作後に使用する複数操作対応の ContentEditsResult.op_honesty ＋ refuse_batch_if_suspicious_fuzzy（#2064）、最も広い matched_text を返す plan／tx、任意指定の apply_content_edits_to_file_with_span_policy。カスタムオプションでは、ファジー Apply の後に引き続き api::fuzzy_span_suspicious／FuzzySpanPolicy を使用します。

コンテキスト予算： 行範囲を指定した read、search --count／--files-with-matches、1 回の batch／tx、大きなストリームには --jsonl を使用します。

AI エージェントとの連携方法

2 つの統合モードで、同じ機能を利用できます。

flowchart LR
    subgraph CLI["CLI mode (any agent)"]
        direction TB
        A["patchloom agent-rules >> AGENTS.md"] --> B["Agent reads AGENTS.md"]
        B --> C{"What kind of edit?"}
        C -->|Simple edit| D["Native tool (faster)"]
        C -->|Config edit| E["patchloom doc (safer)"]
        C -->|Markdown edit| F["patchloom md (smarter)"]
        C -->|Multi-file edit| G["patchloom batch (batched)"]
    end

    subgraph MCP["MCP mode (MCP-capable agents)"]
        direction TB
        H["patchloom mcp-server"] --> I["Agent discovers tools via MCP"]
        I --> J["Structured JSON tool calls"]
        J --> K["No shell syntax needed"]
    end

ステータス

25 個のコマンドにわたる 5900 件以上のテストがあります。Grok 4.3、GPT-5.4、Claude Opus 4.6 でテスト済みです。

全コマンドリファレンス

すべてのコマンド、フラグ、トランザクション操作、終了コードは、コマンドリファレンス に記載されています（docs/reference/README.md でも参照できます）。

ライセンス

以下のいずれかのライセンスで提供されています。

• MIT ライセンス（LICENSE）
• Apache License, Version 2.0（LICENSE-APACHE）

お好きな方を選択できます。

貢献

CONTRIBUTING.mdをご覧ください。

プルリクエストを作成する前にローカルで検証するには、make checkを実行してください。主な Linux テストと lint のゲートをカバーします。具体的には、フォーマット、clippy、ユニットテスト（機能マトリクスのジョブを含む）、統合テスト、PTY テスト、リリースノートの構成、テストの健全性、生成ドキュメントの最新性（check-patchloom-md、check-readme）、server-json-test、verify-homebrew-version-test、パッケージングスクリプトのユニットテスト（scoop-manifest-test、chocolatey-package-test、pack-mcpb-test、force-release-version-test）、workflow-sanity-test、apply-release-notes-test、dco-check-testです。GitHub の必須チェックすべてを実行するわけではありません。audit、deny、Windows のチェックは GitHub Actions で実行されます。ローカルで繰り返し作業する場合、make check-fastはcheck-patchloom-mdのみをスキップし、それ以外は同じです（check-readme、server-json-test、verify-homebrew-version-test、パッケージングスクリプトのテスト、workflow-sanity-test、apply-release-notes-test、dco-check-testは引き続き実行されます）。

プルリクエストのタイトルには、Conventional Commits のプレフィックスを1つ使用する必要があります（feat、fix、docs、style、refactor、perf、test、build、ci、chore、revert。カンマや+は使用できません）。CONTRIBUTING.mdをご覧ください。

すべてのコミットにgit commit -sで署名を付ける必要があります。

エージェント統合テスト

make agent-testを実行すると、指示を与えられた AI エージェントが patchloom を正しく使用することを検証する、19件の pytest シナリオが実行されます。make bench-agentを実行すると、11件のタスクを対象に3方式（CLI、MCP、ネイティブ）のベンチマークが実行されます。モデルを切り替えるにはMODEL=Xを、ばらつきを抑えるにはRUNS=Nを使用してください。LLM API キーが必要です。make checkには含まれません。詳細はtests/agent/README.mdをご覧ください。

セキュリティ

最新のセキュリティ報告に関するガイダンスは、SECURITY.mdをご覧ください。