チュートリアル: 最初の実践タスク
スタートガイド では、5 分でインストールしてチャットする方法を学びました。このチュートリアルは次のステップです: ADHDev が実際に 何のためのものか を実際に体験するハンズオンの過程 — 実際のコーディングエージェントを実行し、その動作を制御し、そして（オプションで）Repo Mesh を通じて複数のマシンにわたって作業を調整し、Refinery に main へ着地させます。
各パーツが動作するのを見られるように、すべて手作業で行います。最後には、ADHDev が提供する 4 つのもの — Refinery、あらゆるエージェント、あなたのマシン、リモート制御 — を、箇条書きとしてではなく、実際に動かした経験から理解できるようになります。
必要なもの
adhdevCLI がインストールされていること（なければ スタートガイド を参照）。- マシンに少なくとも 1 つの CLI エージェントがインストールされ、認証されていること — Claude Code、Codex CLI、Gemini CLI、またはその他。ADHDev はエージェント自身のログインを管理しません。エージェントが自身の認証を保持します。
- エージェントに小さな変更をさせても構わない git リポジトリ。
このチュートリアル全体は Standalone モード（アカウント不要）で動作します。最後の Repo Mesh セクションは Cloud のみ です — 明確に示されており、それより前のすべての内容は独立しています。
ステップ 1 — Standalone を起動してダッシュボードを開く
adhdev standaloneこのコマンドは、組み込みデーモン（localhost:3847）とローカルダッシュボード（localhost:3000）を一緒に起動します。http://localhost:3000 を開いてください。
見えるもの: ローカルマシンが online としてリストされたダッシュボード。ログイン画面はありません — standalone は完全にローカルです。
📸 [スクリーンショット: standalone ダッシュボード、マシン 1 台が online、空のセッションリスト]
なぜ重要か: これがコントロールプレーンです。ここから先、エージェントが行うすべて — チャット、ツールコール、承認 — が、このブラウザとデーモンの間を P2P で流れます。ダッシュボードはすべてのセッションに対するあなたの単一のビューであり、まもなく表示するセッションが 1 つできます。
動作確認
ダッシュボードが空だったりマシンが offline と表示される場合は、別のターミナルで adhdev doctor を実行してください。デーモンプロセス、ローカル接続、プロバイダーレジストリを確認し、具体的な修正方法を指し示します。
ステップ 2 — ADHDev が駆動できるものを確認する
起動する前に、このマシンで検出されたものを確認してください:
adhdev detect見えるもの: installed: yes/no が付いた既知のプロバイダーのリスト。yes のものはすぐに起動できます。
なぜ重要か: プロバイダー は ADHDev の 1 つのエージェントに対するアダプターで、4 種類あります — ここでは最初のものから選びます:
| カテゴリ | トランスポート | 例 |
|---|---|---|
| cli | PTY（ターミナル） | Claude Code, Codex CLI, Gemini CLI, Hermes CLI |
| ide | Chrome DevTools Protocol | Cursor, VS Code, Windsurf, Kiro, PearAI, Trae |
| extension | CDP webview | Antigravity |
| acp | stdio（Agent Client Protocol） | ACP 互換エージェント |
このチュートリアルでは cli プロバイダーを使います — 動作するセッションに最も早く到達でき、エディターの再起動が不要です。
ステップ 3 — CLI エージェントセッションを起動する
installed: yes と表示された CLI エージェントを選んでください。例えば:
adhdev launch claude # Claude Code
# or: adhdev launch codex / adhdev launch geminiデーモンが PTY のもとでエージェントを起動し、ターミナルをダッシュボードにストリーミングします。
見えるもの: ダッシュボードに新しいセッションカードが現れます。クリックすると、下部に入力ボックスがあるライブターミナルビューが開きます。
📸 [スクリーンショット: セッションカード + 入力ボックスのある開いたターミナルビュー]
なぜ重要か: エージェントは あなたの マシンで、あなたの 作業ディレクトリで、それ自身の 認証で実行されます — ADHDev はそれへの窓を提供するだけです。エージェントの挙動については何も変わっていません。その上にコントロールプレーンを追加しただけです。
作業ディレクトリ
セッションは起動したディレクトリで実行されます。エージェントに作業させたい git リポジトリを指定してください — adhdev launch の前に cd で移動するか、ダッシュボードの起動フローからリポジトリを開いてください。
ステップ 4 — チャットし、承認の制御を保つ
セッションの入力ボックスで、エージェントに小さく実際的なことを依頼してください。例えば:
このリポジトリを見て、それが何をするものかを説明する 1 行の説明を README の先頭に追加して。
ローカルターミナルで行うのと同じように、入力して Enter を押してください。
見えるもの:
- エージェントの応答がリアルタイムでダッシュボードにストリーミングされます — ローカルターミナルで見られるのと同じトークン。
- エージェントがツールを実行したりファイルを編集したいとき、ACTION REQUIRED バナーが Approve と Reject のボタンとともに現れます。
📸 [スクリーンショット: Approve / Reject のある ACTION REQUIRED 承認バナー]
Approve をクリックして編集を通す（または Reject で拒否する）と、決定が P2P チャネルを通じてデーモンに伝わり、エージェントが続行します。
なぜ重要か: これがヒューマン・イン・ザ・ループの制御です。エージェントは、あなたが見ていないコマンドを静かに実行することは決してありません — すべてのツールコールとファイル編集が、あなたが所有する承認として表面化します。その同じバナーが、キーボードから離れても引き続き主導権を保てるようにしてくれます。それはまさに次のステップが土台にするものです。
画像を添付する
チャット入力は画像の添付（最大 5 枚、各 10 MB）を受け付けます — バグのスクリーンショットや、エージェントに合わせてほしいデザインを貼り付けるのに便利です。
ステップ 5 — スマートフォンから承認する（Cloud）
Cloud Only
このステップは Cloud バージョン が必要です。Standalone は単一マシンかつローカル専用なので、リモートから承認するサーフェスがありません。standalone を使っている場合は 次のステップ にスキップしてください — すでに中核となるループを見終えています。
ステップ 4 の承認バナーは、エージェントが実行されるマシンに縛られていません。クラウドモードでは、スマートフォンのブラウザで adhf.dev にサインインすると、同じ Approve / Reject バナーがそこに現れます — レスポンシブなレイアウト、同じ P2P 承認フロー。
📸 [スクリーンショット: モバイルの承認バナー]
見えるもの: エージェントがデスクでツールコールに一時停止し、承認がスマートフォンに表示され、あなたが Approve をタップし、エージェントが続行します。
なぜ重要か: 長時間実行される作業を開始して、その場を離れることができます。エージェントは、あなたがどこにいても、あらゆる決定ポイントで停止し あなたを 待ちます。（スマートフォンは承認を 受け取り、答え ます。新しいタスクのディスパッチはデスクトップ/CLI のアクションのままです。）
ステップ 6 — Repo Mesh で複数のマシンを調整する（Cloud）
Cloud Only
Repo Mesh は同じアカウントの複数のデーモンを調整するもので、Cloud バージョン でのみ利用可能です。これは単一のダッシュボードの上のレイヤー — 1 つの コーディネーター が多数のマシン（または多数の分離されたワークツリー）のエージェントに作業を渡し、結果を収束させます。概念については完全な Repo Mesh ガイドを参照してください。ここでは 1 つを配線するだけです。
ここまでは、1 つのセッションで 1 つのエージェントを駆動してきました。Repo Mesh は、それを 1 人が多数のエージェントを調整する ことへと変えるものです。最小のエンドツーエンド版を示します。
1. リポジトリ用の mesh を作成する。 リポジトリの内部から（git リモートが自動検出されるように）:
adhdev mesh create my-project --add-current--add-current は、現在のワークスペースを mesh の最初のノードとしても登録します。コマンドは mesh ID（例: mesh_abc123）を出力します。
見えるもの: mesh ID、検出されたリポジトリの identity、ブランチが表示された確認メッセージ、続いて「Next steps」のヒント。
2. 別のノードを追加する。 2 台目のマシンで（または分離されたワークツリーとして）、同じ mesh に追加します。ワークツリーは、並列エージェントが互いの作業ツリーを踏み荒らすのを防ぎます:
adhdev mesh add-node mesh_abc123 --worktree --provider-priority claude-cli,codex-cli--provider-priority は、タスクがエージェントを指定しないときにどのエージェントを起動するかをノードに伝えます — 優先順位が設定されていないノードは、推測する代わりに自動起動を拒否します。
3. mesh の形を確認する。
adhdev mesh show mesh_abc123 # nodes, policy, per-node launch readiness
adhdev mesh status mesh_abc123 # live per-node git health (branch, dirty, ahead/behind)📸 [スクリーンショット: adhdev mesh status の出力、ブランチ + clean/dirty のノード群]
なぜ重要か: これで、1 つのコーディネーターのもとに 2 つ以上のワークスペースが登録されました。クラウドダッシュボードの Repo Mesh ページ（/mesh）から、ミッション に対してタスクをキューに入れると、アイドルなノードが自律的に作業をプルします — あるノードで Claude Code、別のノードで Codex。特定のマシンにタスクをプッシュして見張る必要はありません。速いアイドルなノードがキューを消化し、コーディネーターはポーリングの代わりに完了イベントを監視します。各タスクは pending → assigned → completed（または failed）の順に移動します。
ステップ 7 — Refinery に作業を着地させる（Cloud）
Cloud Only
Refinery は Repo Mesh の収束の一部として実行されます。
並列エージェントをスポーンするのは簡単な部分です。それらが生み出したものをマージするのが難しい部分です — そして、これこそが ADHDev が存在する理由です。
分離されたワークツリーブランチでタスクが完了すると、Refinery はそのブランチを、force-push を一切せずにベースへ収束させます。一連のゲートを実行します: リポジトリの収束設定を読み込み、ワークツリーをブートストラップし、リポジトリ自身の 検証（typecheck / テスト / lint）を実行し、no-op ガード と パッチ同等性 チェックを適用し、サブモジュールコミットを 公開 し、ベースへの fast-forward のみのマージ を行い、ワークツリーを クリーンアップ します。
触れられたすべてのブランチは正確に 1 つの最終状態に着地するので、何も静かにはぐれたブランチに残されることがありません:
| 最終状態 | 意味 |
|---|---|
merged_to_main | 収束してきれいにマージされた。 |
pushed_feature_branch_needs_merge | プッシュ済み、あなたが行うマージを待っている。 |
blocked_review | 人間のために保留 — 例: サブモジュールコミットがまだサブモジュールの origin から到達できない。 |
cleanup_candidate | 作業は着地済み。ワークツリーは削除可能。 |
not_mergeable | fast-forward できない。Refinery は拒否してあなたに求めます — 競合を盲目的に解決する代わりに。 |
📸 [スクリーンショット: merged_to_main で終わる Refinery の収束ログ]
なぜ重要か: これが「10 個のエージェントが実行された」と「10 個のブランチが安全に着地した」の違いです。Refinery は git ネイティブで、意図的に保守的です — あなたの ゲートに対して検証し、fast-forward しか行いません。きれいに着地できないもの（実際の競合、到達できないサブモジュールコミット）は、静かなマージではなく not_mergeable または blocked_review としてあなたに戻ってきます。マージデーの二日酔いなしに並列性を手に入れられます。
あなたが今やったこと
ADHDev を通じて実際のエージェントを実行し、その全過程を通じて制御を保ちました:
- リモート制御 + HITL — ダッシュボードからライブセッションを駆動し、すべてのツールコールを承認しました（クラウドモードではスマートフォンから）。
- あらゆるエージェント — プロバイダーアダプターを通じて CLI エージェントを起動しました。同じフローが Codex、Gemini、CDP 経由の IDE、ACP エージェントにも適用されます。
- あなたのマシン — エージェントはあなた自身のハードウェアで、自身の認証で、あなたのダッシュボードのもとで実行されました。
- Refinery — （クラウド）mesh にノードを登録し、完了した作業が検証ゲートを通じて
mainへ収束する様子を、すべてのブランチに対する明確な最終状態とともに見ました。