Agent Autoloopとは？
Claude Code、CodexなどのコマンドラインAgentは通常、ターミナルのそばで継続的に操作する必要があります。タスクを入力し、実行を待ち、質問に答えてから、続きを実行させます。ターミナルを閉じたり、一時的に席を離れたりすると、処理が中断することがよくあります。
Agent Autoloopは、コマンドラインAgent向けの軽量な自動化基盤です。タスクのスケジューリングをランタイム依存のないコアに組み込み、イベントソース、Agent、通知チャンネル、デリバリーパイプラインを交換可能なプラグインとして分離しています。ローカルのMacまたはLinuxコンピューターで動作し、クラウドサーバーの購入やパブリックポートの開放は必要ありません。
基本的な動作は次のとおりです。イベントが入るとルールに従ってAgentへ割り当てられます。Agentは1ラウンドの処理を終えると終了します。データ削除、サービス再起動、課金、外部へのメッセージ送信など、不確実な操作が必要な場合だけ、システムが通知カードで判断を求めます。回答すると、元のセッションを再開して残りのタスクを完了します。
主な機能
- ローカル実行：macOSまたはLinuxのコンピューター1台で導入でき、専用のクラウドバックエンドは不要です。
- Agentの接続が簡単：プロンプトを受け取り、最終回答を出力できるコマンドラインツールなら、汎用コマンドプラグインで接続できます。
- 一時停止中はAgentを消費しない：人の回答を待つ間、Agentプロセスは終了するため、Tokenを消費し続けません。待機状態はデータベースに保存されます。
- ルール駆動：
rules.jsonで、どのイベントをどのAgentに渡すか、どのディレクトリで実行するかを記述でき、連携用コードを書く必要がありません。 - 必要に応じた通知：デスクトップ通知、Feishu、DingTalk、企業微信、Slack、Discord Webhookテンプレートに対応しています。
- セッション再開：人が回答した後、元の会話を引き継いで処理を続けられるため、タスクを最初からやり直す必要がありません。
- 追跡可能：状態は追記専用ログから算出され、各タスクラウンドのトリガーと処理結果を確認できます。
- プラグイン方式：イベントソース、Agent、通知チャンネル、CI/CDデリバリーフローを拡張または交換できます。
インストール前の準備
開始前に、システムがmacOSまたはLinuxであり、次のツールがインストールされていることを確認してください。
- Node 24
- Git
- curl
- 少なくとも1つのインストール済みでログイン済みのコマンドラインAgent（Claude CodeやCodexなど）
インストールとローカルでの試行にGitHubアカウントは必要ありません。Agent Autoloopはローカルにあるコマンドラインツールを直接呼び出し、それらのアカウント認証情報を読み取ったり転送したりしません。
ステップ1：Agent Autoloopをインストールする
ターミナルで公式インストールスクリプトを実行します。
curl -fsSL https://raw.githubusercontent.com/KKKKhazix/agent-autoloop/main/install.sh | shインストールの詳細を先に確認したい場合は、プロジェクトのインストール手順を参照してください。READMEでは、この手順をローカルのAgentに渡してインストールを支援させることも推奨しています。
ステップ2：初回の対話試行を行う
インストール後、次を実行します。
agent-autoloop tryこのコマンドはローカルのAgentを使って、タスクの送信、Agentからの質問、終了して待機、あなたの判断の受信、セッションの再開とタスク完了までの流れを実演します。
試行中は、次のような結果が表示されます。
イベントを送信しました。Agentが作業を開始します……
Agentはこのラウンドを終了し、質問を1つしました。現在はプロセスもTokenも消費していません。
【判断待ち】#1 試行：色を1つ選択
これは試行なので、どちらを選んでも構いません。
1. 青
2. 緑対話型ターミナルでは、選択肢の番号を直接入力してEnterを押せます。非対話型ターミナルでは、1枚目のカードに明示的に回答し、2番目の選択肢を選びます。
agent-autoloop answer 1 2続いて全体の状態を確認します。
agent-autoloop status正常に進めば、Agentが元のセッションを再開し、選択結果を確認します。statusコマンドでは、当日および直近7日間の実行ラウンド数、Token、料金の集計も表示されます。
ステップ3：タスクが自動で動く仕組みを理解する
- イベントの受信：スケジュールタスク、GitHub Issue、業務システムのエラーが標準イベントに変換されます。
- ルールの照合：コアがローカルのルールに基づき、使用するAgentと実行する作業ディレクトリを決定します。
- 1ラウンドの実行：Agentがタスクを処理し、最後の返信で結果を説明してからプロセスを終了します。
- 必要に応じた確認依頼：人の判断が必要な操作がある場合、基盤が通知カードを送り、待機状態を保存します。
- 回答後の再開：選択を送信すると、システムが元の会話を復元してタスクを続行します。
人の関与が不要なタスクでは、Agentはそのまま終了することも、後で再確認するよう予約することもできます。また、同じ事柄について待機中に届いた新しいメッセージをまとめ、1回のタスク処理で対応します。
ステップ4：最初の自動化ルールを書く
日常的な設定は次の場所にあります。
~/.agent-autoloop/rules.json各ルールには少なくとも、いつトリガーするか、誰に渡すか、どのディレクトリで作業するかを記述します。toには、設定内のagentsに存在する名前を指定する必要があります。
例：毎朝9時に朝のレポートを生成する
{
"name": "朝のレポート",
"when": { "cron": "0 9 * * *" },
"to": "codex",
"cwd": "~/notes",
"prompt": "昨日のノートとコミットを整理し、今日の朝のレポートを書いてください。"
}このルールは毎日9時に、codexという名前のAgentへタスクを渡し、~/notesディレクトリでノートとGitコミットを整理させます。
例：新しく作成されたGitHub Issueを処理する
外部イベントルールも構造は似ていますが、先にsourcesへ対応するイベントソースを登録する必要があります。次のルールはGitHubのissues.openedイベントを監視します。
{
"name": "issueを処理",
"when": {
"source": "github",
"types": ["issues.opened"]
},
"to": "codex",
"cwd": "~/code/app",
"skill": "handle-issue",
"parallel": 3
}skillはタスク処理に必要なSkillを指定し、parallelは並列数を3に設定します。イベントソースの登録方法は、プロジェクトの設定マニュアルに従ってください。
ルールを保存すると、数秒以内に自動的に反映されます。すぐに次のコマンドを実行して確認することをおすすめします。
agent-autoloop check新しいルールにエラーがある場合、システムは古いルールを使って処理を続け、カードで具体的な問題を通知します。誤った設定によって既存の自動化が直接中断されることはありません。
ステップ5：Agentに人の判断を求めさせる
Agent AutoloopがAgentに求める主な約束は、最後の返信で結果を説明することです。タスクが完了している場合は通常どおり結論を出力します。人の選択が必要な場合は、返信の末尾にagent-autoloopの応答コードブロックを追加します。
注文の確認が完了し、在庫も十分です。
```agent-autoloop
{
"ask": [{
"title": "どのように発送しますか？",
"text": "どちらの方法でも本日発送できます。",
"options": ["宅配便", "自 pickup"],
"key": "shipping"
}]
}
```ここでのaskは、2つの選択肢を含む判断カードを生成します。質問のほか、応答では次のアクションにも対応しています。
notice：通知を送信します。resolve：解決済みのカードを閉じます。later：将来の特定時刻に再確認するよう予約します。events：新しいイベントをトリガーします。
Agentが出力したJSONに誤りがある場合、基盤は元のセッションで最後の応答部分を書き直すよう求めるだけで、完了済みの業務操作を再実行しません。書き直しにも失敗した場合、システムは元の結論を保持し、応答が反映されなかったことを通知します。
既存のシナリオテンプレートを使う
プロジェクトには、ルール、タスクSkill、導入手順を含む複数のテンプレートが用意されており、実際の設定の出発点として利用できます。
- 毎日の朝のレポート：ローカルのノートとGitコミットを整理し、日付名のファイルに書き込みます。
- GitHub Issueのフォローアップ：新しいIssueを定期的に確認し、ローカルでコードを修正して確認を依頼します。デフォルトではコミット、プッシュ、Issueへの返信を行いません。
- 本番アラートの調査：エラーを受け取り、コードと照合して原因を分析します。再起動操作が必要な場合は、先に承認を求めます。
- ユーザーフィードバックの処理：フィードバックの状態を確認し、問題を修正し、納品を確認して返信を準備します。判断が必要な場合はFeishuで質問します。
- Webサイトの巡回チェック：状態と重要な内容を定期的に確認し、異常が続く場合の重複通知を避け、復旧後に元のカードを更新します。
- Feishu週報と業務サマリー：権限に応じて報告書と指定された表を読み取り、完全なサマリーをローカルに保存し、Feishuには短い内容だけを送信します。
- PRの自動デリバリー：コードレビューから開始し、CI、PRのマージ、デプロイを待ち、最後に本番バージョンを確認します。
テンプレートを有効にするには、タスクSkillを使用するAgentのskillsディレクトリに配置し、サンプルルールを~/.agent-autoloop/rules.jsonに統合して、パスとコンピューター名を置き換えた後、agent-autoloop checkを実行します。
READMEでは特に、フィードバック処理、Webサイト巡回、Feishuサマリーのサンプルデータは架空のものであり、関連スクリプトと応答はローカルHTTPおよび模擬Feishu CLIでのみ検証済みで、実際のアカウントによる完全な業務テストはまだ行われていないと説明しています。
さまざまなAgentと通知チャンネルを接続する
組み込みAgentプラグイン
プロジェクトにはClaude Code、Codex、ACP、汎用コマンドのプラグインが組み込まれています。Claude Code、Codex、公式Codex ACPアダプターについては、複数回の質疑応答とプロセスをまたぐセッション再開のテストが完了しています。
汎用コマンドで他のAgentを接続する
その他のコマンドラインAgentでは、use: "command"を設定し、コマンド配列を指定できます。プレースホルダー{prompt}は独立した引数として渡され、Shellコードとして実行されることはありません。
READMEには、各ツールの公式ドキュメントに基づき、DeepSeek Harness、pi、OpenClaw、Hermes、Cursor、WorkBuddy／CodeBuddyなどのコマンド例が掲載されています。ただし、これらのコマンドは個別に実地テストされていないことも明記されています。そのため、本番利用前に隔離したディレクトリで引数、出力形式、セッション動作を検証してください。
サードパーティ製プラグインをインストールする
サードパーティ製プラグインはGitアドレスからインストールできます。
agent-autoloop add <Gitアドレス>自分でプラグインを開発する場合は、プロジェクトが提供する最小構成のAgent、チャンネル、イベントプラグインのテンプレートから始め、プラグイン開発手順を参照してください。
通知チャンネルを選択する
デスクトップ通知はデフォルトで有効です。Feishu では送信、ボタンコールバック、カード更新を実機で検証済みです。DingTalk、企業微信、Slack、Discord は Webhook テンプレートを使用しており、現在はローカルのモックサービス上でのみ検証されています。
これらのテキストチャネルでは、回答リンクを通じて判断結果を送信するため、hub.publicUrl にはスマートフォンやパソコンからアクセスできるアドレスを設定する必要があります。パブリックアクセスが必要かどうかは、選択したチャネルとネットワーク環境によって決まり、基本的なローカル実行そのものによって決まるわけではありません。
高度なテクニックと信頼性設計
タスクの特定ラウンドが実行された理由を確認する
why コマンドを使うと、指定したラウンドのトリガーイベント、ルールのバージョン、担当者、最終結果を確認できます。
agent-autoloop why 1誤ったルール、重複イベント、意図しないタスク割り当ての調査に特に役立ちます。
4つのコアメカニズムを理解する
- 一時停止時はゼロ消費：人間の回答を待つ間は Agent プロセスが終了し、状態はデータベースに保持されます。回答後、元のセッションを再開します。
- イベントソーシング：すべての状態は追記専用ログから計算され、ログとインデックスは同一トランザクションでディスクに書き込まれます。形式が変更されても、ログから状態を再構築できます。
- 命令とデータの分離：Issue のタイトルや本文などの外部コンテンツは資料として保存され、プロンプトに直接連結されません。Agent、作業ディレクトリ、権限はローカルルールだけで決まります。イベント内の
cwd、agent、accessフィールドは拒否されます。 - ホップ数によるサーキットブレーカー：Agent が新しいイベントをトリガーすると階層が加算され、人間への質問や定期的な再確認ではリセットされません。8階層を超えると記録のみ行い、タスクの割り当ては継続せず、ユーザーにカードを送信します。
シミュレーションと性能テストの実行
プログラムのディレクトリに移動します。
cd ~/.agent-autoloop/app続いて、README に記載された検証コマンドを実行できます。
node sim/random.ts 24301 200000
node sim/crash.ts 1000 12648430
npm run benchmark1つ目のコマンドはネットワーク切断、パケットロス、クラッシュ、重複送信をシミュレートします。2つ目のコマンドはプロセスを繰り返し強制終了し、確認済みの記録が失われないかを検証します。3つ目のコマンドは性能ベンチマークを実行します。README の合格基準は Apple M5 Pro、24 GB メモリ、Node 24.21.0 を前提としているため、他のマシンではハードウェアの違いにより基準未達と表示される場合があります。
履歴ログが増えると状態の集計に時間がかかり、ログとインデックスも継続的にディスク容量を消費します。データ形式の変更後、初回起動時に全量再構築が必要になる場合があるため、長期運用ではディスク容量と起動時間に注意してください。
デリバリーパイプラインの利用範囲
Agent Autoloop は delivery プラグインを提供します。GitHub PR に deliver ラベルを付けると、「コードをレビューする、CI を待つ、PR をマージする、デプロイを待つ、本番環境のバージョンを照合する」という順序で継続的にフォローできます。
レビューとデリバリーの設定は main ブランチからのみ読み込まれ、タスクを受け付けるコンピューター上で PR 内のコードをチェックアウトしたり実行したりすることはありません。キュー、同時実行、リトライには同じコアメカニズムが使われます。本番で有効にする前に、リポジトリの権限とリリースフローを踏まえてセキュリティ境界の説明を確認してください。
利用量とコンプライアンスに関する提案
モデル呼び出しの費用は自身のアカウントに計上され、利用枠と利用範囲は各モデルベンダーの利用規約に従います。README では、高頻度の自動化シナリオには通常 API Key が適しており、個人向けサブスクリプションの利用枠は主に日常的な手動操作を対象としていると説明されています。このツールを使って外部向けサービスを提供する場合は、API Key を使用し、利用規約とコンプライアンス要件を自分で確認してください。
Agent Autoloop は独立したオープンソースプロジェクトであり、Anthropic、OpenAI などのモデルベンダーとは所属関係も推薦関係もありません。
まとめ
Agent Autoloop の重点は、Agent を常時オンラインにすることではなく、タスクを確実に一時停止し、待機させ、再開できるようにすることです。まず agent-autoloop try で対話の一連の流れを検証し、毎日の朝刊や GitHub Issue テンプレートからルールの作成を始められます。ローカルのフローが安定したことを確認してから、Feishu、Webhook、外部イベント、PR デリバリーパイプラインを段階的に接続してください。
さらに設定する際は、ルールとデリバリー設定マニュアル、完全な通信プロトコル、プラグイン開発ドキュメントを参照してください。