セットアップ — インストールから最初の依頼まで

問題が起きたら aachat support を起動してください。診断・修復・確認を案内します。ターミナルと選択したCLIが必要です。既定はClaude Codeで、Codexは aachat support --provider codex で選択できます。症状やSession ID・失敗codeは起動後に伝え、秘密情報はコマンド引数に入れないでください。

サインインからProjectへの最初の依頼までを順に進めます。各段階の結果を確認すると、途中で止まったときに対処が必要な場所を判断できます。MacではDesktop 1.0のガイドとの会話でこの準備を進めることもできます。

aachatのコマンドは、up・support・manage-agentを除き、stdoutに共通のJSON（{ok,data?,error?,warnings?,next_actions?}）を1つ返します。以下の「判定」はこのJSONの値で示します。

外部エージェントから始める

ClaudeやChatGPTの会話から接続する場合は、Connected appsを参照してください。MCP URL、アカウントと本人Agentの準備、Teamの許可、6操作、解除の手順を案内しています。以下のセットアップは、そのAgentが使う通常のaachat実行環境を準備するものです。

CodexやClaude Codeに、次の依頼文を貼り付けてください。セットアップから最初の仕事の依頼まで進められます。

https://aachat.io/orchestration-skill.md を読んで、
aachatをセットアップし、最初の仕事を依頼するところまで進めてください。

エージェントはリンク先の案内に従って次の順に進めます。

1. orchestration-skill.mdをSKILL.mdとして、参照ファイル4つ（references/のsetup.md・operations.md・delegation.md・improvement.md）と一緒にユーザーのskillディレクトリへ保存する。Codexは$HOME/.agents/skills/aachat、Claude CodeはCLAUDE_CONFIG_DIR（未設定なら$HOME/.claude）の下のskills/aachat。skillの取得にCLI・認証・runtimeは不要で、CLIが既にある場合も同じ手順を使う。
2. 公式installer（https://aachat.io/install）の内容を確認してからCLIを導入する。
3. Macではaachat launcher statusで次の操作を確認し、Linux・WSL2ではaachat up --if-stoppedでruntimeを起動する。
4. 既存のTeam・Agent・Projectを確認し、必要なものだけを作って最初の依頼を受け付けさせる。

GitHubアカウントの作成、ブラウザでの認可、Claude Code / Codexのloginは本人の操作が必要で、途中で案内されます。接続repoは不要です。エージェントは共通のlocal state root（既定~/aachat、AACHAT_HOMEで変更可）から作業し、コマンドには常に--teamを明示します。ファイル権限を広げる前に、対象の絶対path（例: ~/aachat/teams/<team>/projects/<project>）と読み書きの範囲を示して同意を求めます。自分でセットアップする場合は、以下の手順を進めてください。

前提条件

未インストールのものがあれば、それぞれの公式手順で先に済ませる。npm経由でClaude Codeを入れている場合も node --version が22以上であることを確認する。

サインイン

ブラウザで aachat.io を開き、GitHubでサインインする。完了すると個人team（slugは通常 ~<login>）が自動作成され、Homeが開く。

判定: Home画面が開き、チームメニューに個人teamが表示される。

CLIのインストール

curl -fsSL https://aachat.io/install | sh

aachat 本体と、Session内のagentが使うchat、aachat-mcp、更新用のaachat-updateが ~/.cargo/bin に入り、シェルの設定ファイルにPATHが追記される。aachatとchatは同じ版である必要がある。

aachat --version

バージョンが表示されればインストール完了。command not found の場合はターミナルを開き直す。インストーラーが追記したPATHは、開いたままのターミナルには反映されないことがある。

認証

aachat auth login

ローカルの gh トークンから短命JWTを発行し、~/aachat/.run/tokens/user.jwt にキャッシュする。gh が認証済みであれば対話は発生しない。通常のコマンドもキャッシュが無効ならghから取り直すため、auth loginは明示的に更新したいときに使う。

判定: "ok": true で、data.auth.state が "valid"、data.auth.user.name が自分のGitHub login。ghが未認証ならauthentication_requiredが返るので、gh auth loginの後に再実行する。

• aachat auth status: キャッシュの状態（valid / expired / invalid / missing）と期限をローカルだけで確認する
• aachat auth logout: キャッシュしたJWTを削除する。GitHub側の認証は変えない

セットアップで問題が起きたら

aachat support

support agentは初期doctor結果から次の内容を確認します。利用者が最初に診断コマンドを選ぶ必要はありません。

GitHub CLIとtokenのscope、Node.js、chatの版の一致、runtime用PATH、aachat APIへの接続、ログイン状態（User JWT）、workspaceの状態をread-onlyで診断する。Linuxではloginctlのlinger、WSL2ではuser service managerの状態も確認する。offlineだけでsystemdの未設定とは断定せず、設定の確認方法を案内する。

data.diagnostics.issuesのcategory・code・target・next_actionsを読む。障害はissues_found、未確認はincomplete、作業保全・保守の指摘はattention_neededとなる。保守をすべて解消しないと利用できないという意味ではない。期限内に終わらない検査はunknownとなり、全pathが返るとは限らない。全項目はaachat doctor --view checksで見られる。

healthyは実施範囲で指摘なしという意味。Claude/Codexなどのproviderのinstall・認証・モデル呼出は検査しない。利用するproviderのCLIで認証を別に確認し、aachat upのLaunch Reportと最初のSessionで起動を確認する。

agentの取得

経路は3つある。どの経路でも、作られるものは同じ — agentの実体である1つのGitHub repoと、それを参照するteam上の登録である（agent repoの構造は agents）。

WebUIで作成するときはGitHub repo欄を未指定にできる。その場合、初回のaachat upがghでtemplateからprivate repoを作成する。既存repoを指定した場合はそのrepoを使い、空repoへの雛形補完は保証しない。

判定: サイドバーのAgentsに自分のagentが現れる。

runtimeの起動 — aachat up

aachat up

自分が所有するすべてのagentのruntimeを、1つの常駐プロセスでまとめて起動する。realtime controlにはWebSocket、transcript永続化とproject操作にはHTTPS APIを使う（境界の全体像はtrust-boundary）。このプロセスが動いている間だけagentは依頼を受けられるため、ターミナルは開いたままにする。Ctrl+Cで全agentが停止する。

判定: ターミナルに ● <agent-name> ready が表示され、WebUIのAgentsでオンライン表示になる。dormantのagentは ○ <agent-name> dormant と表示され、起動しない。

自動更新と再起動

~/.cargo/binに導入したaachatで起動した場合、aachat upは次のように自分を更新する。

• 起動時に更新を確認し、新しい版を導入したら更新後のバイナリで再execする。起動時の更新確認が失敗すると、aachat upはエラーで終了する。
• 稼働中は1時間ごとに、実行中のagent turnがなくなるのを待って確認する。新しい版を導入した場合は再びidleを待ち、通常のshutdownを行って再execする。idle確認後に始まったturnはshutdownで中断される場合があり、人間の応答待ち中に停止したSessionは自動再開されない。
• serverとのsync protocolが合わずに停止した場合は、通常の停止・保存の後に一度更新し、導入された版が実行中と異なれば同じ引数で再起動する。途中で止まったSessionの続きは人間が選ぶ。

明示的な更新にはaachat updateを使う（運用コマンドの役割）。

起動の選び方とログ

• 通常のaachat upは、既に動いているruntimeがあれば停止して置き換える。実行中のローカルの仕事に影響する。
• aachat up --if-stoppedは、有効なruntimeが稼働していればそれに触れず、"disposition": "already_running"のJSONを返して終了する。停止していれば起動し、その呼び出しが常駐する。
• aachat up --eventsは、起動・ready・終了などの状態を1行1つのJSON（JSON Lines）でstdoutへ出す。スクリプトから起動を待つときに使う。
• どちらもOSサービスへの登録や、マシン再起動後の自動復旧は行わない。旧Desktop 0.xはCLI launcher経由で起動する。Desktop 1.0自身にはruntimeの起動・停止機能はなく、ガイドが通常のCLIで操作する（Desktop）。

端末には失敗の影響と原因の分類、復旧の通知が表示され、同じ失敗の繰り返しは60秒ごとにまとめて表示される。詳細は~/aachat/.run/logs/up.logにあり、起動の結果は=== Launch Report ===の節に記録される。ログは起動ごとと10 MiBごとにup.log.1〜up.log.8へ回され、現行を含め最大9ファイルを保持する。RUST_LOG（例: RUST_LOG=aachat=debug）は端末とファイルの両方に効く。Session個別の実行ログはaachat session logs <session-id>で読む。

Claude / Codexのruntime別前提

• Claude: claude --versionが通り、Claude Codeが認証済みであること。team workspace repoが持つhooks / MCP / plugins / commands / allow-deny設定はsessionへ継承され、aachatに必要なpermissionとmergeされる。~/.claude/settings.json の env.CLAUDE_CONFIG_DIR が設定されている場合、aachatはそのディレクトリを指定してClaudeを起動し、sessionとUsageはそこに保存されたログインを使う
• Codex: Codex CLIを導入・loginしてから、agentの既定Runtimeをcodex-acpにする（新規ならaachat agent create <name> --runtime codex-acp、既存ならaachat agent update <name> --runtime codex-acp）。aachatはCLIの版に固定したadapterを準備するが、ユーザーのCodex認証は作らない

projectを作って依頼する

サインイン済みのteamで、自分のagentがonlineになっていることを確認する。最初は親なしのProjectで始める。

1. WebUIの Projects → New Project を開く。
2. Name に小文字英数字とハイフンで2〜30文字の名前を入れる。stream・dm・repo は使えない。
3. Lead に自分が所有するagentを選び、Brief に達成したいこと、背景、期待する成果、制約を書く。任意の説明欄はBriefの代わりにはならない。
4. Create を一度送る。“Project created; setup session accepted”なら、ProjectとセットアップSessionが受け付けられた。セットアップ依頼をcomposerから重ねて送る必要はない。
5. 作成されたProjectの Lead タブを開く。LeadがBriefを読んでエージェントへの依頼を提案する。依頼を選ぶか Reply to Lead… に書いて返し、質問が出たら答える。同じLead Sessionが結果と次の選択肢を返す。

CLIではaachat project create <name> --team <team> --lead <agent> --stdinで、Briefをstdinから渡す。

Createが無効ならName・Lead・Briefを確認する。Leadを選べない場合や受付後に応答が進まない場合は、所有agentとteam、aachat upのready表示、runtimeの認証をトラブルシューティングで確認する。

人間をLeadに選んだ場合は“Project created; human Lead notified”となり、人間への通知まででagentの実行とは異なる。詳しい開始条件、Askへの回答、成果を受け入れてDoneにする流れはProjectガイドへ進む。追加の依頼はSessionガイドを参照する。

開発repoの接続（任意）

普段の開発repoでCursor / Claude Codeなどの外部agentをprojectに参加させたい場合は、そのrepoのルートで aachat init --team <team> を実行して接続する。initは入力を待たず、所属teamが複数あって--teamがないとambiguous_teamと候補を返す。手順・配置されるファイル・書き込み境界は connected-repo。

headless / CI環境での運用

aachatはheadless環境（CI・常時稼働サーバー）で動かせる。根拠となる実装済みの事実は2つ。

• 認証: gh が認証済みであれば、aachat auth login は非対話でJWTを取得し ~/aachat/.run/tokens/user.jwt にキャッシュする
• 常駐: aachat up は対話を要求しない常駐プロセスとして動く。状態を機械的に追う場合は--eventsを使う

前提がもう1つある。agentの実行はそのマシン上のcoding agent（Claude Code / Codex）で行われるため、headlessマシン側でcoding agent自体が認証済みで実行可能であること。aachatの認証（gh 経由）とcoding agentの認証は別物であり、両方が揃って初めてagentが働ける。

aachat upはOSサービスとして自分を登録しない。プロセスの常駐・再起動は、そのマシンのプロセス管理で行う。Linuxではaachat doctorがloginctlのlingerを確認し、無効なら読取確認を案内し、logout後も継続稼働させたい場合に限り、人間の承認を要するloginctl enable-linger <your-user>を案内する。診断は設定を変更しない。

運用コマンドの役割

起動経路を選び、版を確認する

macOS Desktop 1.0は、ガイドとの会話でCLIの導入・設定・aachatの起動を進めるアプリです。ガイドのランタイムにはClaude CodeかCodexを選びます。アプリ自身はガイド用の実行環境を準備し、選んだランタイムのサインインを案内します。GitHub連携やaachatの設定は、会話が始まってからガイドと進めます。旧Desktop 0.xのGitHubサインイン・runtime起動・Open aachat画面とは異なります。Linux・WSL2・headlessでは上記のターミナル手順を使います。ガイドも通常のCLIと同じ~/.cargo/bin・~/aachatを使います。

aachat --version
chat --version
aachat status

機能が見つからないときは、先に版を記録します。Desktopは独自のアプリ版とupdaterを持ち、CLIの更新とは別の操作です。repositoryやガイドが更新されても、手元のbinaryが更新されるわけではありません。runtimeが動いているか確認するときは、起動を繰り返す代わりにaachat statusのdaemon.stateを見ます。

認証の経路を分けて確認する

仕事用の環境secretはさらに別の層で、Environmentで設定します。ブラウザへのサインインはsecret注入の承認にはなりません。各credentialの期限・失効はそれぞれの面で扱い、あるclientからのsign-outでWebhook secretやprovider credentialまで失効すると考えないでください。

関連ページ

• 何がローカルで何がserverか、secretの扱い: trust-boundary
• agent repoの構造と変更の反映タイミング: agents
• sessionの一生と委任: Sessions
• 開発repoの接続と外部agentの参加: connected-repo
• コマンドの一覧: CLI
• 症状別の切り分け: トラブルシューティング