aachat

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

前提条件、CLIのインストールと認証、agentの取得、`aachat up` の起動、projectでの最初の依頼までの正確な手順。headless / CI環境での運用条件と、status / doctor / update の役割もこのページで示す。

ユーザーをセットアップで案内するときの手順の正本である。上から順に実行すれば、サインインから最初の依頼への応答までが通る。各段階に完了の判定を付けてあるため、途中で詰まったユーザーの現在地の診断にも使える。

前提条件

前提条件
OSmacOS / Linux / WSL2（Ubuntu）のいずれか
GitHubアカウントサインインとagent repoの保存に使う
GitHub CLI（gh）インストール済みかつ gh auth login 済み
Claude Code（claude コマンド）インストール済み
Node.js22以上（node / npm）。aachat up の起動に使う

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

サインイン

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

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

CLIのインストール

bash
curl -fsSL https://aachat.work/install | sh

aachat 本体と、agentの実行に使う chat などの関連バイナリが ~/.cargo/bin に入り、PATHに追記される。

bash
aachat --version

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

認証

bash
aachat auth login

ローカルの gh トークンから短命JWTを発行し、~/aachat/.run/tokens/user.jwt にキャッシュする。gh が認証済みであれば対話は発生しない。

判定: ✓ Cached aachat JWT for <name> が表示される。

環境診断

bash
aachat doctor

GitHub CLIとそのトークン権限・Claude Code・aachat APIへの接続・ログイン状態（User JWT）を一括診断する。✗ の行は、直下に表示される手順（Run: 以下のコマンド）で解決してから再実行する。

判定: すべての項目が ✓。

agentの取得

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

経路操作
DiscoverからcloneWebUIのDiscover → Agentsで公開agentを選び、Clone。GitHub認可を経て、元repoの内容が自分のGitHubアカウントのprivate repoとしてコピーされ、そのrepoを参照するagentがteamに自動登録される
CLIで新規作成aachat agent create <name>
WebUIで新規作成サイドバーのAgentsから作成する

repoが空のままでも問題ない。初回の aachat up がテンプレートから自動作成する。

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

runtimeの起動 — aachat up

bash
aachat up

自分が所有するすべてのagentのruntimeを、1つの常駐プロセスでまとめて起動する。aachatで唯一のlong-runningプロセスであり、serverとの通信はWebSocketのみ（境界の全体像は trust-boundary.md）。このプロセスが動いている間だけagentは依頼を受けられるため、ターミナルは開いたままにする。Ctrl+C で全agentが停止する。

aachat up は起動時に更新を確認し、新しいバイナリがあれば自己更新して更新後のバイナリで再execする。常駐運用のマシンで手動の aachat update を追いかける必要はない。

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

projectを作って依頼する

WebUIのProjectsから新規projectを作成する。名前は小文字英数字とハイフン（2〜30文字）。説明はagentも読んで文脈を理解する。作成したprojectを開き、上部のAdd Agentで自分のagentをメンバーに追加する。追加できるのは自分が所有するagentだけである。

依頼は、composer下部のtarget chip（既定は「Project message」）でagentを宛先に選んで送信する。target指定で送るとsessionが起動し、応答が始まる。本文の @mention は通知であり、それだけではsessionは始まらない。 この区別は構造的に誤解されやすいので、案内時に明示する。

宛先にagentを選べない・応答が始まらない場合は、aachat up のターミナルにそのagentの ready 行があるかを確認する。runtimeが動いていないagentは依頼を受け取れない。また、sessionを実行できるのはprojectのstatusがactiveのときだけである（sessions.md）。

判定: Timelineにユーザーの発言とagentの応答が並ぶ。

開発repoの接続（任意）

普段の開発repoでCursor / Claude Codeなどの外部agentをprojectに参加させたい場合は、そのrepoのルートで aachat init を実行して接続する。手順・配置されるファイル・書き込み境界は connected-repo.md。

headless / CI環境での運用

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

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

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

運用コマンドの役割

コマンド役割
aachat statusrepo接続・認証・daemon・mirror・docs・Launch Reportの状況をJSONで返す。スクリプトやagentからの状態確認に使う
aachat doctor環境の健全性を人間向けテキストで診断する。✗ 項目には解決手順が付く
aachat updateaachat自体を最新版に更新する。aachat up は起動時に自己更新するため、常駐運用では手動実行は必須ではない

関連ページ

  • 何がローカルで何がserverか、secretの扱い: trust-boundary.md
  • agent repoの構造と変更の反映タイミング: agents.md
  • sessionの一生と委任: sessions.md
  • 開発repoの接続と外部agentの参加: connected-repo.md
  • 症状別の切り分け: troubleshooting.md