コンテンツにスキップ
SpantailSpantail docs

Claude Plugin をセットアップする

Spantail は人の作業を作業エントリとして、AI エージェントの活動をエージェントセッションとして 記録します。このページはその後半を扱います。Claude Code 用の Spantail プラグインが セッションを自動で記録し、あなたはそれを作業エントリとレポートに変えます。Web アプリからも、 Claude Code の中からも。

クイックスタート の続きから始めます。読み終える頃には、自分の Claude Code のセッションが作業と並んでタイムラインに現れ、エディタを離れずに作業エントリと レポートを作れるようになっています。

事前準備

Section titled “事前準備”
  • 自分のインスタンス、ワークスペース、プロジェクトがあること （クイックスタート を終えた状態）。
  • Claude Code v2.1.143 以降。プラグインの設定機能が入ったバージョンです。
  • bash・jq・curl が PATH にあること。プラグインの Hooks はシェルスクリプトです。 ターンを失敗させたり、セッションの終了を妨げたりすることはなく、依存が足りなければ 黙ってスキップします。git は任意で、あればセッションに実行時のブランチとリポジトリが 付きます。

セッションを記録して使う

Section titled “セッションを記録して使う”

  1. AI エージェントを有効にする

    エージェント活動の記録は既定でオフで、有効にできるのはインスタンス管理者だけです。 設定 → 機能を開き、エージェント活動の記録を有効化をオンにします。

    機能設定の「AI エージェント」カードと有効化トグル。

    インスタンス全体の他のスイッチについてはシステム設定を 参照してください。

  2. エージェントを登録し、2 種類のトークンを用意する

    設定 → エージェント（アカウントの下）を開き、新規エージェントをクリックします。 名前を付け、種別に Claude Code を選びます。有効期限は任意です。ここでは ワークスペースもプロジェクトも選びません。セッションの記録先は、手順 3 の /spantail:link スキルがリポジトリごとに決めます。

    保存すると、エージェントアクセストークン（spantail_aat_…）が一度だけ 表示されます。二度と表示されないので、ここで必ずコピーします。

    エージェント作成後のダイアログ。一度だけ表示されるアクセストークン。

    ここまでが 2 種類のトークンの 1 つ目です。エージェントトークンは 書き込み専用・取り込み専用で、エージェント活動を送ることしかできません。 プラグインのスキルはあなたとして動くため、もう 1 つの資格情報が必要です。

    2 つ目が個人 API トークン（spantail_pat_…）です。設定 → API トークンで 発行してください。手順 5 まで進むなら、ここで作っておきます。

    エージェントとは何か、どのトークンが何をするのかの全体像は エージェント活動を記録するにあります。

  3. プラグインを導入してセッションを記録する

    Claude Code で次を実行します。

    /plugin marketplace add spantail/spantail
/plugin install spantail@spantail

    インストール時にスコープを訊かれたら user を選びます。1 回のインストールで、 作業するすべてのリポジトリをカバーします。プラグインの設定はどのスコープを 選んでもユーザー単位で保存され全リポジトリで共有されるうえ、個人のトークンを 入れるので、コミットされるファイルに置くべきものでもありません。どのリポジトリの セッションをどのワークスペース・プロジェクトに記録するかはこの設定には含まれず、 次のステップでリポジトリごとに設定します。

    有効化すると Plugin options の入力を訊かれます。

    • Spantail instance URL — クイックスタートで作ったインスタンスの URL （https://spantail.<自分のサブドメイン>.workers.dev）。
    • Agent access token — 手順 2 のエージェントアクセストークン （spantail_aat_…）。
    • Personal API token — 手順 2 の個人 API トークン（spantail_pat_…）。 スキルを使うのに必要です。テレメトリのフックだけ使うなら空欄で構いません。
    • Send plan title as session summary — ON にすると、プランモードを 使ったセッションの終了時に、プランのタイトルが作業内容の説明として 送られます。

    続けて、いま作業しているリポジトリで、セッションの記録先をクイックスタートで 作ったワークスペース・プロジェクトにリンクします。

    /spantail:link

    スキルがワークスペースとプロジェクトの ID を尋ねるので、サイドバーのコピー ボタン（ワークスペーススイッチャーとプロジェクト一覧）でコピーして貼り付けると、 .spantail/config.local.json（個人用）に書き込まれます。このファイルは git 管理外に 置いてください（未 ignore の場合はスキルが案内します）。 記録したいリポジトリごとに繰り返してください。リンクしていないリポジトリには 記録先がないため、セッションは黙って誤帰属される代わりに拒否されます。 有効な設定とリンク忘れは /spantail:doctor で確認できます。

    プラグインは 3 つの Hooks を登録し、そのうち送信を行うのは 2 つです。Stop （ターンの終わり）ごとに、そのターンのトークン使用量・時刻・モデル名を、git のブランチ、 リポジトリ URL、作業ディレクトリ、Claude Code のバージョン、リクエスト id とともに 送ります。SessionEnd では冪等に再送したうえで、セッションの終了時刻と、その セッションが触れたプルリクエストを送って確定させます。SessionStart は何も送りません。 /spantail:summary がいま開いているセッションを指定できるよう、セッション id を エクスポートするだけです。

    あとは Claude Code をいつもどおり数分使って、セッションを終了します。Spantail に戻り、 ワークスペースのサイドバーからエージェントを開くと、アクティビティページにそのセッションが 並んでいます。行を開けば、所要時間・トークン使用量・触れたブランチとリポジトリが見えます。

    設定項目の全容、環境変数による上書き、プラグインなしで Hooks を動かす方法は Claude プラグインに、通信の形式は 取り込み API にあります。

  4. セッションから作業エントリを作る

    セッションはエージェントがしたことの記録で、作業エントリはあなたがしたことの記録です。 エージェントのアクティビティページで自分のセッションにチェックを入れ、 選択から作業を記録をクリックします（C キーでも同じです）。

    2件のセッションを選択し「選択から作業を記録」ボタンが出たエージェントのアクティビティページ。

    作業エントリのダイアログが、選択内容から前もって埋まった状態で開きます。所要時間はその合計、 日付は最も時間を占める日、説明はセッションの説明（複数選んだ場合は代わりに箇条書きの メモになります）、プロジェクトは共通のものです。すべて編集でき、何から作られた記録なのかが バナーに表示されます。

    選択したセッションから前埋めされた作業エントリダイアログと、その旨を示すバナー。

    紐付けられるのは自分のセッションだけで、プロジェクトは 1 つに揃っている必要があり、 一度に選べるのは 50 件までです。保存すると、その作業エントリは元になったセッションと紐付いた まま、タイムラインに並びます。

  5. Claude Code から作業エントリとレポートを作る

    プラグインはスキルも持っています。Hooks と違い、スキルは Spantail の MCP 接続を通じて あなたとして動きます。手順 2 の個人 API トークンが必要なのはそのためです。

    /spantail:log-work を引数なしで実行すると、いま話しているセッションの作業から作業エントリを 提案します。作業内容を要約し、かかった時間を見積もり、記録する前に確認を求めます。 自由記述を渡せば、その内容で記録できます （/spantail:log-work 認証のバグを修正, 2h, project core）。

    /spantail:log-work #123 2h yesterday は GitHub の issue に対して記録します。 プロジェクトはサーバー側のリポジトリ対応表から解決され、issue のタイトルとラベルが入り、 一致するエージェントセッションが紐付けられます。対応表の設定は GitHub 連携を参照してください。

    /spantail:create-report はレポートを組み立てます。保存する前に必ずプレビューを レンダリングして見せてくれます。

    読み取り専用のエージェントも 2 つ付いてきます。作業エントリを振り返る spantail-work-analyst と、Hooks が集めたセッションのテレメトリを分析する spantail-agent-activity-analyst です。

ここまでで作ったもの

Section titled “ここまでで作ったもの”

Claude Code のセッションが自動で Spantail に流れ込むようになり、それを扱う 2 つの経路が どちらも通りました。セッションを選んで作業エントリに変える Web アプリと、あなたとして作業エントリや レポートを作るスキルを備えた Claude Code そのものです。

次に読むもの

Section titled “次に読むもの”