macOS Desktop — アプリからaachatを起動する

aachat DesktopはMacの前提条件を確認し、ローカルCLIの導入を支援し、runtimeを起動してブラウザでaachatを開くアプリです。Project・Session・文書の画面はWebUIにあります。アプリの案内で起動したい場合はDesktop、ターミナル・Linux・WSL2・headless運用ではCLIセットアップを使います。

インストールと準備

Mac用の配布物は公式Desktopリリースページから取得します。公開されている配布物の対象は Apple Silicon、macOS 14以上 です。AssetsのDMGを開き、aachatを Applications にコピーしてから起動してください。updater用archiveはアプリ更新向けで、通常の初回インストールには使いません。新しい版をダウンロードするときは、そのリリースの対応条件も確認します。

GitHubアカウント、Git、npmを含む Node.js 22以上、ローカルで導入・認証済みのcoding runtime（Claude CodeまたはCodex）が必要です。DesktopのGitHubサインインではcoding runtimeの認証は行われません。private repositoryを使う仕事では、ローカルのGit認証にもそのrepositoryへのアクセス権が必要です。

Applicationsからaachatを開きます。CLIが未導入なら先に Install aachat で導入し、その後はCLIから表示される案内に従います。
Sign in with GitHub からブラウザで認可し、aachatへ戻る操作を許可します。失敗した場合は Try sign-in again で新しい認証を完了します。
Install aachat が表示されたらmanaged CLIを導入します。Gitがなければ Install Git からmacOSの開発ツールのインストールを完了します。Download Node.js はダウンロードページを開く操作なので、インストールは自分で完了してください。
外部でのインストール後はアプリに戻ると、CLIが完了を確認して起動を進めます。ダウンロードページが開いただけでは導入完了ではありません。
準備が完了すると自動で起動し、ブラウザでaachatを開きます。以後はアプリを開くだけで起動します。必要なら Open aachat でも開けます。
Agentを取得し、セットアップに従ってLeadとBriefを指定したProjectを作り、最初のSessionの応答を確認します。Desktopのreadyはローカルruntimeの準備を示し、すべてのAgentの実行成功を示すものではありません。

ウィンドウを閉じたときとruntimeの起動元

ウィンドウを閉じる操作は非表示にするだけです。アプリの終了・更新やブラウザを閉じる操作でruntimeを停止しません。

DesktopはCLIに起動を依頼します。CLIがmacOSのlaunchdで一度だけruntimeを起動するため、アプリの終了・更新後もruntimeは動作を続けます。ログイン時の自動起動や異常終了時の自動再試行は行いません。起動に失敗したら表示された案内に従って再試行します。

既にターミナル等からruntimeが稼働していれば、そのまま使います。通常のaachat upは既存daemonを止めて置き換える場合があるため、状態確認にはaachat statusまたはaachat launcher statusを使います。アプリから起動したruntimeを止めるにはaachat launcher stopを使います。ターミナルで起動したruntimeは、そのターミナルのCtrl+Cで停止します。停止はローカルの仕事と同期を中断します。

認証、前提条件の確認、状態の判定と復旧はCLIが担当します。MacアプリはCLIが返す案内を表示します。強制終了で古い状態ファイルが残っても、CLIは排他ロックとプロセスの起動情報を確認して復旧します。ファイルを手動で削除する必要はありません。

アプリ更新とCLI更新

更新の表示はアプリの版によって異なります。以下の更新・復旧の説明は、更新欄に独立した Update and relaunch が表示される版を対象にしています。手元の表示が異なる場合は、表示されている操作と公式Desktopリリースページを確認してください。

Desktopはプロセス起動時やウィンドウを開き直したときに、アプリ自身の更新をバックグラウンドで確認します。Update ready と更新先の版が表示されたら、アプリ更新の準備ができています。表示された Update and relaunch で適用・再起動します。

更新欄に独立した Update and relaunch が表示される場合は、認証・導入・runtime復旧の主操作を先に完了しなくても更新を選べます。runtimeに問題があるときや準備中でも、更新候補があれば表示されます。ただし、別の操作の実行中は完了を待ちます。元の診断と復旧操作は残り、アプリ更新がruntimeの問題まで解決する保証はありません。

Later は更新候補があるときに表示されます。認証や環境設定の途中でも延期できます。アプリ更新の表示・延期・失敗によって、CLIの状態や起動・利用・復旧の操作は変わりません。

この操作が更新するのはDesktopアプリです。aachat updateはCLIを更新し、aachat upも起動時にCLI更新を確認します。それぞれ版と配布物が異なります。Desktop更新の完了だけで、CLIや実行中のcoding-agent Sessionの版まで変わったとは判断しません。

起動・更新が止まったとき

表示・状況	対処
Git、Node.js、npmが不足	外部でインストールを完了し、アプリに戻って確認を待ちます。Node.jsは22以上が必要です
GitHubサインインが終わらない	Try sign-in again で新しいブラウザ認証を完了し、アプリへ戻ります
起動後に Action needed	理由を読み、前提やruntimeの問題を解決してから Try again を使います
runtime statusが不正、またはプロセスを確認できない	表示された理由を添えて Open aachat support へ進みます。終了済みプロセスの残存記録はCLIが復旧します
`aachat`と`chat`の版が違う	CLIインストールの案内に従ってmanaged CLIを揃え、再確認します
バックグラウンドの更新確認に失敗	確認失敗だけではruntimeの状態・理由・主操作は変わりません。表示されている起動・利用・復旧操作に従います。更新候補がないことを、更新適用失敗やruntime停止とは判断しません
アプリ更新の適用に失敗	アプリ更新欄の Open update support を使います。CLIの起動・利用・復旧の操作は引き続き使えます
更新適用後の再起動が完了しなかったと表示される	アプリ更新欄の Open Applications からアプリを開きます。CLIの状態と操作は保持されます
アプリはreadyだがAgentが動かない	トラブルシューティングで対象Agentのruntime認証、owner、Launch Reportを確認します

更新の適用・再起動失敗だけで、稼働中のruntimeも停止・失敗したとは判断しません。問い合わせには更新のどの段階で止まったか、元の復旧操作、アプリの理由と版、aachat --version、aachat statusの必要部分を秘密情報を除いて添えます。JWTファイル、API key、環境変数のsecret値は含めないでください。導入後に仕事用secretを渡す手順はEnvironmentを参照してください。