Claude Code のループ機能を管理する Spool: 機能、構成と使用方法

Spool を使用すると、永続的な Claude コードループを作成し、管理し、対話することが容易になります。作業を任せて調整し、チャットを通じて常に関与し続けることができます。

🌟 主な特徴：Spool が容易にする作業

• 作業の継続
  • 特定の場所で永続的なループを作成・管理できます。
  • スケジュールされた起動時刻と再開可能なセッションを設定することで、作業の中断を防ぎます。
• 参加の維持
  • ループのターミナルセッションにいる必要はありません。
  • Web コントロールルーム、Telegram、Slackからループと会話できます。
• 調整の簡素化
  • ループが「艦隊チャネル」を介して直接通信できるようにします。
  • 各質問や結果、手渡しのすべてを手作業で中継する必要がなくなります。
  • これにより、より多くの時間を「何をやるべきか」の決定と、「生み出した成果物のレビュー」に費やすことができます。

注: Spool は v1.0 前のバージョンであり、Claude コードのループとそのオペレーターによって公開開発されています。イシューおよびプルリクエストで実行されている 4 つのループも Spool を使用しています。コミットはモデルが共著者として記述し、CI でゲートされた後、オペレーターがマージします。

🚀 クイックスタート

環境要件:

• OS: Linux、macOS、または WSL2（Windows）。
• Docker: 実行中である必要があります。
• 言語・ツール: git、Go 1.25+、Node.js 20.19+ または 22.12+。
• Claude Code: インストール済み（トークン取得用）。

1. Spool の取得と構築

git clone https://github.com/enes-alatas/spool && cd spool
make build image

• コマンドは

  bin/spool

  （内部制御ルームを含む）と、ループが動作する 2 つの Docker イメージを構築します。

2. 起動とログイン

./bin/spool

• 初回起動: ユーザー「admin」用のワンタイムパスワードが表示されます。
  • ブラウザで

    http://127.0.0.1:8080

    を開き、パスワードで admin としてログイン。
  • 独自のユーザー名を設定してください。
• パスワードを再発行: コマンドを使用します。

  ./bin/spool user reset admin
  

3. 制御ルームでのセットアップ

起動すると以下の 3 つのカードが表示されます。順に操作してください。

ハarness（統合）

• claude setup-token

  を実行し、表示されたトークンをコピーします。
• カード上の「Add token」を選択し、コピーしたトークンを貼り付けます。
  • これでループはあなたの Claude プランを通じて動作します。

Loops（ループ）

• 「New loop」を選択し、名前とミッションを入力します。
• 初回の起動でワークステーションが構築されます（初回は 1〜2 分かかります）。
  • 最初のターン終了までこのカードは完了状態になりません。

Chat Surface（対話インターフェース）

ボットを追加する順序です。

1. **「Attach a bot」**を選択し、以下から選択します。
   • Telegram:
     • Telegram で

       @BotFather /newbot

       を実行。
     • 生成されたトークンを貼り付けます。
   • Slack:
     • ダイアログに従って「Create app from manifest」を実行。
     • アプリの 2 つのトークンを貼り付けます（詳細は

       docs/SLACK.md

       ）。
2. 「Get a link code」を選択し、そのコードをボットに直接メッセージ送信します。
3. ボットから質問があれば **「YES」**と返信し、アカウントをリンクしてオーナーになります。
4. 最後に一度でもボットにメッセージを送れば、ループが返信するとカードが完了状態になります。

チャットアプリがない場合: 制御ルーム内のループページから直接会話することも可能です。Harness と Loops のカードが完了したら、「Skip for now」を選択し、後からボットを連携させることができます。

その他の実行方法

• リリース版からの実行（v0.5.1 以降）: ビルド済みバイナリとイメージが同梱されているため、Go や Node.js は不要です（

  OPERATIONS.md

  を参照）。
• サーバー上のサービスとして実行（TLS とバックアップ付き）:

  OPERATIONS.md

  を参照してください。
• Docker 不使用:

  ./bin/spool --runtime bare

  コマンドを使用すると、独自アカウントで「bare」モードとなり、ループを個々のプロセスとして実行します（コンテナ化されない）。

⚙️ 動作原理

• 下流の Plain Claude CLI
  • ループは

    claude

    のサブプロセスであり、stdin/stdout を介して stream-json で通信します。
  • 通常の Claude コードのログイン、プラン制限、セッション制限が適用されます。API キーや SDK は不要です。
• 直接協調
  • ループは明示的にアドレスされたメッセージを艦隊チャネルまたはプライベート会話に送信します。
  • Telegram や Web、他ループからの

    @mention

    に反応して Spool がメッセージを配信します。
  • 最終ターンの返信はタイムラインのステータスノートとして保持され、ループ間の連鎖は「storm-guarded（暴風雨ガード付き）」です。
• 起動・休止とペース調整
  • アイドル中のループにはコストがかかりません。プロセスは終了し、必要な文脈を保ったまま後で再開します。
  • デフォルトでは 30 分間隔（tick） で起動しますが、メッセージ届くと即時起動します。

  • [next-wake: 45m]

    トレーラーで次の起動時間を指定できます（設定範囲内）。
  • 休止中のループはメールをキューイングします。
• 制御ルーム
  • デフォルト

    http://localhost:8080

    の Web UI ハブです。
  • トークンのストリーミングに従って各ループの対話をリアルタイム表示し、スケジュールやターン・日のコストを表示します。
  • ループを停止、起動、終了させることができます。
• プランガードレール
  • Fleet ページで、プランの 5 時間と 7 日ウィンドウの使用量をループからのストリーミングデータから読み取り表示し、各ループの日々の消費シェアを示します。
  • 上限（デフォルト 90%）を超えると、すべてのループがそのウィンドウのリセットまで休止し、メッセージは待機されますが失われません。
  • 「Resume now」で早期再開が可能です。
  • 閾値の変更や無効化は

    Settings → Plan guardrails

    で設定できます。

🔒 セキュリティ概要

• デフォルトでコンテナ化
  • 各ループは独立したコンテナ内で実行され、エグレス（外部接続）がリストされたホワイトリストのみ許可されています。
  • ハブポート以外のマシンのルートはありません。このハブポートではループの MCP エンドポイントのみ提供されます。
• コンテナ化なしはユーザー側で要求時
  • Docker がない場合、Spool は起動を拒否します（

    --runtime bare

    の場合はホスト上で実行されます）。
• ログインが必要
  • 制御ルームではユーザー名とパスワードが必要です。スクリプトではオペレータートークン (

    spool token

    ) を使用します。
• 機密情報の密封
  • ボットトークン、接続シークレット、setup-token はデータディレクトリの

    hub.key

    で密封されています。

    spool.db

    と別にバックアップしてください。

詳細：

docs/CONTAINMENT.md

（コンテナ化の全貌）および

SECURITY.md

（脆弱性報告）。

💬 チャット表面とアクセス制御

チャット表面（対話インターフェース）

• ループは当初、制御ルームでのみ起動します。
• Telegram または Slack からアクセスするには、クイックスタートのステップ 5 でボットを追加する必要があります。

ループにアクセスできる人

Spool は送信元ホワイトリストを維持しており、登録された人だけがあなたのループに到達できます。

• ホワイトリスト外のメッセージ: ボットへの送信は無視され、グループバインドもできません。

  /spool_status

  には答えません。
• アカウントのリンク: ステップ 5 で自分のアカウントをリンクします。
• 他の人を許可する手順:

  1. spool user add

     コマンドを使用するか、「Settings → Users and access」から追加します。
  2. 「Settings → Link Telegram/Slack」で彼ら自身のリンクを行います。
  3. 「Settings → Users and access」では各ユーザーのリンク一覧を表示でき、すべてのボット上でユーザーをブロックすることも可能です（古いペアリングコードによる承認を含む）。

ブロックされた送信元は一切返信されません。Slack アプリはインストールしたワークスペースに限定され、ホワイトリストもそこで適用されます。ループ間通信は内部処理であり影響を受けません。

🛠️ フラグ（コマンドラインオプション）

すべてのフラグは

spool --help

--listen

--data-dir

--runtime

--trusted-host

--mcp-listen

🧪 開発とテスト

ビルドコマンド：

make server         # Go バイナリのみ
make dev            # バックエンド実行 (:8080)
make ui-dev         # Vite 開発サーバー (/api プロキシ付き)
make image          # ローカルに Docker イメージをビルド

テスト階層 (docs/QUALITY.md を参照):

• Tier 1 (Unit Test): ユニットテスト＋アーキテクチャテスト。
• Tier 2 (Integration Test): 実際のバイナリと fakeclaude（プロトコルフェイク）でのテスト（約 10 分）。
  • Docker デーモンなしで約 7 分。
  • テスト対象：m1 (機能確認)、m2 (ティックスケジューリング)、m4 (メンションリレー＋暴風雨ガード)、m5 (Telegram)、m6 (ワークツリー分離) など。
• Tier 3 (End-to-End Test): 実際の Claude セッション（プラントークンを消費）。

  scripts/e2e/

  でローカル実行。

CI でゲートするのはユニットテストと fakeclaude を基にした統合テストです。e2e シートは各マイルストーンごとにローカルで実行されます。

📚 プロジェクトドキュメント

ハブの実行に関するドキュメント:

• docs/OPERATIONS.md

  : サーバーへのインストール、バックアップ、リストア、アップグレード。

• docs/CONTAINMENT.md

  : ループをコンテナ化する内容及びハブ自身のシークレット。

• docs/TELEGRAM.md

  ,

  docs/SLACK.md

  : チャット表面の詳細。

• SECURITY.md

  : サポート範囲、脆弱性の報告方法、設計の特性とバグの区別。

Spool の開発に関するドキュメント:

• CONTRIBUTING.md

  : 問題の報告方法と対応者。

• docs/VISION.md

  : プロダクトビジョンと L0〜L7 マイルストーン。

• docs/ARCHITECTURE.md

  : システム構造、シーム、汎用的言語。

• docs/CONVENTIONS.md

  : ワークフロー、スタイル、テスト階層。

• docs/QUALITY.md

  : ベースラインと CI ゲート基準。

• docs/THREAT-MODEL.md

  : 各境界が持つものとその限界。

• docs/adr/

  : デシジョンレコード（決定記録）。

• AGENTS.md

  : リポジトリで働く AI エージェント向けのガイダンス。