AGI CockpitDocs
ドキュメント

Hooks

タスクの完了、Ask、ホットキーなどをきっかけに処理を実行するHooksの使い方と、設定・実行履歴の確認方法を説明します。

対象
DesktopCLI
WindowsmacOSLinux

最終検証 2026-09-09 · v4.74.0

Markdown

Hooksは、タスクの完了やAskの作成など、Cockpitで起きたイベントをきっかけに、登録した処理を自動実行する機能です。「この出来事が起きたら、この処理をする」というルールをHookとして保存できます。ホットキーをきっかけにすることもできます。

Autorunとの使い分け

やりたいこと 使う機能 例
時刻や間隔に合わせて仕事を始める Autorun 毎朝9時にレポートを作成する
出来事に反応して処理を実行する Hooks タスクが完了したら結果をまとめるスクリプトを動かす
複数タスクを依存関係に沿って進める Fleet 調査が終わったら執筆とレビューへ進む

組み合わせることもできます。たとえば、Autorunで始めたタスクの完了にHooksで反応したり、Fleet全体の終了をきっかけに後処理を実行したりできます。

きっかけを選ぶ

きっかけ 主なイベント 活用例
タスクの状態が変わる task.completed、task.waiting、task.error 完了後の処理や、確認待ち・エラーの通知を実行する
Askが作成・回答される ask.created、ask.resolved 外部サービスへ判断依頼や回答結果を連携する
Autorunが実行される autorun.triggered スケジュールの実行を記録する
Fleetが開始・終了する fleet.run.started、fleet.run.completed 一連の作業の終了後に後処理を実行する
アプリが起動・終了する app.ready、app.quit 起動時の準備処理を実行する
ショートカットキーを押す hotkey よく使う処理をキー操作で呼び出す

task.completedはタスクが完了状態へ変わったときに発生します。同じ状態が再保存されても発生しません。fleet.run.completedは成功だけでなく失敗・キャンセルでも発生するため、成功時だけ実行する場合は状態のフィルターを付けます。

エージェントに設定を依頼する

Cockpitのタスクから、きっかけ、対象、実行したい処理を伝えて設定を依頼できます。

このプロジェクトのタスクが完了したら、指定した集計スクリプトを実行するHookを作って。子タスクは対象外にして、まず無効な状態で登録し、テスト結果を確認してから有効にして。

外部サービスとの連携には、そのサービスへ接続するスクリプトや認証設定が必要です。Hooksに登録するのは実際に実行するコマンドやスクリプトです。

CLIで登録して試す

追加・変更・テストはcockpit hooksで行います。ここでは、タスク完了時にCockpitへメッセージを表示するHookを作ります。例はmacOSやLinuxのシェル向けです。

cockpit hooks add --event task.completed \
  --name completion-message \
  --disabled \
  --run 'cockpit display --text "${COCKPIT_TASK_NAME} completed"'

返されたhook.idを以下の<hookId>に置き換えます。<taskId>にはcockpit task listで確認したタスクIDを指定します。

cockpit hooks test <hookId> --task <taskId>
cockpit hooks enable <hookId>

まずテスト結果のexitCodeが0で、表示内容が意図どおりであることを確認してから有効にします。testは無効なHookでもアクションを実行します。イベントやフィルターの一致は検証せず、通常の実行履歴にも残さないため、有効化後は実際のイベントと履歴も確認します。

対象と処理を絞り込む

プロジェクトやタスク名、エージェントなどで対象を絞れます。次の例は指定ディレクトリ配下のタスク完了に反応し、子タスクを除外します。パスは自分の環境に置き換えてください。

cockpit hooks add --event task.completed \
  --name project-summary \
  --directory /path/to/project \
  --no-child \
  --run-file /path/to/project/scripts/summarize.sh \
  --disabled

短いコマンドには--run、管理するスクリプトには--run-fileを使います。複数のフィルターを指定すると、すべてに一致するイベントが対象になります。スクリプトはイベント情報を標準入力のJSONやCOCKPIT_TASK_IDなどの環境変数から受け取れます。

設定画面と実行履歴

  1. 画面左下のアプリメニューから「設定」→「Hooks」を開きます。
  2. 登録したHookを確認し、必要に応じて有効・無効を切り替えます。
  3. 実行履歴を開き、実行日時、イベント、終了コード、標準出力・標準エラーを確認します。
  4. 不要になったHookは削除できます。削除しても既存の実行履歴は残ります。

CLIからも状態と履歴を確認できます。

cockpit hooks list
cockpit hooks runs --hook <hookId> --limit 20
cockpit hooks disable <hookId>

実行されない場合は、Hookが有効か、イベントとフィルターが対象に一致しているかを確認します。ホットキーではcockpit hooks get <hookId>のregisteredも確認してください。falseならショートカットは登録されていません。処理が失敗する場合は終了コードと標準エラーを確認します。実行時間の上限は既定で60秒で、--timeoutで変更できます。

実行時の注意点

登録した処理は利用者のローカル権限で実行されます。エージェントの承認モードとは別に動くため、内容を確認したコマンドやスクリプトを登録してください。HooksのCLIはローカル専用で、--hostには対応していません。

app.quitで待機できる時間は最大5秒です。終了時に必ず完了させたい長い処理には使わないでください。イベントの連鎖による繰り返し実行には上限があるため、Hookが別のタスクを起動する場合は対象を絞ることも必要です。

関連ページ