エージェント駆動の新規マシンセットアップ

このページは、まっさらな新規マシンに ADHDev をセットアップするよう指示された AI コーディングエージェント（Claude Code、Codex、Hermes など）に向けて書かれています。以下の番号付きの手順を順番にたどり、各コマンドを書かれているとおりに正確に実行してください。

人間の読者の方へ: このページをエージェントに渡して 「新規マシンガイドに従ってこのマシンに ADHDev をセットアップして」 と伝えれば、あなたにしか承認できないブラウザサインインの 1 ステップを除いて、エージェントがすべてを行います。

目標は、クリーンなマシンから、可能な限り人間の関与を減らしてデーモンを起動し、最初の adhdev launch にたどり着くことです。人間を必要とするのは正確に 1 つ のステップ — クラウドのブラウザサインイン — だけで、そこには明確な印が付いています。

まずモードを選ぶ

ADHDev は 2 つのモードで動作します。始める前に決めてください。インストールコマンドは同一で、アカウントのフローだけが異なります。

	A — スタンドアロン	B — クラウド
アカウント / ログイン	なし	GitHub または Google（ブラウザサインイン）
人間のステップの要否	不要 — 完全に自律	必要 — ブラウザ承認 1 回
ダッシュボード	`http://localhost:3000`	`https://adhf.dev`
適した用途	単一マシン、ローカル利用、アカウント不要、完全無人セットアップ	マルチマシン、リモートアクセス、共有、Repo Mesh

エージェント向けの目安: ユーザーがクラウド/マルチマシン/リモート機能を求めていないなら、スタンドアロン (A) を選んでください — 人間もアカウントも不要です。クラウド (B) は、ユーザーが明示的にアカウント、リモートアクセス、または mesh を望んでいて、ブラウザサインインを承認できる状態にあるときにだけ選んでください。

ステップ 1 — 前提条件を確認する

ADHDev には Node.js ≥ 22 が必要です。

bash

node --version

Node ≥ 22: 問題ありません。続けてください。
Node がない、または Node < 22: インストールスクリプト（ステップ 2）がランタイムをブートストラップします（macOS/Linux では nvm/fnm/brew/apt/dnf/yum、Windows ではポータブル Node 22）。先に自分で Node を入れたい場合は 22.x LTS をインストールしてください — Windows に Node 24+ をインストールしてはいけません（下の警告を参照）。

Windows + Node 24+

Windows では、Node.js 24+ 上でのグローバル npm install -g adhdev はブロックされます。代わりに PowerShell インストーラーを使ってください — ~/.adhdev/tools/node22 の下にポータブルな Node.js 22 をプロビジョニングし、それを使います。新しい Node を強制して回避しようとしないでください。

ついでに OS も確認しておき、ステップ 2 で正しいインストールコマンドを選べるようにしてください: macOS、Linux、Windows のいずれかです。

ステップ 2 — CLI をインストールする（無人）

インストールスクリプトはプラットフォームを検出し、Node.js がなければインストールし、adhdev を PATH に配置します。

無人のエージェント駆動セットアップでは、ADHDEV_NO_SETUP=1 を設定して、インストーラーが インストールのみ を行い、対話式のセットアップウィザードを 起動しない ようにしてください（セットアップは後続の手順であなた自身が進めます）。

macOS / Linux:

bash

ADHDEV_NO_SETUP=1 curl -fsSL https://adhf.dev/install | sh

Windows (PowerShell):

powershell

$env:ADHDEV_NO_SETUP=1; iwr https://adhf.dev/install.ps1 -useb | iex

すでに Node ≥ 22 がある場合（どのプラットフォームでも）:

bash

npm install -g adhdev

Homebrew (macOS / Linux) — 別途 Node は不要:

bash

brew tap vilmire/adhdev && brew install adhdev

Homebrew は独自の Node.js ランタイムを同梱します。上記の無人インストールスクリプトは、macOS で brew が存在する場合すでにこの経路を自動的に優先するため、通常は手動で実行する必要はありません。

オプション: preview チャンネル

ADHDEV_CHANNEL=preview を設定すると、stable ではなく @next（リリース候補）ビルドをインストールします。通常の stable インストールでは省略してください。Homebrew tap は stable リリースのみを追跡するため、preview のインストールは常に npm 経由になります。

インストールを検証する:

bash

adhdev --version

これはバージョン番号を表示するはずです。インストーラーは 現在のセッションに対して PATH を更新し、さらに恒久的に登録するため、通常はすぐに動作します — 新しいターミナルは不要です。

それでも command not found になる場合（PATH の変更を取り込まない制限の厳しいシェルなど）、新しいターミナルを開かずに 使えるフォールバックが 2 つあります:

安定した shim をフルパスで呼び出す（インストーラーは常に adhdev をここに配置します）:
powershell
```
# Windows
& "$HOME\.adhdev\npm-global\adhdev.cmd" --version
```
bash
```
# macOS / Linux
"$HOME/.adhdev/npm-global/bin/adhdev" --version
```
Windows のポータブル Node による脱出口 — shim 自体が動かない場合（例: CLI は配置されたが node.exe への PATH が古い）、インストーラーがプロビジョニングしたポータブル Node 22 で、インストール済みの CLI エントリを直接呼び出します:
powershell
```
& "$HOME\.adhdev\tools\node22\node-v22.*-win-x64\node.exe" "$HOME\.adhdev\npm-global\node_modules\adhdev\dist\cli\index.js" --version
```

それ以外の場合、新しいターミナル を開けば必ず動作します（PATH は恒久的に登録されています）。

ステップ 3 — デーモンを起動する

モード A — スタンドアロン（ログイン不要）

スタンドアロンにアカウントは不要です。直接起動してください:

bash

adhdev standalone

これは localhost:3847 でデーモンを、localhost:3000 でダッシュボードを、認証なし で起動します。ステップ 4 は完全にスキップして、ステップ 5 に直行してください。

オプションの LAN アクセス: adhdev standalone --host 0.0.0.0 --token <some-secret>。--token は任意で、スタンドアロンを localhost の外に公開する場合にのみ関係します。

モード B — クラウド（ログイン必須）

クラウドにはアカウントが必要です。ステップ 4 のサインインが 唯一の人間のステップ です。ステップ 4 でマシンがオンラインになったと報告されるまで、adhdev daemon を実行 しないで ください。

ステップ 4 — サインイン（クラウドのみ）⏸ 人間のステップ

⏸ 人間のステップ — エージェントはここで停止すること

クラウドのサインインは、人間が承認するためにブラウザを開く OAuth デバイスフロー を使います。非対話のログインフラグは存在せず、これは意図的です — アカウント認可は、人が一度だけ越えるセキュリティ境界として設計されています。

環境変数やその他のサイドチャネルでマシンシークレットを注入して、これを迂回しようと 決してしない でください。それはサポートされておらず、文書化もスクリプト化もしてはいけません。

このステップにおけるエージェントへの指示:

自分でログインコマンドを実行して待たないこと。 代わりにユーザーにこう伝えてください: 「サインインをお願いします。adhdev setup（エイリアス adhdev login）を実行し、GitHub または Google アカウントでブラウザのプロンプトを承認してください。」
一時停止してユーザーに制御を渡すこと。 サインインが保留中の間は先に進まないでください。
アカウントが認可されたときにのみ再開すること。 adhdev status をポーリングし、マシン/アカウントがオンラインと報告されたときにのみステップ 5 に進んでください。それまでは待ち続け、インストールやデーモンのコマンドを再試行しないでください。

人間の方へ: 以下を実行し、adhf.dev に対して開くブラウザタブを承認してください:

bash

adhdev setup    # or: adhdev login

サインインには GitHub または Google の 検証済みメールアドレス が必要です。そうでなければ拒否されます。ブラウザで承認したら、制御をエージェントに戻してください。

その後、クラウドデーモンを起動します（バックグラウンドで長時間稼働）:

bash

adhdev daemon

デーモンは api.adhf.dev に接続し、マシンを登録し、マシン ID を表示します。

ステップ 5 — 検証する

デーモンが正常であることを確認します:

bash

adhdev status

期待される結果:

スタンドアロン: デーモンが localhost:3847 で正常と報告される。
クラウド: マシンが online と表示され、api.adhf.dev に接続されている。

ステータスが正常でない場合は、起動前に下記のトラブルシューティングを参照してください。

ステップ 6 — 最初のエージェントを起動する

ユーザーがすでにインストールしている CLI エージェントを起動します:

bash

adhdev launch claude    # Claude Code
# or:  adhdev launch codex-cli
# or:  adhdev launch <target>

adhdev launch <target> はデーモン配下でエージェントを起動し、ダッシュボードにミラーリングします。ADHDev はエージェント自身の API キーやログインを管理 しません — 各ツールが自分の認証を保持します。エージェントが自分の資格情報を要求する場合、それは ADHDev ではなくそのエージェントの UI で処理されます。

完了です。 これでデーモンが動作し、ダッシュボードが接続され、最初のエージェントが稼働しています。

トラブルシューティング

command not found: adhdev — インストーラーは現在のセッションについても PATH を更新するため、これはまれです。発生した場合は、新しいターミナルを開く代わりに安定した shim をフルパスで呼び出してください: & "$HOME\.adhdev\npm-global\adhdev.cmd"（Windows）または "$HOME/.adhdev/npm-global/bin/adhdev"（macOS/Linux）。shim すら動かない場合の Windows 限定の最終手段: & "$HOME\.adhdev\tools\node22\node-v22.*-win-x64\node.exe" "$HOME\.adhdev\npm-global\node_modules\adhdev\dist\cli\index.js"。新しいターミナルを開くのも有効です — PATH は恒久的に登録されています。
Node < 22 — 22.x LTS をインストールしてください（またはインストーラーにブートストラップさせてください）。ADHDev はそれより古い Node では動作を拒否します。
Windows で Node 24+ のときインストールが失敗する — Node 24+ 上の npm install -g ではなく、PowerShell インストーラー（ポータブル Node 22）を使ってください。
Windows の PSSecurityException / ...\adhdev.ps1 について「スクリプトの実行が無効になっているため読み込めません」 — デフォルトの Restricted 実行ポリシーが npm 生成の PowerShell shim をブロックしています（PowerShell は adhdev.cmd より adhdev.ps1 を優先します）。インストーラーは現在のユーザーに対してこれを自動的に緩和します。それがブロックされた場合（グループポリシーなど）は自分で Set-ExecutionPolicy -Scope CurrentUser RemoteSigned を実行するか、.cmd を呼び出して .ps1 を完全に迂回してください: & "$HOME\.adhdev\npm-global\adhdev.cmd" --version。
デーモンがオンラインにならない（クラウド） — adhdev status を実行してください。オフラインのままなら、サインアウトして入り直します: adhdev logout の後に adhdev setup、そして再度 adhdev daemon。
起動後にエージェントが応答しない — adhdev status（デーモンは正常か？）を確認し、その後対象のプロバイダーがインストールされているか確認してください。

ブートストラップスクリプト

人間のステップのガードレールを組み込んだ状態で、ステップ 1〜6 を自動化する付属の Node スクリプトがあります: scripts/bootstrap-new-machine.mjs。

bash

# See exactly what would run, without executing anything:
node scripts/bootstrap-new-machine.mjs --mode standalone --dry-run

# Fully unattended standalone setup:
node scripts/bootstrap-new-machine.mjs --mode standalone --yes

# Cloud: runs up to the sign-in, then stops and waits for you to approve in the browser:
node scripts/bootstrap-new-machine.mjs --mode cloud --yes

フラグ:

--mode cloud|standalone — どちらのモードをセットアップするか。
--yes — 無人モード。追加の確認なしにインストール/デーモンを実行します。これがない場合、破壊的なステップは説明されるだけで実行されません。
--dry-run — コマンドを表示するだけで、何も実行しません。プレビューのため最初にこれを使ってください。

cloud モードでは、スクリプトは意図的に サインインのステップで停止し、ブラウザ承認の指示を表示し、その後マシンがオンラインになるまで adhdev status をポーリングしてから再開します — 上記の ⏸ 人間のステップを反映しています。資格情報を注入することは決してありません。

エージェント駆動の新規マシンセットアップ ​

まずモードを選ぶ ​

ステップ 1 — 前提条件を確認する ​

ステップ 2 — CLI をインストールする（無人） ​

ステップ 3 — デーモンを起動する ​

モード A — スタンドアロン（ログイン不要） ​

モード B — クラウド（ログイン必須） ​

ステップ 4 — サインイン（クラウドのみ）⏸ 人間のステップ ​

ステップ 5 — 検証する ​

ステップ 6 — 最初のエージェントを起動する ​

トラブルシューティング ​

ブートストラップスクリプト ​

エージェント駆動の新規マシンセットアップ

まずモードを選ぶ

ステップ 1 — 前提条件を確認する

ステップ 2 — CLI をインストールする（無人）

ステップ 3 — デーモンを起動する

モード A — スタンドアロン（ログイン不要）

モード B — クラウド（ログイン必須）

ステップ 4 — サインイン（クラウドのみ）⏸ 人間のステップ

ステップ 5 — 検証する

ステップ 6 — 最初のエージェントを起動する

トラブルシューティング

ブートストラップスクリプト