token-receipt

Token Receipt

今回の AI 会話で消費したトークンを、スクリーンショットで共有できるモノスペースの感熱紙レシートにします。レポートとしての網羅性よりビジュアルを重視しますが、データの根拠は正直に示します。実際のログを優先し、次に公式価格に基づく推定を使い、欠落している情報は明記します。

ユーザーが呼び出す方法

以下の表現があれば、デフォルトで直接起動します。

• token receipt
• token 小票
• 对话发票
• AI 用量账单
• 把这次对话打成小票
• 看看这轮 token 消耗
• 查看本次对话 Token 消耗

Claude Code に自動トリガーが設定されている場合は、SessionEnd の終了時にも自動でレシートを発行します。

現在の製品方針

• メインの出力は引き続きチャットダイアログ内のテキストレシートとし、HTML はそれに付随する印刷用の出力先として返します。主役を奪うことはありません。
• QR コードは作成しません。下部には現在のバーコード／レシート ID の構造を維持します。
• トリガー方針はホストの機能に応じて分けます。
  • Claude Code：SessionEnd auto trigger + 触发词 を使用します。
  • Codex：トリガー語を使用します。
  • Kimi Code：--agent-tool kimi-code を使用します（context.jsonl 内の _usage を読み取って累積できます）。
  • OpenCode：--agent-tool opencode を使用します（デフォルトのデータディレクトリにある opencode*.db SQLite を読むか、--session <db> --opencode-session-id ses_... を使用します）。
  • Trae：トリガー語を使用します。
• すべてのホストに Claude Code のようなライフサイクルフックがあるとは限りません。自動トリガーのインストールは、SessionEnd フックのサポートを確認済みのホストでのみ行ってください。

すぐに実行する

まず、スクリプトを実行してレシートを生成してください。

python3 scripts/token_receipt.py

サポート対象のチャットホストで手動で呼び出す場合、レシートを Bash の stdout に出すだけにしないでください。 チャット返信モードに統一して実行することを優先します。

python3 scripts/token_receipt.py --agent-tool codex --chat-reply
python3 scripts/token_receipt.py --agent-tool claude-code --session ~/.claude/usage-data/session-meta/${CLAUDE_CODE_SESSION_ID:-$CLAUDE_SESSION_ID}.json --chat-reply
python3 scripts/token_receipt.py --agent-tool kimi-code --chat-reply
python3 scripts/token_receipt.py --agent-tool opencode --chat-reply

これにより、次の 3 つを同時に行います。

• 完全なレシートをチャット返信の本文として出力します
• /tmp/token-receipt.html に HTML を自動で保存します
• 返信の末尾に [Printable HTML](file:///tmp/token-receipt.html) を付けます

デフォルトのコマンドを一度実行してから、会話ファイルを grep し、もう一度実行するのは避けてください。そうすると、ツール出力にロゴが複数枚表示されるだけです。

よく使うパラメーター：

python3 scripts/token_receipt.py --agent-tool codex --model gpt-5.4 --width 48 --stream
python3 scripts/token_receipt.py --agent-tool kimi-code
python3 scripts/token_receipt.py --agent-tool opencode
python3 scripts/token_receipt.py --provider anthropic --agent-tool claude-code --model claude-sonnet-4-5 --input-tokens 12487 --cached-input-tokens 8742 --output-tokens 3215
python3 scripts/token_receipt.py --provider openai --agent-tool trae --model gpt-5.4 --input-tokens 12487 --output-tokens 3215
python3 scripts/token_receipt.py --provider alibaba --agent-tool trae --model qwen3.6-plus --input-tokens 1000000 --output-tokens 1000000
python3 scripts/token_receipt.py --footer-tone snarky --conversation-summary "用户正在反复打磨 Claude Code 小票的传播视觉"
python3 scripts/token_receipt.py --show-fields
python3 scripts/install_claude_auto_trigger.py
python3 scripts/uninstall_claude_auto_trigger.py

対話型ターミナルでは、スクリプトはデフォルトで 1 行ずつ出力します。現在の stdout が TTY でない場合は、レシート全体をまとめて出力します。1 行ずつの出力を強制するには --stream を、全体をまとめて出力するには --no-stream を使用します。チャット欄で返信する場合は、出力を Markdown のコードブロックで囲み、モノスペースの見た目を維持してください。

呼び出しモード

• デフォルトの目標は、RECEIPT # / TOTAL / USD ESTIMATE のような要約だけを表示するのではなく、ユーザーがダイアログ内でレシート全体を直接確認できるようにすることです。
• スキルがチャット内で呼び出された場合は、完全なレシートのコードブロックを優先して返してください。「ターミナルに出力しました」とだけ報告しないでください。
• すべての対応ソフトウェアでは、デフォルトで統一されたチャット返信モード --chat-reply を使用します。
• --chat-reply は /tmp/token-receipt.html を自動で書き出し、レシートのコードブロックとローカルファイルへのリンクを一緒に返します。
• ターミナル PTY への出力は追加のデモ用経路であり、デフォルトのメイン経路ではありません。ユーザーが「ターミナルに印刷して」「ターミナルで実行して」と明確に指定した場合にのみ、ターミナルをメインの出力先にしてください。
• ホストがトークンのストリーミングに対応している場合、返信にはできるだけレシート本体だけを含め、説明は少なくして、ダイアログ内で自然に表示されるようにしてください。
• ホストがツールの stdout をチャットバブル内に段階的に表示できない場合、スキル側から UI に 1 行ずつ表示させることはできません。その場合も要約に切り替えるのではなく、完全なレシートをダイアログに貼り付けてください。

チャット返信の要件

• デフォルトの返信は、チャットで使いやすい完全な成果物にしてください。レシートのフェンス付きコードブロックと [Printable HTML](file:///tmp/token-receipt.html) を含めます。
• コードブロックの前後に、説明、要約、状態報告、フィールドの抜粋、箇条書きを追加しないでください。
• RECEIPT #、TOTAL、USD ESTIMATE のような要約だけを返さないでください。
• Claude Code でスクリプトを Bash から実行する必要がある場合は、--chat-reply を直接使用してください。--write /tmp/token-receipt.txt と --write-html ... を手動で組み合わせた 2 段階の処理は避けてください。
• 生成に失敗した場合、レシートを発行できないほどフィールドが欠落している場合、またはユーザーが明確に説明を求めた場合にのみ、デフォルトの返信形式から外れてかまいません。その場合も、まず簡潔に説明し、その後にレシートまたはエラーの理由を示してください。
• 推奨形式は次のとおりです。

```text
<full receipt here>
```

[Printable HTML](file:///tmp/token-receipt.html)

データの根拠

1. デフォルトの動作は「現在のソフトウェアからデータを取得する」です。
   • Codex で実行する場合は、Codex の会話を読み取ります。
   • Claude Code のフックまたは会話内で実行する場合は、Claude Code の usage log／transcript を読み取ります。
   • Kimi Code（Kimi CLI）：--agent-tool kimi-code を使用し、context.jsonl 内の _usage.token_count を読み取ります。これは API の内訳ではなく、コンテキストの累積値です。米ドルでの推定額は UNMAPPED と表示されます。
   • OpenCode：~/.local/share/opencode/opencode*.db（または OPENCODE_DATA_DIR／%LOCALAPPDATA%\\opencode）から、assistant メッセージの tokens.input／cache.read／cache.write／output／reasoning と modelID（provider/model）を読み取ります。--scope latest-turn はトークン数またはコストがある最後の assistant を取得し、session はセッション内の複数の assistant の値を合算します。ルートセッションは、session テーブルで parent_id を含まない行です（アーカイブ列がない場合は、クエリを切り替えて処理します）。
   • 他のソフトウェアのログのほうが新しいからといって、別のソフトウェアから読み取ることは禁止です。
2. 現在の実行環境からソフトウェアを特定できず、ローカルに複数のログが存在する場合は、--agent-tool codex、--agent-tool claude-code、--agent-tool kimi-code、または --agent-tool opencode を明示的に渡してください。推測しないでください。
3. デフォルトでは、最新の token_count イベントにある last_token_usage、つまり「最新ターンのレシート」を使用します。
4. ユーザーが累積請求を求めた場合は、--scope session を使用して total_token_usage を読み取ります。
5. ベンダーはまず session_meta.payload.model_provider を読み取ります。モデル名はまず session_meta.payload.model* を読み取り、なければ turn_context.model にフォールバックします。どちらもない場合は呼び出し元に --model を渡すよう求め、それ以外の場合はレシートに MODEL: UNRECORDED と表示します。
6. 価格の推定には references/pricing.json の公式価格表のみを使用します。モデルが見つからない場合は PRICE: UNMAPPED と表示し、金額を捏造しないでください。
7. 価格表ではモデルごとに通貨を保持します。米ドル建てモデルには USD ESTIMATE、人民元建てモデルには CNY ESTIMATE と表示します。GLM には明記された百炼の CNY 公開価格を、MiMo には OpenRouter のルーティング価格を使用します。プラットフォーム価格をメーカー直結の請求額のように見せないでください。
8. 主見出しには THANK YOU FOR CODING WITH ... を使用し、実際のブランドレシートのようにしてください。レシート上に DATA: SNAPSHOT は追加しないでください。
9. 上部のロゴはソフトウェアに応じて決定します。Codex、Claude Code、Trae、Kimi Code、OpenCode には、それぞれ対応するロゴブロックがあります。感謝のメッセージは引き続きモデル／ベンダー（Claude／GPT／Qwen…）に基づいて表示し、ホストのロゴをモデル名として扱わないでください。
10. ユーザーが言語を切り替えた場合：

• 英語：--language en
• 中国語：--language zh-CN
• ユーザーが「中文版小票／English receipt」と直接指定した場合は、呼び出し時に対応するパラメーターを付けてください。

11. --show-fields を実行すると、現在のログから実際に読み取れるフィールドを確認できます。詳しい説明は references/available-fields.md を参照してください。

アーキテクチャ

• token_receipt/data.py
  • Codex JSONL、Claude の使用状況データ、Claude の transcript model、Kimi Code の context.jsonl、OpenCode の SQLite、価格表、フィールド機能レポートの読み込みを担当します。
• token_receipt/render.py
  • ブランドヘッダー画像、レシートのレイアウト、フッター、バーコード、最終的なレシートテキストを担当します。
• token_receipt/hooks.py
  • Claude Code の SessionEnd hook の payload、インストール、アンインストールを担当します。
• scripts/token_receipt.py
  • CLI の薄いエントリーポイントにすぎず、すべてのビジネスロジックを詰め込むことはありません。

トリガー戦略

1. Claude Code
   • claude-receipts の SessionEnd hook を参考にしています。
   • インストーラーを提供しています：python3 scripts/install_claude_auto_trigger.py
   • アンインストーラーを提供しています：python3 scripts/uninstall_claude_auto_trigger.py
   • セッション終了時にレシートを自動生成します。セッション中にユーザーが「token receipt／token レシート／会話の請求書／AI 使用量の請求書」と明示した場合もトリガーできます。
2. Codex
   • 現在はトリガーワードで呼び出す方式で、SessionEnd hook の存在は前提としていません。
3. Kimi Code（Moonshot kimi-cli）
   • --agent-tool kimi-code を指定します。環境変数 KIMI_SESSION_ID でセッションを指定でき、KIMI_SHARE_DIR でデータディレクトリを上書きできます。または、--session ~/.kimi/sessions/<hash>/<id>/context.jsonl を指定します。
4. OpenCode
   • --agent-tool opencode、OPENCODE_SESSION_ID、--session <opencode*.db> --opencode-session-id ses_... を指定します。OPENCODE_DATA_DIR は任意です。
5. Trae
   • 現在はトリガーワードで呼び出す方式で、ライフサイクル hook の存在は前提としていません。

Kimi Code のワンステップ例

python3 scripts/token_receipt.py --agent-tool kimi-code
python3 scripts/token_receipt.py --session ~/.kimi/sessions/<hash>/<session-id>/context.jsonl

トリガーワードの設計について詳しくは、references/trigger-phrases.md を参照してください。

OpenCode のワンステップ例

python3 scripts/token_receipt.py --agent-tool opencode
python3 scripts/token_receipt.py --session ~/.local/share/opencode/opencode.db --opencode-session-id ses_xxx --scope session

ビジュアル原則

• デフォルトの幅は 48 文字です。ロゴ領域には █░▒▓▐▛▜▌▘▝ のピクセル文字を使用でき、金額領域では人民元記号 ¥ を使用できます。それ以外のレシート部分は、できるだけ ASCII を使用してください。
• 上部は一般的な表ではなく、ブランドレシートのようにします。
  • Codex：ユーザー指定のハーフトーンピクセルロゴに CODEX を添えます。
  • Claude Code：参考画像のピクセルのカニの輪郭を、縦横比を保って縮小したものに CLAUDE CODE を添えます。
  • Trae：ユーザー指定のピクセルブロックロゴに TRAE を添えます。
  • Kimi Code：四角形で構成したロゴに KIMI CODE を添えます。
  • OpenCode：ブロック状のロゴに OPENCODE を添えます。
  • 未認識のプロバイダー：AI CHECKOUT。
• 中段は実際のレシート形式にします。ITEM / TOKENS の 2 列を横線で区切り、数値を右揃えにします。
• 3 つのツールに共通する、固定のレシート項目は Input Tokens、Output Tokens、Cache Read Tokens、TOTAL です。ログまたは手動パラメーターから値を確認できる場合にのみ出力し、未確認の項目をレシートに記載しないでください。
• 任意の項目は Reasoning Tokens、Cache Write Tokens です。実際のフィールドがある場合は表示し、ない場合は省略します。このうち Cache Write Tokens は通常 Codex のログにはなく、Anthropic のキャッシュ関連データまたは手動パラメーターから値を取得できる場合にのみ表示します。
• 現在の Codex ログでよく読み取れるフィールドは、input_tokens、cached_input_tokens、output_tokens、reasoning_output_tokens、total_tokens、model_context_window です。
• SCOPE LATEST-TURN は出力せず、代わりに CONTEXT USED を使用して、このターンのコンテキスト入力量を表示します。コンテキストウィンドウがある場合は used/window を表示します。
• TOTAL は視覚的に目立たせ、最下部には短いキャッチフレーズ、ASCII バーコード、レシート ID を必ず配置します。デフォルトのフッターは、固定文のランダム選択でも、subject/resource/artifact のようなスロットを組み合わせた文章でもありません。今回の会話に対する、モデルの短いツッコミや励ましのようなものにしてください。呼び出し時には、現在の会話を一文で要約した内容を --conversation-summary で渡すことを優先し、カスタムの --footer も指定できます。
• 詳しいレイアウト規則は references/receipt-style.md を参照してください。

検証

Skill の作成または変更後、少なくとも次を実行してください。

python3 scripts/validate_receipt.py

行幅、必須項目、Claude のブロックロゴ、バーコード、価格が不明な場合のフォールバック、および固定されていない項目が出力されないことを確認します。