Plumb

エージェントに IDE のインテリジェンスを — 無人作業のためのガードレールと、エージェント群の連携。

Plumb は、コーディングエージェントに IDE のインテリジェンス層を提供する MCP サーバーです。LSP を活用したセマンティクス、tree-sitter のコードインデックス、プロジェクトメモリを、ガードレールの内側で利用できます。書き込みはアトミックで、ロックによって直列化され、トランザクションによるロールバックが可能です。また、ファイルシステムと git へのアクセスはスコープが限定され、デーモンは自身のクラッシュから復旧します。さらに、実行するすべてのエージェントが単一のデーモンを共有するため、Plumb はエージェント間の連携層としても機能します。互いの変更を確認し、メッセージを送り合い、作業を重複させる代わりに引き継ぐことができます。単一のバイナリで、ほかにインストールするものはありません。

---

Plumb を選ぶ理由

LLM エージェントは通常、ファイル全体をコンテキストウィンドウに読み込んで作業します。トークンを大量に消費し、大規模になると情報が失われ、シンボルのセマンティクスを把握できず、実際のリポジトリで自由に操作させるには安全性に欠けます。Plumb は、優先度順に次の 4 つの柱を基盤としています。

1. 信頼性と書き込みの安全性

エージェントに 1 時間コードベースを編集させるには、書き込みでファイルが破損せず、クラッシュでセッションが停止しないことが不可欠です。

• アトミックな I/O — すべての書き込みは一時ファイルにステージングされ、所定の場所にリネームされます。部分的な書き込みは一切ありません。シンボリックリンクに対応し、CRLF も許容します。
• パス単位のロック — デーモンが、すべてのセッションとチャットウィンドウにわたって、同じファイルへの同時書き込みを直列化します。競合は発生しません。
• 複数ファイルのトランザクション — いずれかの手順が失敗した場合に確実にアトミックロールバックしながら、数十のファイルにまたがる編集を適用できます。
• クラッシュに強いデーモン — plumb serve は再接続するプロキシです。デーモンがクラッシュまたはハングすると、新しいデーモンを再起動してハンドシェイクを再生します。エージェントが気づくことはありません。実行中の書き込みが、通知なく再実行されることもありません。
• 楽観的同時実行制御 — mtime/sha ガードにより、古い編集が新しい変更を上書きする前に検出します。

動作の様子を見るには、docs/demos/ をご覧ください — two-agents-one-file.sh（古い書き込みは拒否され、何も失われません）と daemon-respawn.sh（下図 — セッション中にデーモンが強制終了されても、エージェントの次の編集は成功します）：

2. マルチエージェントの連携

1 つのデーモンで、実行するすべてのエージェントに対応します。そのため、エージェント同士が互いの書き込みを避けるだけでなく、互いを把握してやり取りするための自然な場所となります。ロックは 2 つのエージェントが同じファイルを破損させるのを防ぎます。連携は、タスクの重複や、ピアが書き換え中の関数シグネチャに対するリベース、ピアの進行中の作業によって無効になる変更のリリースを防ぎます。

• ピアの把握（デフォルトで有効） — workspace_sessions は、デーモンが記録したすべてのアクティブなセッション名と、そのセッションが行った書き込みを表示します。別のエージェントの申告ではなく、記録されたアクティビティです。タスクを始めようとしているエージェントは、ピアがすでにそのファイルを扱っているかどうかを確認できます。（読み取り専用の操作は表示されません。また、失敗または拒否された書き込みは保持されますが、[failed — no change applied] と表示されるため、「ピアがここで作業中」と「変更が反映済み」をひと目で区別できます。）
• エージェント間メールボックス（デフォルトで有効、同じワークスペース内） — leave_note / check_messages により、セッション間でスレッド形式のやり取りができます。対象のファイルを書き換えているピアに変更を引き継いだり、思い込みで判断する代わりに、ピアに動作を測定するよう頼んだりできます。メッセージは通常のツール結果に載るため、作業中のエージェントはポーリングしなくても受け取れます。
• アドバイザリーインテント（オプトイン：[collab] intents） — share_intent でエージェントが作業内容を宣言します。ピアが申告されたパスに書き込もうとすると、競合が起こりうる時点でヒントが表示されます。インテントには意図的に未検証の申告というラベルが付けられ、デーモンが記録したアクティビティフィードとは区別されます。また、いかなる操作もブロックしません。
• 永続的な知見（オプトイン：[collab] knowledge_handoff） — share_findings により、エージェントが学んだばかりの内容を検索可能で秘密情報を除去したプロジェクトメモリーにすぐ反映できるため、その知識を得たセッションの終了後も知識が残ります。

連携は、設計上アドバイザリーにとどまります。上記の書き込み安全性は、エージェント同士の協力には依存しません。参考資料：エージェント間の共有（ツールドキュメント）および[collab]設定セクション。

3. セマンティックインテリジェンス

エディターが備えるものと同じプリミティブを、構造化ツールとして利用できます。

• LSP 対応のリファクタリング — rename_symbol、replace_symbol_body、safe_delete_symbol は、スコープ、型、参照を理解します。
• 実際の診断をインライン表示 — 実際の gopls / pyright の出力がすべての書き込みに追加されるため、エージェントはビルドを壊したことをすぐに把握できます。
• シンボル検索 — コードに範囲を限定し、標準ライブラリや依存関係によるノイズはありません。

4. コンテキスト効率と安全制御

• 必要なものだけを読み取る — 2,000 行のファイル全体ではなく、シンボルや行範囲を指定できます。
• 制御可能なアクセス範囲 — 接続ごとのパス許可リスト（読み取り専用／読み書き可能なルート）と、段階的な git 制御を備えています（破壊的な操作とネットワーク操作はデフォルトで無効で、明示的な確認が必要です）。SECURITY.md をご覧ください。
• 1 回の往復でブートストラップ — session_start は、ワークスペース、ブランチ、最近のコミット、診断情報、プロジェクトメモリーを返します。

実測可能で再現可能な数値の詳細は、docs/use-cases.md をご覧ください。1 つの関数を読む場合、ファイル全体を読むよりコンテキスト量を 2.9 倍～33.4 倍削減できます（この比率は、不要だったファイルの割合を示します）。また、find_references は、テキスト検索ではノイズが 60% を占める場合に、実際の呼び出し箇所を返します。このページでは不利な結果も公開しています。read_multiple_files は、ファイルをネイティブに読む場合よりペイロードが 1.31 倍多くなります（1.32 倍から改善しましたが、それでも損失です。小さくならない理由についてはシナリオ 10 をご覧ください）。すべての数値は scripts/measure-use-cases.py によって再生成されます。

---

はじめに

Plumb は単一のバイナリです。ゼロから最初の回答を得るまで、次の手順で進めます。

1. インストール

# Homebrew (macOS + Linux) — recommended
brew install plumbkit/plumb/plumb

# or with Go
go install github.com/plumbkit/plumb/cmd/plumb@latest

# or grab a prebuilt binary: https://github.com/plumbkit/plumb/releases

macOS に関する注意： ビルド済みバイナリはまだ公証されていません。初回の実行時に xattr -d com.apple.quarantine ./plumb を実行するか、右クリックして「開く」を選択する必要がある場合があります。Homebrew でインストールすると、この操作は不要です。

2. エージェントを接続する

plumb setup claude-code      # also: claude-desktop, codex, gemini, cursor, …

plumb setup が MCP 設定を書き込むため、JSON を手動で編集する必要はありません。

3. プロジェクトを開いて試す

必要な言語サーバーが $PATH にあることを確認してから（Go なら gopls、Python なら pyright など）、エージェントに実際の質問をしてみましょう。Claude Code では次のようにします。

cd your/project
claude "Use plumb to orient in this repo (session_start), then show me
everywhere <Handler> is called and what would break if I changed its signature."

Plumb はワークスペースを特定し、状況を把握するために session_start を実行してから、推測やファイルのダンプではなく、実際の呼び出し箇所や影響範囲など、LSP とトポロジーの実データに基づいて回答します。読み取り専用のため、何も変更されません。（接続済みのエージェントならどれでも使えます。プロンプトを貼り付けるだけです。）

go.mod／pyproject.toml がなく、Git リポジトリでもない場合は、plumb init を一度実行してワークスペースのルートを固定してください（.plumb/context.md とプロジェクト設定も初期化されます）。

手順の全体像 → docs/getting-started.md。

---

言語サポート（正確な説明）

Plumb は言語ごとに LSP の機能をネゴシエートし、言語サーバーなしで検索やナビゲーションを行える、組み込みの tree-sitter インデックスも備えています。サポートには段階があります。大きな数字をうたうより、正確にお伝えします。

Tier	Languages	What you get
第一級（CI テスト済み、実バイナリとの統合）	Go（gopls）、Python（pyright）	フル LSP：定義、参照、名前変更、診断、階層機能、およびすべての書き込みツール
検証済み	Java（jdtls）、Rust（rust-analyzer）、Swift（sourcekit-lsp）、TypeScript/JS（typescript-language-server）、Zig（zls）、Kotlin（kotlin-lsp）、HTML（vscode-html-language-server）	フル LSP。サーバーを $PATH に追加すると自動的に有効になります（[lsp.<lang>] enabled = false を指定すると、任意の言語を除外できます）。HTML には注意点が 1 つあります。このサーバーはファイルシステムにアクセスできないため、すでに開かれているドキュメントのみを対象に回答します
検索とナビゲーション（tree-sitter、LSP 不要）	JS/TS/TSX、Ruby、C、C#、Elixir、Scala、PHP、JSON、CSS、SCSS、XML、Lua、C++、Objective-C、Dart、Bash、SQL、HCL、Dockerfile、TOML、YAML、Markdown など 31 以上	ランキング付きシンボル検索、アウトライン、Topology インデックスによるグラフ探索

実バイナリによる検証は macOS と Linux で実施済みです。2026-08-21 時点で、9 つすべてのアダプターが、両方の OS で実際のサーバーバイナリを使った統合テストに合格しています。アダプターの不具合に見えるツールチェーン上の落とし穴 3 つを含む詳細は、docs/adding-an-lsp.md をご覧ください。Windows は対応予定として追跡中ですが、まだサポートされていません。デーモンの Unix ソケットを使うアーキテクチャを移植する必要があります。

---

仕組み

plumb serve は、再接続機能を備えた薄い stdio プロキシです。実際の処理は、1 つの共有バックグラウンドデーモンで行われるため、チャットをまたいでも言語サーバーは起動したままです。

flowchart TD
    A1["Claude"] --> S1["plumb serve *"]
    A2["Codex"] --> S2["plumb serve *"]
    A3["Gemini"] --> S3["plumb serve *"]
    S1 --> K["plumb.sock"]
    S2 --> K
    S3 --> K
    K --> D["plumb daemon **"]
    D --> SDB[("stats.db ***<br/>global — all projects")]
    D --> G["gopls → /projects/foo"]
    D --> P["pyright → /projects/bar"]
    G --> F1[("/projects/foo/.plumb/ ***<br/>topology.db · memory.db")]
    P --> F2[("/projects/bar/.plumb/ ***<br/>topology.db · memory.db")]

* plumb serve は再接続するプロキシです。デーモンがクラッシュしたり応答しなくなったりすると、新しいプロセスを再起動してハンドシェイクを再実行するため、エージェントに気づかれることなくセッションを継続できます。

** 1 つの共有プロセスを、すべての会話で再利用します。

*** SQLite。1 つのグローバルな stats.db（ツールの統計情報とエピソード要約）と、各ワークスペースの .plumb/ にある 2 つのプロジェクトごとのインデックス（コードグラフ用の topology.db とメモリ検索用の memory.db）です。スキーマの詳細 → docs/architecture.md。

チャットをまたいでもサーバーは起動したままで、パスごとのロックはすべての接続で共有され、書き込みのたびにシンボルインデックスがライブ更新されます。アーキテクチャの全体像 → docs/architecture.md。

---

モニタリング（TUI）

引数なしで plumb を実行すると、ライブダッシュボードが表示されます。エージェントの動作をリアルタイムで確認できます。発生するたびに表示されるすべてのツール呼び出し、デーモンの稼働状況、ツールごとの統計情報、追跡やフィルタリングが可能なストリーミングログを確認できます。暴走するループをすばやく検出したり、編集が反映されたことを確認したりするのに最適です。

---

主な機能

Plumb は 61 個のツールを提供します。頻繁に使用するツールは次のとおりです。

session_start · workspace_symbols · get_definition · find_references · rename_symbol · edit_file · transaction_apply · diagnostics

その他のツールは、ファイルシステムの読み書き、LSP 階層、階層化された git 操作、オプションのローカル Topology インデックス（ランキング付き検索＋影響範囲／ルート分析。言語サーバーは不要）、プロジェクトごとの永続メモリ、エージェント間の連携（ピアセッション、エージェント用メールボックス、オプトイン方式のインテントと知識の引き継ぎ）をカバーします。API リファレンス全文は docs/tools.md をご覧ください。

---

設定

グローバルまたはプロジェクトごとの config.toml、あるいは環境変数で設定できます。plumb config show を実行すると、設定元とともに解決済みの設定を確認できます。

[edits]
strict = true                  # require read_file before edit_file
rate_limit_per_minute = 30     # bound runaway agent loops

[git]
allow_destructive = false      # reset/checkout/rebase off by default
allow_push = false             # push/fetch/pull off by default

設定リファレンス全文は docs/configuration.md をご覧ください。

---

難しい課題

エージェントはすでにコードを十分に 読み取れます。一方、監督なしで並行して、トランザクション的に、復旧可能な形でコードを書き込むことは、いまだ解決されていません。Plumb は、まず取り組む価値があるのはこの後半だという考えに基づいています。まだ初期段階であり、対応言語の状況にもそれが表れています。検証済みの小規模なコアと、実験的であることを明示したその他の機能で構成されています。

---

ロードマップ

Plumb は 1.0 より前の段階です。コア機能である書き込みの安全性、堅牢なデーモン、トポロジーインデックス、プロジェクトメモリは、日常的に利用されています。1.0 までの道のりは、主に検証済みのコアを超えて機能を 実証 し、配布を改善することです。課題やアイデアを歓迎します。

リリース済み

• 並行処理に対応した、アトミックかつトランザクション方式のロールバック可能な書き込み
• クラッシュに強い再接続型デーモン
• Tree-sitter トポロジーインデックス＋プロジェクトごとのメモリ
• エージェント間の連携：ピア認識＋エージェント用メールボックス（デフォルトで有効）、インテント＋知識の引き継ぎ（オプトイン方式）
• Go と Python の LSP アダプターを検証済み（実際のバイナリで検証）

1.0 への道のり。 0.9 から一気に 1.0 へ進むのではなく、Plumb は一貫したテーマを持つ一連のマイナーリリース — 0.10 から 0.19 — を順にリリースします。**0.19.x が最後の 0.x リリースであり、**その後に、安定性への明確な取り組みとして 1.0 をリリースします。ネイティブの Windows サポートは、1.0 の必須条件ではなく、意図的に 1.0 後（1.1）の項目としています。テーマ別の計画は次のとおりです。

• 0.10 — 配布＋誠実な機能説明（Homebrew、セマンティックな再ランキング → GA）
• 0.11 — 実験的な LSP アダプターを実際のバイナリで検証（zls ✓ 検証済み、Kotlin ✓ JetBrains の kotlin-lsp で検証済み）
• 0.12 — Build Server Protocol のガイダンスを介した Xcode 上の Swift
• 0.13 — デーモンの堅牢性（git 書き込み時のクラッシュ安全性、生存確認プローブ）
• 0.14 — エージェントの使いやすさ＋ツールの拡充
• 0.15 — 誠実さ＋設定項目の全面的な整備
• 0.16 — 安定化＋クロスプラットフォームでの実証
• 0.17 — 配布＋見つけやすさ（レジストリ）
• 0.18 — 実証＋ドキュメント
• 0.19 — 十分な実運用期間＋フィードバック、最後の 0.x（正式な RC ではなく、継続的なパッチリリース）
• 1.0 — 一般提供：安定性と検証済みコアの提供を約束

詳細、根拠、1.0 後の項目（Windows、tree-sitter の整理）については、docs/roadmap.md をご覧ください。

貢献

アーキテクチャとコードスタイルについては、CONTRIBUTING.md と AGENTS.md をご覧ください。すべての文章でオーストラリア英語を使用しています。貢献することで、行動規範に同意したものとみなされます。

ライセンス

MIT — LICENSE をご覧ください。