set-up-machine

マシンのセットアップ

選択したハーネスと環境をすべて、Harnesses に記載されている各ソースからセットアップします。選択した各ツールを、入手可能な最新バージョンにインストールまたは更新します。スキルを再度実行することが監査となります。設定と最新性を確認し、必要な更新を提案します。

ソース

• ルールテーブル、rules.json。
• ワークステーションリポジトリ、<workstation-repo>。ポインター、~/.config/agents/source.md を通じて特定します。このファイルにはリポジトリ名とそのクローンが記されています。次の各ファイルは任意です。
  • setup/instructions.md：作業上の取り決め、用語集、各役割を担うツール、個人のワークフロー。
  • setup/permissions.json：個人の権限。各ハーネスがルールテーブルの権限の横に持つ行です。
  • setup/installs.json：すべてのマシンにインストールするスキル、プラグイン、コマンド。
  • setup/harnesses.json：各ハーネスの指示と宣言済み設定の場所。各ハーネスには、デフォルトモデルなどの宣言済み設定を指定できます。

出力

• 共有グローバル指示ファイル、~/.config/agents/AGENTS.md。すべてのハーネスが読み込みます。個人向けの部分は setup/instructions.md に基づきます。
• setup/harnesses.json で instructions ファイルが指定されているハーネスのハーネス指示ファイル：Cursor の ~/.cursor/rules/harness-instructions.mdc と Claude Code の ~/.claude/rules/harness-instructions.md。詳細は references/workstation.md の「Harness instructions file」を参照してください。
• ルールテーブルと個人の権限に基づく、各ハーネスの権限エントリー。
• 各ツール呼び出しの前に実行するツール前フック、scripts/pre_tool_hook.py。
• 見つからない場合、または何も記録されていない場合のポインター。
• setup/harnesses.json で各ハーネス用に指定された config ファイルに基づく、各ハーネスの宣言済み設定：そのファイルで設定されているキーのみをハーネス独自の設定ファイルにマージします。その他のキーはすべてユーザーの設定として維持します。詳細は references/workstation.md の「Declared config」を参照してください。
• このマシン用に setup/installs.json が列挙するスキルとコマンド、および同ファイルで指定された各ハーネスのプラグイン：エントリーごとに、プラグインのセットアップ領域、プラグインバンドル、または単独の MCP サーバーを使用します。
• すべてのハーネスでメモリを無効にします。

毎回の実行に適用するルール

• ソフトウェアのバージョンのスナップショットではなく、インストール時の選択、設定、手順を再現します。最新の安定版、またはリポジトリで配布されるコードの場合は最新のデフォルトブランチを使用します。これは、ハーネス、スキル、プラグイン、パッケージ、コマンドラインツールに適用します。
• インストール済みのバージョンとソースのコミットは、将来のインストール先としてではなく、監査証拠として記録します。過去の引用や依存関係ロックファイルは、マシンのセットアップ時の選択と分けて管理します。
• インストールが最新かどうかを判断する前に、現在の上流ソースを確認します。宣言と一致していることや実行可能ファイルが存在することが証明するのは、存在のみです。最新性を確認できない場合は gap と報告します。
• ルールテーブルで生成されなかったエントリーはすべて、そのまま維持します。これらはユーザーのものです。
• ハーネスの形式は変更されるため、記述する前に、ハーネスのリファレンスがリンクしているドキュメントを確認します。形式が異なる場合は、ドキュメントに従い、その違いをレポートに記載します。

パラメーター

• <skills-repo>：GitHub にあるユーザー自身のスキルリポジトリ。形式は owner/repo です。ワークステーションリポジトリに setup/installs.json がない場合のみインストールします。
• <workstation-repo>：ユーザー自身の個人用エージェント設定リポジトリ。通常は非公開で、形式は owner/repo です。
• <path-to-workstation-repo>：そのリポジトリのクローン先。例：~/code/agent-setup。
• <session-host>：エージェントセッションの実行場所。例：herdr。ライブチェックでは、そこで各ハーネスのセッションを開始します。

手順

1. 調査します。

   • ハーネスとツール： 選択されたものをそれぞれ特定し、インストール済みのバージョンを最新のソースと比較して、現在のドキュメントを読みます。インストールチャネルは維持します。
   • ハーネスの参照資料： それぞれを読み、続いて必要な機密情報ではない設定フィールドを読みます。認証情報、認証情報ストア、実行時の状態は読み取りません。各ハーネスのオプションの config は、参照資料の指示に従って調べます。
   • 共有ファイルとポインター： 両方を読みます。ポインターにワークステーションのリポジトリが記載されている場合は、references/workstation.md を読み、続いて <path-to-workstation-repo> 内の setup/instructions.md、setup/permissions.json、setup/installs.json、setup/harnesses.json を読み、その後、setup/harnesses.json が指す各ファイルを読みます。
   • Codex と Pi： セットアップと検証の全体を通して、解決済みの Codex 設定ホームを 1 つ、解決済みの Pi エージェントフォルダーを 1 つ使用します。
   • ポインターが見つからない場合： references/workstation.md を読み、続いて <workstation-repo> と <path-to-workstation-repo> をユーザーに一度だけ尋ねるか、該当するものがないかを尋ねます。diff でポインターを書き込み、「none」の場合も記録するため、次回は尋ねません。
   • ポインターにワークステーションのリポジトリがないと記録されている場合： references/workstation.md の指示に従って、リポジトリを使わない実行としてマシンをセットアップします。または、ユーザーが今回リポジトリを指定した場合は、ポインターを書き換える手順に従います。
   • マシンが VPS などのリモート環境またはヘッドレス環境の場合： まず references/remote-machine.md を読みます。
   • ハーネスが Grok Bot の場合： その指示はファイルではなくメモリに記録します。適用、調整、監査には references/grok-bot/desktop.md の「Instructions」に従います。
   • 実機に変更を加えずに変更を試す場合： プロジェクトの .scratch/ にホームフォルダーのコピーを作り、そのコピーに対して手順を実行し、verify.py --home <copy> で確認します。そこでハーネスは起動しません。実際のログイン情報を読み取ってしまうためです。

2. **各ハーネスをルール表、共有ファイルの構成と個別設定、ポインター、メモリ無効化、フックの接続、各ハーネスが宣言する設定、インストール項目に準拠させる diff を 1 つ提案します。**インストール項目には、このマシン向けに setup/installs.json が列挙するすべてのスキルとコマンドを含め、選択した各インストールを最新の状態にします。不足しているインストールだけでなく、ハーネスのアップグレードとプラグインの更新も含めます。見つかった各ハーネスに専用のセクションを設け、その参照資料に記載された各ギャップとフックの見落としを列挙します。グローバル指示ファイルを diff に含める場合は、references/global-instructions.md を読みます。

   rules.json、個人用の権限、共有ファイルの構成、ハーネスの参照資料をもとに、各ハーネスが保持すべき内容を判断し、マシンにある内容と比較します。diff 全体を記述します。ハーネスとファイルごとに、正確な項目または統一 diff を示し、各行に次のいずれかのマークを付けます。

   • added：追加。tightened：より厳しい項目が追加され、その項目が優先される。removed：削除。updated：インストール済みのハーネス、スキル、プラグイン、またはツールが最新のソースより古い。
   • present：存在。フックの場合は wired：接続済み。行に一致する MCP ツールの場合は found：検出済み。
   • stricter：マシンの設定が表より厳しく、そのまま維持。extra：表にも個人用の権限にもないが、そのまま維持。ignored：setup/installs.json が意図的に除外しているインストール済みスキルで、そのまま維持し、インストールも削除もしない。gap：ハーネスが表現できない項目。
   • personal：個人用の権限によって生じた各項目のマークの横に付けます。例：added, personal または present, personal。これにより、ユーザーは該当項目を表の項目と区別でき、extra と誤認しません。
   • n/a：該当なし。個人用の権限にあるツールをこのハーネスがサポートしない場合に使用し、その理由も記します。そのハーネスには何も書き込みません。 removed は、メモリファイル、すべての行がすでに共有ファイルに含まれているハーネス独自のグローバルファイル（リンクになります）、および古いスクリプトを参照するこのスキル独自の配線にのみ使用します。削除された行（表の行または個人用の行）が残っている場合は extra とし、ユーザーが削除できるようにします。
   • ワークステーションのリポジトリに setup/installs.json がある場合： diff には、このマシンに適用されるエントリごとに1行と、適用されないエントリごとに理由を添えた n/a の行が含まれます。このファイルがリストの全体です。記載されていないものは何もインストールしません。形式、確認項目、コマンドについては references/workstation.md を参照してください。
   • ファイルがなく、<skills-repo> の値がある場合： diff は、そのリポジトリのスキルをグローバルにインストールします：npx --yes skills add <owner>/<repo> -g -a codex -a claude-code -y。ただし、~/.claude/skills が ~/.agents/skills へのリンクである場合は -a claude-code を省きます。references/workstation.md の説明に従って、インストール済みスキルのハッシュをソースの最新のデフォルトブランチと比較します。ロックファイルに存在するだけでは、最新である証明にはなりません。値がない場合は none の行になります。

3. diff 全体について、承認を1回だけ求めます。 その後に変更を加える場合は、新たな承認が必要です。

   • diff に setup/installs.json に記載された added と updated のインストールのみが含まれる場合： ユーザーがそのリストを記述した時点で承認しているため、確認を求めずに書き込みます。

4. バックアップを作成します。 diff で変更または削除するファイルをすべてバックアップします。ファイルを書き込む前に、それぞれをホームフォルダーからの相対パスで ~/.config/agents/backups/<UTC time as YYYYmmddTHHMMSSZ>/ にコピーします（例：.claude/settings.json）。シンボリックリンクはリンクとしてコピーします。

5. 書き込みます。 承認された diff の内容だけを正確に書き込みます。diff でインストールするスキルなどがある場合は、書き込みの前にインストールコマンドを実行します。失敗した場合は後続の書き込みを中止し、失敗までに変更した内容を報告します。アップグレード後は設定とガードレールの互換性を確認し、失敗を報告します。古いスナップショットを望ましい状態として扱ってはいけません。JSON および TOML ファイルでは、diff で指定されたキーのみを変更し、残りはそのままにします。シンボリックリンクを経由して書き込みます。

6. 次のコマンドで検証します： python3 <skill-folder>/scripts/verify.py。ここで <skill-folder> は、このスキルのインストール先フォルダーです。このスクリプトには Python 3.9 以降と標準ライブラリのみが必要で、何も書き込みません。Verification の条件を満たせば検証に合格です。その後、diff に変更がなくなるまで再度確認します。未処理の added、updated、tightened、removed の行がない状態にします。バックアップフォルダー、配線した内容、未対応の項目、および厳格化した項目と余分な項目を報告します。

   検証スクリプトが確認するのは永続化された設定であり、上流のリリースではありません。すべてのインストールが最新であると報告する前に、Inspect の最新性確認を完了してください。

7. references/live-check.md の説明に従い、各ハーネスを実際に確認します。 <session-host> で各ハーネスの実セッションをデフォルトモデルで開始し、使い捨てのフォルダーで同じプローブを実行して、ディスク上の内容と画面を確認します。検証スクリプトが証明するのはファイルの状態であり、実際の確認で証明するのは各ハーネスがその設定どおりに動作することです。各 FAIL は手順2から6を通じて修正し、その後、そのハーネスを再確認します。検証スクリプトと実際の確認の両方に合格した時点で完了です。

   • <session-host> がハーネスのセッションを開始できない場合： そのハーネスの実際の確認を gap として記録します。

検証

グローバル行が2行、続いてテーブルが1つ、その後に各 FAIL および gap セルにつき詳細行が1行あります。

setup  ok    <owner>/<repo>: the shared file matches setup/instructions.md
rules  ok    38 rows and 2 personal permissions, 197 samples

harness      instructions  guardrails    sandbox       plugins       skills        config
Claude Code  ok            ok            n/a           ok            ok            ok
Cursor       FAIL          ok            ok            ok            ok            ok

FAIL  Cursor instructions: ~/.cursor/rules/global-instructions.mdc is stale; generate it again

• setup: ポインターとすべての setup/ ファイルを読み取ることができ、共有ファイルには setup/instructions.md が生成する内容が含まれています。ポインターにワークステーションリポジトリがないと記載されている場合は n/a です。
• rules: ルールテーブルの各行のすべてのサンプルと個人用権限について、フックがその行の回答を返します。
• 存在する各ハーネスの行。 各セルは ok、FAIL、ハーネスが対応できないかチェックで確認できない場合は gap、該当する領域がない場合は n/a です。列の内容は次のとおりです。
  • instructions: ハーネスが共有ファイルを読み取り、名前が指定されている場合は setup/harnesses.json から独自の指示を読み取り、メモリがオフになっていること。
  • guardrails: フックがインストール済みのスクリプトに接続されており、ハーネスにネイティブなルールがある場合は、各個人用権限にネイティブなエントリーがあること。
  • sandbox: ハーネスのサンドボックスと承認の設定。Cursor の実行モード、および宣言された Codex 設定のサンドボックスと承認のキーが対象です。
  • plugins: このハーネス用の各 setup/installs.json プラグインがインストールされ、有効になっていること。
  • skills: setup/installs.json に記載された各スキルが、このハーネスがスキルを読み取るフォルダーにあること。
  • config: 宣言された設定が設定している各キーが、ハーネスの設定ファイルで同じ値になっていること。宣言された設定がない場合は n/a です。デフォルトモデルはセットアップ領域のいずれにも該当しません。

FAIL の行またはセルがなければ実行は成功し、その後、検証ツールは 0 を終了コードとして返します。各 gap 行を報告してください。各ハーネスのリファレンスにある「Verification」セクションでは、その行で確認する内容を説明しています。

ルールテーブル

rules.json には、各グローバルルールが各ハーネスの形式ではなく、意味に基づいて一度だけ記載されています。行の各フィールド、各 match 種別、および表記については、references/rule-table.md を参照してください。各ハーネスのリファレンスでは、各行をそのハーネスのエントリーに変換しています。フックと verify.py は、scripts/setupmachine/rules.py を通じて同じ行を読み込みます。このスクリプトは、不正な形式の行を拒否します。ワークステーションリポジトリの setup/permissions.json には、同じ形式で個人用権限が記載されています。すべてのハーネス、フック、verify.py は、references/workstation.md > setup/permissions.json の説明どおり、テーブルの行と合わせてこれらの権限を使用します。

ツール実行前フック

scripts/pre_tool_hook.py は、各ツール呼び出しの前にすべてのハーネスが実行するフックです。Python 3.9 以降が必要で、標準ライブラリのみを使用します。rules.json と、ポインターを通じて個人用権限を読み込み、呼び出しをチェックします。

• deny 行：シェルで実行される方法に従ってコマンドを読み取り、ファイルツール、リダイレクト、MCP ツールもチェックします。呼び出しを拒否し、拒否した各部分について、そのルールの理由と指示を示します。
• allow-and-report 行：呼び出しごとに JSON の行を1つ、ユーザーだけが読み取れる <report-folder>/<date>.jsonl に書き込みます。アクセス権限はハーネスの設定に従います。
• ask 行：ハーネスのネイティブな確認エントリーが確認を行います。approver: "user" の行では、呼び出しの状況からユーザーへの確認が行われないとわかる場合、代わりに呼び出しを拒否します。該当するのは、auto、dontAsk、bypassPermissions モードの Claude Code、承認ポリシーが never の Codex、そして確認を保証できない Cursor と opencode でのすべての呼び出しです。詳細は各リファレンスを参照してください。Cursor には ask リスト自体がないため、そこでフックはすべての ask 行を拒否します。Pi にも ask リストはありませんが、拡張機能が確認できます。UI がある場合、フックは ask 行を示し、拡張機能が Pi のダイアログでユーザーに確認します。UI がない場合、references/pi/cli.md > 「Hook wiring」の説明どおり、フックはすべての ask 行を拒否します。
• allow 行：何もせず、ハーネスのネイティブな許可エントリーによって、確認なしで呼び出しが実行されます。

個人用ファイルの形式が不正な場合、テーブルの行は引き続き有効です。フックは個人用権限をスキップし、verify.py がそのファイルを報告します。

配線

各ハーネスの参照先には、スクリプトのパスの代わりに <script> を使った配線が記載されています。これを、インストール済みスキル内の scripts/pre_tool_hook.py の絶対パスに置き換えてください。場所は ~/.agents/skills または ~/.claude/skills の下とし、削除される可能性があるチェックアウトやワークツリーには置かないでください。インストール済みのコピーがない場合は、その不足を明記してください。verify.py は、スクリプトが別の場所にある配線を失敗と判定します。

配線はフェイルオープンの形式で、[ -f <script> ] && … || true と記述するか、ハーネスの参照先で示されている形式にします。スクリプトがなくなった場合は、各呼び出しがネイティブのエントリーのもとで続行されます。これがないと、python3 はスクリプトが見つからず終了コード 2 を返し、すべての呼び出しがブロックされます。例外は Pi です。下にネイティブのエントリーがないため、拡張機能はフェイルクローズし、フックが確認できない呼び出しを拒否します。詳細は references/pi/cli.md > 'Hook wiring' を参照してください。

<report-folder> は ~/.local/state/agents/reports、または ~/.config/agents/hook.json の report_dir です。

制限事項

各監査で、次の項目をそれぞれ一度記載してください。

• スクリプトファイル内のコマンド、または別のインタープリター（python -c）内のコマンド。
• 変数から組み立てられるコマンド（$cmd -rf x）。
• 別の場所で定義されたエイリアスまたは関数。
• 省略されたロングオプション（--recur）。
• refspec による強制プッシュ（git push origin +main）。
• シェルが展開する glob（cat .env*）。
• Codex の auto_review のような自動レビュアーが、approver: "user" の行に回答する場合。呼び出しのペイロードにレビュアーが表示されないためです。
• 各行固有の gap。

ハーネス

このスキルがセットアップするハーネスと環境の一覧です。id は setup/harnesses.json、installs.json、verify.py --harness、フックの --harness で使う値です。環境は --env と setup/harnesses.json の environments で使う値です。どれを使うかは、ワークステーションのリポジトリによって異なります。

ハーネス（id）	環境	参照先
Claude Code（claude-code）	cli、desktop、cloud	CLI とデスクトップアプリで共有する内容については claude-code/index.md を参照し、続いて cli.md、desktop.md、cloud.md を参照してください
Codex（codex）	cli、desktop	共通のセットアップについては codex/index.md を参照し、続いて cli.md または desktop.md を参照してください
Cursor（cursor）	cli、desktop、cloud	CLI とデスクトップアプリで共有する内容については cursor/index.md を参照し、続いて cli.md、desktop.md、cloud.md を参照してください
Grok Bot（grok-bot）	desktop	grok-bot/desktop.md：指示はメモリに保存され、権限、コネクター、シークレット、ルーティンはアプリに保存されます
opencode（opencode）	cli	opencode/cli.md
Pi（pi）	cli	pi/cli.md：フックの拡張機能だけが強制適用の手段です

環境を持つハーネスには、references/<harness>/<env>.md と scripts/setupmachine/harnesses/<harness>/<env>.py があります。環境を持たないハーネスには、references/<harness>.md とモジュールが 1 つあります。ハーネスまたは環境を追加するには、docs/design/set-up-machine.md > 'Extensibility' の説明に従って、ここに行を追加してください。

参照資料

• references/global-instructions.md：共有ファイルの構成、役割の表、作業上の合意事項と用語集、個人のワークフローに該当するもの、ハーネス独自のファイルの移動、メモリを無効にしておく理由について説明します。
• references/rule-table.md：各行のフィールド、match の種類、ハーネスに必要な表記について説明します。
• references/workstation.md：このスキルがワークステーションのリポジトリから読み取るもの（ポインター、setup/ 内のファイル、setup/harnesses.json が指すファイルとその形式）、それらから共有ファイルの個人用部分と個人向けの権限を生成する方法、インストール一覧、該当ファイルがない場合の実行について説明します。
• references/live-check.md：各ハーネスの実際のセッションの開始、プローブ、その動作の確認について説明します。
• references/remote-machine.md：リモートマシンやヘッドレスマシンでエージェントを実行する方法（ブラウザーを使わないサインイン、マシンごとの設定、セッションの維持、誤った判断をしたエージェントの封じ込め）について説明します。
  • references/new-remote-machine.md：新しいマシンで最初に行うセットアップについて説明します。ユーザーを root として、キーアクセスから、専用ユーザー、鍵のみの SSH、ファイアウォール、更新、スワップ、docker グループ、セッションホストとの連携、git 認証情報、SSH 経由の PATH、ヘッドレスブラウザーまで整えます。
• ハーネス環境ごとに参照資料が1つあります。見つかった環境ごとに読み込んでください。Harnesses の表に一覧があります。各ページの見出しはすべて共通で、Presence detection、Instructions、Guardrails、Sandbox、Plugins、Skills、Config、Hook wiring、Limitations、Verification です。それぞれのハーネスの index.md ですでに説明されている内容は省略します。バージョンやテストに照らして事実を確認したページには、末尾に Notes があり、上記のセクションでは現時点の事実のみを記載できるよう、確認の履歴を記録しています。

スクリプト

• scripts/pre_tool_hook.py：各ハーネスがツール呼び出しのたびに実行する、ツール実行前のフックです。
• scripts/cloud_bootstrap.py：Claude Code のクラウド環境のセットアップスクリプトから実行します。references/claude-code/cloud.md > 'Bootstrap' の説明どおり、ワークステーションのリポジトリからセッションをセットアップする手順をエージェントに提示します。
• scripts/verify.py：上記のチェックです。何も書き込みません。
  • --home <folder>：ホームフォルダーのコピーをチェックします。ハーネスは PATH 上の CLI ではなく、フォルダーだけを基準に検出されます。
  • --grok-bot-rules：references/grok-bot/desktop.md > 'Guardrails' の説明どおり、ルール表と個人向けの権限を Grok Bot の自動レビュー規則として出力します。
  • --harness <harness> [--env <env>]：1つのハーネスの行、または1つの環境の行（例：--harness cursor --env cloud）に絞ります。
  • --codex-trust-hash '<command>'：references/codex/index.md > 'Hook wiring' の説明どおり、フックコマンドに必要な Codex の trusted_hash を出力します。
• scripts/setupmachine/：両方のスクリプトが使用するモジュールです。harnesses/__init__.py には ALL の全環境が記載されています。ハーネスはパッケージ harnesses/<harness>/ で、環境ごとに1つのモジュールと、共有コードを含む __init__.py で構成されます。
• references/opencode/opencode-plugin.js：フックを呼び出す opencode プラグインです。
• references/pi/pi-extension.ts：フックを呼び出し、ask 行についてユーザーに確認する Pi 拡張機能です。