Claude プラグイン

Claude Code 向け Spantail プラグインは、Claude Code のセッションをエージェント活動として自動で取り込み、さらに Claude Code の中から作業を記録しレポートを作るためのスキルとエージェントを追加します。

Claude Code v2.1.143 以降が必要です。

インストール

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

プラグインを有効化すると、インスタンスの URL とエージェントアクセストークン （先にエージェントを登録してください）、スキルの MCP サーバー用の個人用 API トークン（任意。スキルとエージェントを参照）の入力を求められます。Claude Code はこの設定をプラグイン単位で保存し、インストールスコープに関わらず全リポジトリで共有します。ワークスペースとプロジェクトがこの設定に含まれないのはそのためです。インストーラーにスコープを聞かれたら user scope を選んでください。1 回のインストールで全リポジトリをカバーし、帰属はリポジトリごとに設定します（下記）。

各設定は環境変数（SPANTAIL_API_URL、SPANTAIL_AGENT_TOKEN、 SPANTAIL_SEND_SESSION_SUMMARY）で上書きでき、環境変数が優先されます。これらの上書きはフックにのみ適用されます。同梱の MCP サーバーはプラグインの apiUrl / apiToken の設定を読むため、SPANTAIL_API_URL でインスタンスを上書きする場合は、プラグイン設定側も同じ値に揃えてください。

フックの動作には bash・jq・curl が PATH に必要です。フックがターンを失敗させたり、セッションの終了を妨げたりすることはありません。問題があれば stderr にログを残してスキップします。

リポジトリをリンクする

リポジトリのセッションがどのワークスペース・プロジェクトに記録されるかは、リポジトリ自身に設定します。記録したい各リポジトリで次を実行してください:

/spantail:link

ワークスペースとプロジェクトの ID を尋ねられるので、サイドバーのコピーボタン（ワークスペーススイッチャーとプロジェクト一覧）でコピーして貼り付けると、個人用の .spantail/config.local.json に書き込まれます。このファイルは git 管理外に置いてください（未 ignore の場合はスキルが案内します）。チームで共有するリンクは /spantail:link --shared が .spantail/config.json に書き込みます。一度コミットすれば、プラグインをインストールしたコラボレーター全員に適用されます。

これらのファイルに書けるのは workspaceId と projectId だけです。clone したリポジトリは信頼できない入力であるため、フックはリポジトリ内のファイルから apiUrl やトークンを読みません。リンク済みのリポジトリは帰属を完全に所有し、個人用の local ファイルはコミット済みの共有ファイルを丸ごと置き換えます。ワークスペースだけのリンクが、別の場所で設定されたプロジェクトを引き継ぐことはありません。環境変数（SPANTAIL_WORKSPACE_ID、SPANTAIL_PROJECT_ID）は両ファイルより優先されます。

リンクしていないリポジトリには記録先がなく、セッションは黙ってどこかに記録される代わりに取り込み時に拒否されます（それでもリンクなしのリポジトリを一律にあるワークスペースへ送りたい場合は、SPANTAIL_WORKSPACE_ID をユーザーグローバルに設定します）。各設定がどこから解決されているか、現在のリポジトリがリンク済みか、直すべき点は何かは、いつでも /spantail:doctor で確認できます。

送信される内容

プラグインのフックが送るのはコンパクトなテレメトリのみです。会話本文・思考・ツールの入出力がマシンの外に出ることはありません。

毎回の Stop（ターン終了）で: ターンごとのトークン使用量・タイムスタンプ・モデル名に加え、git ブランチ・リポジトリ URL・作業ディレクトリ・Claude Code のバージョン・プロバイダのリクエスト ID をイベント属性として送ります。送信はバックグラウンドに切り離して実行されるため、ネットワークが遅くても次のプロンプトが待たされることはありません。
SessionEnd で: イベントの最終再送（冪等）に続けて、実時間の終了時刻とセッションが触れたプルリクエスト（context.refs）を finalize に送ります。

1 つだけオプトインの項目があります。sendSessionSummary 設定（または単一セッションなら /spantail:summary on）を有効にすると、SessionEnd フックはタイトルをエントリの説明として送ります。使われるのはそのセッションのプランファイルのタイトル、プランがないセッションでは transcript 自身のセッションタイトル（Claude Code が生成するもの。compact または resume したセッションにのみ存在）です。どちらも transcript の構造化レコードから機械的に抽出され、追加の推論は行いません。どちらもないセッションでは説明は空のままです。他の説明と同様そのまま保存されてレポートや共有リンクに表示され得るため、自分で有効にしない限りオフのままです。

スキルとエージェント

名前	用途
`/spantail:log-work`	作業エントリを作成 — 指示した内容からも、現在のセッションの作業内容からも。現在のセッションの作業を記録した場合、そのセッションのエージェントエントリ（記録済みのもの）が作業エントリに自動で紐づきます。
`/spantail:log-work #N <duration> [date]`	GitHub Issue に対して記録します。サーバーがリポジトリのマッピング（GitHub 連携参照）からプロジェクトを解決し、Issue の件名とラベルを補完し、関連するエージェントセッション — テレメトリが記録済みなら（最初のターン完了後）、実行中のセッション自身も含む — を紐づけます。紐づいたセッションにタイトルがあれば、エントリのメモに追記されます。
`/spantail:create-report`	レポートを作成。保存前に必ずプレビューします。
`/spantail:summary on\|off`	セッション単位で、セッションのタイトル（プランタイトル、なければ生成されたセッションタイトル）を説明として送るかを切り替え。
`/spantail:link [--shared]`	現在のリポジトリをワークスペース・プロジェクトにリンク（リポジトリをリンクする参照）。
`/spantail:doctor`	各設定がどこから解決されているかと、直すべき点を表示。
`spantail-work-analyst`（エージェント）	作業エントリのふりかえり分析。
`spantail-agent-activity-analyst`（エージェント）	エージェントのセッションテレメトリ分析。

スキルと分析エージェントはあなたとして動くため、個人用 API トークンによる Spantail MCP 接続を使います（フックの書き込み専用エージェントトークンとは別の資格情報です）。この MCP サーバーはプラグインに同梱されています。任意の apiToken を設定すると、インスタンスの /mcp に HTTP であなたとして接続します。フックだけ使う場合は apiToken を空欄のままにでき、CLI も不要です。例外が 2 つあります。 /spantail:doctor と /spantail:link は MCP なしで動作します。

別のクライアントから、あるいはプラグインを使わずに MCP を使う場合は、手動で登録します。 MCP を参照してください。

プラグインを使わない場合

フックのスクリプトは、settings.json に手動で配線し SPANTAIL_* 環境変数を設定すれば単体でも動きます。手順はプラグインの README を参照してください。プログラムから直接送るには取り込み API を使います。