Patchwork OS

Patchwork OS

自動化の問題ではありません。意思決定の問題です。

AI エージェントの恐怖談はいつも同じ結末を迎えます。誰も止めて疑問を挟まなかったアクションです。Patchwork OS は、エージェントの衝動とアクションの間に位置するレイヤーです。ローカルファーストのランタイムであり、あなたの AI がエディター、GitHub、Slack、Gmail、その他 45 以上のサービスをまたいで実際の作業を自動化できるようにしながら、重要なことは何でも止まってまずあなたに確認させることができます。

対象となる方: すでに実際のシステムに対してエージェントを動かしている開発者や技術オペレーター — リリースされるリポジトリ、重要な受信トレイ、本番サービス — で、何が許可され、なぜ許可されたかの記録を求める方。ターミナルと Node のインストール、そして YAML の編集に抵抗がないことが前提です。

3 つの考え方、1 つのランタイム:

• 行動する前に確認する。 すべてのアクションは影響範囲によって分類されます — 取り消せるか、そして間違っていた場合にどれだけ壊れるか。可逆的なものは自由に流れます。リスクのあるものは、証拠を添えて承認キューで待機します。正確に何が実行されるのか、なぜ発火したのか、そして間違っていた場合に何が起こるのか。

• 信頼は勝ち取るものであり、決して前提とされるものではありません。 ワーカー — 役割を持つ名前付きのエージェント — は監督下で始まり、アクションの種類ごとに実績から独立性を獲得していきます。issue の起票が得意 ≠ コードのプッシュが許可される。1 つの重大な失敗したアクションは、100 の些細な成功を上回ります。上限を設定するのはあなたであり、計算が勝手にその上限を引き上げることはありません。

• すべての意思決定は記録を残す。 何が行われ、なぜ許可され、どうなったか — 永続的で、再生可能で、patchwork judgments、ダッシュボードのトレースページ、そして patchwork gate explain を通じて説明可能です。何かを承認したとき、あなたが正しかったかどうかを後で知ることができます。

エージェントがファイルを書き込もうとしています。ゲートが有効な場合、それは待機し、実行しようとしている内容を正確に示します:

あなたが承認します。呼び出しは進行し、その両方が記録に残ります:

ステータス：安定版 1.2

バージョン 1.2.6 は npm に latest として公開されています。意思決定レイヤー、レシピ、コネクター、IDE ブリッジはすべて動作しており、日々実際の用途で使われています。インターフェースはマイナーバージョン間で変更されることがあり、機能によってはまだ粗削りです。これを基盤に構築する場合は、正確なバージョンを固定してください。

安全機能が有効かどうかは、インストール方法によって異なります。 README のほかのどの記述よりも重要な点です。

• 新規インストール： ~/.patchwork/config.json が存在しないマシンで patchwork-os init を実行すると、profile: governed が書き込まれます。最初の実行からゲートが有効になります。
• 既存のインストール： アップグレードしてもプロファイルは変更されません。既存の設定はそのまま維持されます。有効にするには patchwork profile governed を実行して、ブリッジを再起動してください。
• 設定がまったくない場合（init を実行せずにブリッジを起動）：何もゲートされない compat プロファイルになります。

patchwork doctor を実行すると、現在マシンで適用されている設定を確認できます。この表よりも、コマンドの出力を優先してください。

機能	governed（新規 init）	compat（既存の設定、または設定なし）
承認キュー	自動トリガー（cron、webhook、file-watch、git-hook）と手動実行の両方で、high に設定すると有効	--approval-gate high または all を指定しない限り無効。指定した場合も手動実行のみ
取り消し不能な書き込み	ティアにかかわらず承認を求める	ティアのしきい値に従う
エージェントのステップ	制限あり：読み取り専用ツールのみ。ネットワークやシェルは使用不可	ステップで sandbox: true を設定しない限り、フルアクセス
レシピプラグイン（servers:）	plugins.allow に記載されている場合のみ読み込む	すべてのエントリーをプロセス内で読み込む
登録先のないツール	実行を停止する	ステップをスキップする
キルスイッチ（patchwork panic）	利用可能。状態を読み取れない場合はフェイルクローズ	利用可能。フェイルオープン
ワーカーの自律性の段階的な引き上げ	ワーカー所有のレシピで有効（実行には --driver subprocess などのドライバーが必要）	PATCHWORK_FLAG_WORKER_AUTONOMY=1 を設定しない限り無効（同じドライバー要件）
テレメトリー	無効	無効。明示的にオプトインしてください（詳細）

compat では、新しいブリッジは自動化ランタイムとして動作し、ゲートを有効にすると意思決定レイヤーになります。「まず停止して確認を求める」という上記の説明は、ゲートが有効な場合についてのものです。

ループ

trigger → recipe/worker → reversible?           → runs
                        → risky, gate on        → approval queue → your yes → receipt
                        → risky, gate off       → runs
                        → forbidden by policy   → refused (no approval unlocks it)

patchwork panic は、実行中のすべてのブリッジで、書き込みティアのツール呼び出しをただちにすべてブロックします。読み取りは引き続き機能し、実行中の推論も停止しません。これは書き込みのブロックであり、全面停止ではありません。

インストール

npm install -g patchwork-os@beta
patchwork-os init

init は ~/.patchwork のひな形を作成し、ローカル専用のレシピを用意して、Patchwork の PreToolUse フックを ~/.claude/settings.json に登録します。その後、Claude Code を再起動してください。フックはセッション開始時に読み込まれます。

前提条件： Node 22.5 以降。macOS、Linux、ネイティブ Windows（WSL なし）。

始める前に知っておくとよい点が2つあります。

• npx ではなく、グローバルインストールを使用してください。 npx ではバイナリが保持されないため、ガイドに記載された次のコマンドが見つからなくなります。
• Web ダッシュボードは npm パッケージに含まれていません。 独自のビルドが必要な Next.js アプリなので、リポジトリに同梱されています：

  git clone https://github.com/Oolab-labs/patchwork-os && cd patchwork-os/dashboard
  npm install && npm run build && npm start   # http://localhost:3200
  

  以下の内容はすべて、ダッシュボードなしで CLI から実行できます。承認、トレース、コネクターの設定を簡単に行うには、ダッシュボードを使用してください。

初回実行：コネクターなし

サービスを接続する前に、ランタイムが動作することを確認します。daily-status が使用するのは git とローカルファイルだけです。アカウントもネットワークも必要ありません。

patchwork recipe run daily-status

昨日以降のコミットと ~/.patchwork/planned.md を読み取り、Markdown のダイジェストを ~/.patchwork/inbox/daily-status-<date>.md に書き込みます。このファイルが作成されていれば、インストールは正常です。

関連する便利なコマンド：patchwork recipe list、patchwork status、問題が発生したときの patchwork recipe doctor <name>。

モーニングブリーフ: 連携されたワークフロー

patchwork-os init --with-connectors   # seeds the connector-backed recipes
patchwork connect gmail
patchwork connect google-calendar
patchwork connect github
patchwork connect linear
patchwork recipe run morning-brief

このレシピは、未読メール、今日のカレンダー、自分のオープンな GitHub issue と PR、Linear の issue、ローカルの git アクティビティを取得し、それらをモデルに要約させて 1 つの Markdown ブリーフとして ~/.patchwork/inbox/ に出力します。メールのステップは トリアージ です。返信が必要なものを一覧にするだけで、返信の作成や送信は行いません。接続したサービスへの API 呼び出しを除き、何もあなたのマシンから出ていきません。

4 つのコネクターはすべて、記述どおりに必須です。どのステップもガードされていないため、1 つでも欠けると実行が停止します。不要なステップは削除するか、daily-status から始めてソースを 1 つずつ追加してください。

動作するモデルドライバーが必要です（PATH 上に Claude CLI がある状態での --driver subprocess、または API キー）。patchwork recipe preflight templates/recipes/morning-brief.yaml は、レシピを実行する前に何が必要かを正確に一覧表示します。

実行方法は 2 通り

自動化ランタイムとして — レシピ、ワーカー、コネクター、意思決定レイヤー。~/.patchwork とモデルドライバーが必要で、エディターは任意です。

patchwork start        # bridge + Claude + dashboard

patchwork start はブリッジと一緒に claude --ide を起動するため、PATH 上に Claude CLI があることを前提とします。それが不要な場合は、patchwork start --no-dashboard を使うか、patchwork --workspace . でブリッジだけを実行してください。

グローバルな npm インストールでは起動すべき dashboard/ が存在しないため、ダッシュボードの警告をログに記録してブリッジ + Claude で続行します。警告を消すには --no-dashboard を渡してください。リポジトリのクローンからなら 3 つすべてが起動します。

スタンドアロンの IDE ブリッジとして — Claude Code にエディター内での目と手を与える 180 の MCP ツール: 診断、LSP ナビゲーション、リスク分析を伴うリファクタリング、デバッガー、ターミナル、git/GitHub、ファイル操作。~/.patchwork もレシピもゲートも不要です。

npm install -g patchwork-os
claude-ide-bridge install-extension     # VS Code / Cursor / Windsurf / Antigravity
claude-ide-bridge --workspace .
claude --ide                            # in another terminal

JetBrains はコンパニオンプラグイン経由です。Claude Desktop、Gemini CLI、Codex CLI、Grok Build、claude.ai は stdio または HTTP で接続します。それだけで十分なら、ブリッジだけをずっと使えます。ランタイムはその上に載るオプションのレイヤーです。

claude --ide が IDE を見つけられない場合は、CLAUDE_CODE_IDE_SKIP_VALID_CHECK=true を設定してください（init がこれを設定します）。

「ローカルファースト」が意味すること、意味しないこと

あなたのマシン上にあるもの: ランタイム、すべてのレシピとワーカー、すべての認証情報とコネクタートークン、承認キュー、そして ~/.patchwork/ 配下のすべてのログと意思決定レシート。何もアップロードされず、Patchwork が運用するサーバーが経路上に存在することもありません。

ネットワーク経由で、必然的に: 接続先のモデル（Anthropic、OpenAI、Google、xAI）への呼び出しと、認可したすべてのコネクター（Gmail、GitHub、Slack など）への呼び出し。プロンプト、およびステップがそれらに与えるコンテキストは、そのモデルプロバイダーに送信されます。ローカルの Ollama エンドポイントを選べば推論もあなたのマシン上に留まりますが、コネクター呼び出しは依然としてマシン外に出ます。それがコネクターというものだからです。

オプトインした場合のみ: 匿名アナリティクス。

知っておく価値のあるその他の境界: runCommand は許可リストにあるコマンドのみを実行し、sendHttpRequest はプライベートおよびループバックのレンジをブロックし、ファイルツールはワークスペース外へのシンボリックリンクによる脱出を拒否します。リモートデプロイメントは TLS と OAuth 2.0 の背後に置く必要があります。詳細は docs/remote-access.md を参照してください。

ここにあるもの

• 意思決定レイヤー — 承認キュー · 影響範囲アクションクラス · ワーカー信頼度ランプ · キルスイッチ · 意思決定レシート

• 自動化 — YAML レシピ · cron/ファイル/git/テスト/webhook トリガー · イベントフック · マルチモデル（Claude、GPT、Gemini、Grok、Ollama）

• コネクター — 45 以上、すべての書き込みはあなたのポリシーで統制: GitHub、Slack、Gmail、Calendar、Drive、Linear、Jira、Sentry、Notion、Stripe、PagerDuty、Datadog、…

• IDE ブリッジ — 180 の MCP ツール · VS Code ファミリー拡張機能 · JetBrains プラグイン · プラグインのホットリロード（セッション中にツールを書き込み可能）

• 監督 — Web ダッシュボード · モバイルプッシュ承認（PWA） · 停止/判定 CLI · セッションをまたぐトレースメモリ

• デプロイ — あなたのノート PC · OAuth 2.0 を備えたヘッドレス VPS（ガイド） · ネイティブ Windows

レシピはプレーンな YAML です: トリガー（cron、ファイル保存、git コミット、テスト実行、または任意の webhook — iPhone ショートカット、Stream Deck、Home Assistant）とステップ。dotfiles のように共有したり、マーケットプレイスからインストールしたり、ダッシュボードに一文から生成させたりできます。

ワーカーは、アイデンティティと実績を持つレシピです。失敗している CI をトリアージするワーカーは、まず提案だけを行います（「これは本当の破損のようです — イシューを起票しますか?」）。その起票が本物であったことを確認すれば、より長いリードが与えられます — そのジョブに限って。悪い一日で降格されることもあります。どのワーカーも YAML 一行で恒久的に上限を設定できます。

なぜ Zapier / MCP サーバー / ホスト型アシスタントではないのか? 正直なトレードオフ: documents/comparison.md。

ドキュメント

ドキュメント索引 · プラットフォームリファレンス · レシピとトリガー · ワーカーの自律性 · プラグイン作成 · アーキテクチャ · Windows · ADR

テレメトリー

デフォルトではオフです。オプトインしない限り何も送信されません。オプトインした場合: 送信されるのは集計されたカウントとレイテンシのみ — パス、プロンプト、ファイルの内容、引数、~/.patchwork/ からのあらゆるものは決して送信されません。詳細 & ソース。

コントリビューションとサポート

Issues · Discussions · CONTRIBUTING.md

⭐ これが設定ファイル一つ、あるいはデプロイの失敗を防いだなら、スターは私が役に立っていると知る唯一のシグナルです。

MIT © Oolab Labs — それがカバーする範囲 · 名称とマーク