clikae Docs
ガイド

clikae で agy（Antigravity）をヘッドレスで動かす

Markdown を表示 View this page as plain textChatGPT で開く Ask ChatGPT about this pageClaude で開く Ask Claude about this page

特定の一つの仕事に絞ったレシピです。メインの Claude/codex クォータを投入する代わりに、 Antigravity（agy）の Pro アカウントへ作業を振り向ける こと。agy は本物の有料エンジン です — 使いましょう。ただし claude -p / codex exec とは挙動が違い、無駄になる agy クォータの大半は、間違った動かし方から生まれます。このページは、毎セッション学び直して （そして使い潰して）しまわないための、決定版の手順書です。

要点 — agy は グローバル、単一アカウント、burn 不可 です。これは「使えない」という 意味では ありません。意味するのは、burn が claude/codex でやるようにタンクをまたいで 自動で再ルーティングできない、ということです。clikae agy <tank> -- -p で アクティブな アカウント上でヘッドレスに動かし、バッチの合間に対話的にアカウントを切り替えます。

押さえるべき一つの事実

agy の Google ログインは、シェルごとの環境変数ではなく グローバルな Keychain エントリ 1 つ です。したがって、

  • clikae env agy は存在せず、シェルごとのルーティングもありません — clikae env agy はわざと失敗し、あなたをここへ案内します。
  • clikae agy <tank> は ~/.gemini（とそのログイン）を マシン全体で 入れ替えます — agy アカウントは一度に すべての ターミナルで 1 つだけアクティブになります。並列ではなく 排他です。
  • clikae burn は予備タンクの巡回に agy を組み込めません（同じマシン上では再ルーティング する 先 がありません）。agy のリレーは 手動で、逐次 です。バッチを走らせ、タンクを 切り替え、次を走らせる。同一アカウントの agy↔gemini がなぜ偽のリレーになるか（同じ クォータのバケツ）は、agy-gemini-shared-quota のメモを参照してください。

決定版のヘッドレス呼び出し

# agy をタンクに切り替え（マシン全体）、そのアカウント上でヘッドレスに走らせる。
# プロンプトは FILE 経由で渡す — 段落をシェルでクォートした -p '…' に詰め込まないこと。
clikae agy <tank> -- \
  --print-timeout 900s \
  --add-dir /abs/path/to/repo  `# タスクが cwd 外のファイルを読み書きする場合のみ` \
  -p "$(cat /tmp/agy_prompt.txt)"

これだけです。以下のルールが、本物の成果が返るか、空振りが返るかの分かれ目になります。

agy を空振りさせないためのルール（苦労して得た教訓）

  1. ヘッドレスの agy は -p（print モード）であって、-i ではない。 agy -i は本物の TTY を必要とし（bubbletea の TUI です）、ヘッドレスでは could not open TTY で死にます。 エージェント主導やバックグラウンドの呼び出しは、すべて -p を使います。

  2. プロンプトはネストしたクォートではなく、ファイル経由で渡すこと。 -p "$(cat /tmp/foo.txt)"。ネストした sh -c '… -p "…"' のクォートはプロンプトを 黙って食い、agy は的外れな答えを返します。一層で、ファイルから。

  3. 大きな出力を stdout から集めない — agy にファイルを書かせること。 agy -p の stdout での返却は、大きい／構造化された出力では信頼できません。プロセスは 0% CPU で 生きたまま、すべてをバッファに溜めて何も出さない ことがあります。大きいものは、 agy に 結果をファイルへ自分で書かせ（エージェント的に）、そのファイルを読んでください。 置き場所: ~/.gemini/antigravity-cli/brain/<session-id>/*.md — -p の stdout は、 多くの場合そこへの 1 行ポインタにすぎません。

  4. 死んだタスク、固い境界、長いタイムアウトを与えること。 agy の対話時の強み — 自由な探索 — は、ヘッドレスでは負債になります。あてどなくさまよい（たとえば git diff を 調べに行く）、何も書かないままタイムアウトを使い切ります。プロンプトで明示的に柵を 立て（「git を見るな、調査するな、X だけをやって Y を書け」）、--print-timeout 900s を 与えてください（既定の約 5 分は、本物の仕事には短すぎます）。

  5. macOS に timeout はない。 --print-timeout はいつもきれいに kill するとは 限りません。無人ジョブでは、外側に固いキル（たとえば Python の subprocess.run(..., timeout=N)）を保険として巻いてください。

  6. タンクを切り替える前に pkill -9 -f "agy -p"。 clikae agy <tank> は、agy プロセスが生きている間は切り替えを拒みます（その下で ~/.gemini を入れ替えると セッションが壊れます）。古い／ハングした print ジョブを先に kill してください。

  7. cwd 外のファイルを読むには --add-dir <abs path> が必要（事前認可）です。 あるいは純粋なテキストを stdin で流せば（cat file | agy -p "…"）、ツール／権限の ゲートに当たりません。認可されていないパスを読もうとする素の agy -p は、答える TTY の ない権限プロンプトを待って 永遠にハングします。

  8. --dangerously-skip-permissions は 人間 用であって、エージェント用ではない。 clikae が 別の AI（たとえば Claude Code）に 動かされている とき、その AI の安全 分類器は、Bash(agy:*) の許可ルールがあっても、--dangerously-skip-permissions を 伴う agy 呼び出しをブロックします。素の agy -p（skip フラグなし）なら通ります。 どうしても skip-permissions が要るタスクなら、その行は人間が走らせます（たとえば ! 接頭辞で）。エージェントに自己認可を期待しないでください。

  9. バッチごとにタンクを回し、週上限を分散させること。 グローバルアカウントが 1 つ＝ 逐次実行。タンクを交互に使えば（clikae agy 8 / clikae agy c / …）、使用量を複数の アカウントに分散できます。正味のスループットはラウンドロビンであって、並列ではありません。

agy が本当に得意なヘッドレス作業

  • 一発のテキスト生成 — 翻訳、トランスクリエーション、要約、コピー。検証済み: スコープの 明確なテキストタスクなら、単発の出力を確実に生み出します。（zh-TW を台湾の語感で レビューさせるときは、大陸→台湾の用語ルーブリックを添えてください — agy は中身が Gemini なので、放っておくとブレます。ネイティブの耳ではなく、明示的なルーブリックを 与えられた採点者として扱ってください。）
  • ライブ Web の QA — agy には read_url_content ツールがあり、本当にブラウズします （URL を取得し、リンクをたどり、HTML を読みます）。バイヤージャーニー／i18n／仕上げの 一掃に向いており、観点ごとに 1 つのレポートファイルを出します。一度スモークテストして （ページの本物の <h1> を返させて）、当て推量でないことを確かめてください。素の 生存確認なら curl のほうが確実です — 「サイトは生きてる？」に agy のクォータを 使わないでください。
  • メイン予算からオフロードした大きなファイル書き込みジョブ — まるごと一つの翻訳辞書を、 ファイルに書き（ルール 3）、agy のバケツで、あなたの Claude 予算には触れずに。これが コストを意識したルーティングの見返りです。
  • clikae conduct での安価な幅出しレッグ — conduct --leg agy/<tank> は、読み取り 専用の監査／分析プロンプトを claude/codex のレッグと並べて agy にも振り、各レッグの 出力をあなたに渡して判断させます。agy は安価で速いので、best-of-N に追加の視点として 好適です。注意: agy レッグは 現在アクティブな agy タンク上でのみ走ります（別の タンクを指定したレッグは、実行されずに報告されます — clikae は agy を並列に切り替え られません）。その切れ状態は stdout ではなく cli.log から読みます。

⚠️ agy のレビュー提案は仕分けが必要です。 すでに決まっている製品上の判断に反することを、 自信たっぷりに勧めてきます。agy のレビューの修正を自動適用しては絶対にいけません — オーケストレーターか人間がふるいにかけます。

❓ 未検証（慎重に扱うこと）: ある観察は、agy -p が claude -p / codex exec のような 完全に自律的な複数ステップの ファイル編集 ループを走らせない可能性を示唆しています — 単発で答えるか、非同期のビルドに委ねて返ってくるかもしれません。単発のテキスト出力は 確認済みですが、エージェント的な「編集して検証する」ループは未確認です。agy を burn スタイルのコード編集ワーカーとして使うつもりなら、まず制御されたタスクで検証してください。 最新の地に足のついた事実は agy-gemini-shared-quota を参照してください。

あわせてどうぞ

  • docs/orchestration.md — ヘッドレス振り分けの一般的な手引き（burn/conduct/legs）。
  • docs/dogfood-agy-headless.md — このレシピの元になった、生のドッグフーディング日誌。
  • clikae agy --help — agy タンクの切り替え／管理のコマンドインターフェース。