トークンレポート

Looptrack はコーディング AI が使ったトークンを記録してイシューに帰属させ、期間ごとの PDF のレポートにまとめます。読み手はレポートを読む管理者と AI の消費を計測される開発者の 2 通りです。このページでは何が記録されてどう集計され、レポートがどうできあがるのかを順に見ていきます。

何が記録されるか

手元から送るのはスナップショット、つまりある時点の「会話の累計」1 件です。実はサーバ自身はトークンのことを何も知りません。値があるのは手元にある AI の会話記録の中だけなので、looptrack がその記録（Claude Code は ~/.claude/projects/…、Codex は ~/.codex/sessions/…）を読んで数値を送ります。

スナップショットに入るのは次のものです。

4 種類のトークン（入力・キャッシュ作成・キャッシュ読み込み・出力）の累計。本体とサブエージェントを分けてモデルごとの内訳も持つ
応答の数・git のブランチ・作業ディレクトリの名前
セッションの終わりには会話の区間の一覧（開始時刻・種別・待ち分・所要分・トークン）

差分ではなく累計を送ります。だから 1 件が欠けても重なっても誤差にならず、次の 1 件で追いつきます。スナップショットはサーバに追記するだけです（DB の利用者には行を足す権限しかありません）。

送る契機

いつ	送る者	補足
CLI の変更操作の直後（`new`・`push`・`comment`・`status`・`close`・着手した `next`・`verify`・`assign`）	CLI 自身	どの AI でも、フックが無くても付く。AI の下でなく人がターミナルから打ったときは送らない
MCP の変更操作の直後	`PostToolUse` のフック（Claude Code・Codex）	イシューを変えるツールだけ
ターンの終わり	`Stop` のフック	前回の送信から 10 分未満なら送らない（`LOOPTRACK_USAGE_THROTTLE_MIN`）
セッションの終わり	`SessionEnd` のフック	常に送る。区間の一覧つき
`looptrack issue usage attach <ID>` を実行したとき	人か AI	その会話の累計を、そのイシューに手で付ける

送信が操作の邪魔をすることはありません。 CLI は 2 秒、フックは 5 秒で打ち切ります（LOOPTRACK_USAGE_TIMEOUT）。操作の結果も終了コードも変わりません。送れなかった分は資格情報と同じ置き場（~/.config/looptrack/、Windows は %APPDATA%\looptrack\）の usage-spool/ に置かれます。置かれた分は次の起動で送り直します。7 日たったものは捨てます。失敗が続いたら？セッション開始時の summary に 1 行で出ます。フックのほうは失敗しても黙って終わるから、というのがその理由です。

GitHub Copilot を計測できるのは利用者が OpenTelemetry のファイル出力を有効にしたときだけです（AI ごとの手引き）。

送らないもの

人が打った指示文は既定では送りません。 サーバに届くのは区間ごとの数値だけです。各指示の先頭 44 文字（区間の「作業名」）を送るのは次の両方が許すときに限られます。

プロジェクト別ルール usage.send_prompts が true（管理者が <サーバの URL>/admin/projects で切り替えるか、looptrack project rules set で書く）
利用者が LOOPTRACK_USAGE_SEND_PROMPTS=0 を設定していない

CLI はプロジェクトの設定をサーバの応答で知り、次の送信からそれに従います。知るまでは送りません。サーバの側でも許していないプロジェクトに届いた作業名は保存しません。

止め方

手元から一切送らないなら LOOPTRACK_USAGE=0 を設定するだけです。
1 つの会話だけをレポートから外したいときは、その会話の中の発言に 本セッションはレポート対象外 と書きます。会話そのものは記録されます。レポートでは合計から外して対象外として別に示します。効くのは日本語の文だけ。「」 や引用符で囲んだもの（引用）は数えません。

どう集計するか

サーバは差分を保存しません。問い合わせのたびに計算しています。

会話ごとにスナップショットを累計の順に並べる。
隣り合う 2 件の差をその区間の消費とする。
区間はその区間を閉じたスナップショットのイシューに帰属させる。起票の前の調査は起票したイシューへ、コメントの前の作業はそのイシューへ入ります。
ターンの終わり・セッションの終わりで閉じた区間は、その会話で直前に操作したイシューがまだ開いていればそこへ。開いていなければ未帰属です。

looptrack issue usage show <ID> を使うと 1 つのイシューの消費が段階（区間を閉じた操作）ごとに出ます。ただ、3 の規則があるので 1 つの会話で 2 つのイシューを並行して進めた分は区別できません。

トークン情報の付いていない操作

AI の変更操作が「付与済み」になる条件は、同じイシュー・同じ利用者のスナップショットが操作から 10 分以内に届くことです。後から usage attach で付けたものも付与済みに数えます。人がターミナルから打った操作はそもそも数えません。

bash

looptrack issue usage missing                   # 直近 30 日の自分の AI 操作（--days N）
looptrack issue usage missing --all-users       # 全員の分と充足率
looptrack issue usage attach DEMO-0004          # この会話の累計をイシューに付ける

summary の末尾には直近 7 日の自分の操作のうち、トークン情報がまだ付いていないものが並びます。必須にしたいならプロジェクト別ルール usage.require_on_close を設定しておきましょう（管理者の手引き）。設定すると AI はその会話のトークン情報が無いままイシューを Done・Canceled にできなくなります。CLI は自動で付けてから 1 回だけやり直します。

レポートの作り方

流れはこうです。期間を決めてその中で閉じた区間を集計し、プロジェクトの台帳に登録します。集計はサーバの仕事です。本文と PDF は AI を動かしている手元で作ります。 PDF がサーバに置かれることはありません。

ボードから AI に依頼する

プロジェクトのボード（<サーバの URL>/p/<slug>/）のレポート作成で依頼を登録します。期間は「前回以降」か日付の範囲。AI への対象とメモも書けます。editor 以上が必要です。
次にコーディング AI がセッションを始めると、依頼が summary の末尾に出ます。
あとは AI に「トークンレポートを作成して（依頼 #N）」と頼むだけ。skill token-report が集計・本文・PDF・台帳の登録まで進めます。

依頼が完了するのはその番号の付いた台帳の行ができたときです。ほかの方法では取り下げられません。同時に抱えられる未完了の依頼は 20 件までです。

skill は looptrack issue init が .claude/skills/token-report/SKILL.md に置きます。依頼の登録は省いてもかまいません。「トークンレポートを作成して」（前回以降）と頼んだり、期間を指定して頼んだりもできます。

手で作る

bash

looptrack issue usage requests                                  # 未完了の依頼（--all で完了したものも）
looptrack issue usage report --since-last --json > r.json       # 前回のレポート以降
looptrack issue usage report --from 2026-09-01 --to 2026-09-30  # 期間を指定して、読むための表で
looptrack issue usage report --request 3 --xlsx r.xlsx          # 依頼 #3 の期間を数表で
looptrack report pdf --report r.json --content body.json --check
looptrack report pdf --report r.json --content body.json --out report.pdf
looptrack issue usage ledger add "2026年9月" --from-report r.json --note report.pdf
looptrack issue usage ledger list

`usage report` の指定	期間
`--since-last`	台帳で最も新しいデータ終端から今まで（台帳が空なら最初から）
`--from D --to D`	`[from, to)`。日付だけの `--to` はその日を含む。日付は Asia/Tokyo で読む。`--to` の既定は今
`--request N`	依頼 #N の期間（実行したときに決まる）

レポートに出るのは合計と、イシュー・ラベル・イシューの種類・段階・AI・案件・会話ごとの内訳です。未帰属と対象外の会話は合計に入れず別に示します。案件ごとの内訳はイシューのラベルかブランチ名から案件名を取り出して区間をまとめたものです。その取り出し方を決めるのがプロジェクト別ルール usage.case_pattern の正規表現です。

PDF

looptrack report pdf は 2 つの JSON から PDF を作ります。集計（usage report --json の出力）と、本文（AI が書く節。形は skill にあります）です。数表は集計から組み立てるので、数値を手で写す場面はありません。 --check は入力を確かめて節と表の数を出すだけです。見出しに「データの限界」を含む節は必須です。日本語フォントは内蔵済みです。差し替えたいときは TOKEN_REPORT_FONT（TrueType のフォントのパス）を使います。 skill の保存先はリポジトリの外の ~/Documents/トークンレポート/<slug>/（TOKEN_REPORT_DIR）です。

台帳

usage ledger add は 1 つのレポートを 1 行として登録します。持つのは名前・期間・データ終端・対象外の会話・合計・メモです。 --from-report を付ければこれらを集計 JSON から写し、--request で集計したときは依頼の番号も写します。

行は変更も削除もできません。 名前はプロジェクトの中で一意です。
次の --since-last は台帳で最も新しいデータ終端から始まります。だから期間は重なりも欠けもしません。
気をつけたいのは遅れて届いたスナップショット。前回のデータ終端より前の時刻のものは、どのレポートにも入りません。
台帳への登録には editor 以上が必要です。閲覧者にできるのは集計を読むことだけ。

設定

設定	置き場	効果
`LOOPTRACK_USAGE=0`	利用者の環境変数	トークン情報を送らない
`LOOPTRACK_USAGE_SEND_PROMPTS=0`	利用者の環境変数	プロジェクト別ルールに関わらず作業名を送らない
`LOOPTRACK_USAGE_TIMEOUT`	利用者の環境変数	送信を待つ秒数（CLI は 2・フックは 5）
`LOOPTRACK_USAGE_THROTTLE_MIN`	利用者の環境変数	ターンの終わりに送る間隔の分（10。`0` で毎回送る）
`LOOPTRACK_USAGE_DEBUG=1`	利用者の環境変数	送れなかった理由を出す
`usage.send_prompts`	プロジェクト別ルール	作業名の送信を許す（既定は送らない）
`usage.require_on_close`	プロジェクト別ルール	AI がイシューを閉じる前にトークン情報を必須にする
`usage.case_pattern`	プロジェクト別ルール	案件ごとの内訳の正規表現
`TOKEN_REPORT_DIR`	利用者の環境変数	skill がレポートを保存する場所
`TOKEN_REPORT_FONT`	利用者の環境変数	PDF の TrueType フォント

プロジェクト別ルールの設定には looptrack project rules set を使います（管理者の手引き）。設計の全体は DESIGN.md §9-5 にあります。

トークンレポート ​

何が記録されるか ​

送る契機 ​

送らないもの ​

止め方 ​

どう集計するか ​

トークン情報の付いていない操作 ​

レポートの作り方 ​

ボードから AI に依頼する ​

手で作る ​

PDF ​

台帳 ​

設定 ​