Communitygithub.com

kitorz/token-step-tracker

各エージェントステップ後にトークン使用量を推定し、設定可能なアラートをトリガーし、コンテキスト節約の実用的な方法を提案します。

token-step-tracker とは?

このスキルは、AIエージェント(Claude Code、Coder、Codexなど)の各ステップ終了時にトークン使用量を推定し、設定された閾値に達した場合にアラートを表示します。タスクを中断せず、課金精度を主張せずに、おおよそのトークン消費を追跡できるため、開発者はコンテキスト管理を意識しながら作業を進められます。 主な機能は以下の通りです。 - ユーザー指定またはデフォルト(10,000トークン)の間隔でアラートを発行。 - 各ステップ終了時にコンパクトなチェックポイント(ステップ名、推定範囲、累積範囲、主なコスト要因、節約提案)を表示。 - 閾値に達した場合、赤丸と太字の数字を使ったアラートをマークダウンで通知。 - 推定は観測可能なコンテンツ(プロンプト、ツール出力、生成コンテンツ)に基づき、隠れたシステム・推論・キャッシュ・プラットフォームオーバーヘッドは除外。 - 各チェックポイントで最大1つの具体的な節約提案(例:大きなファイルは検索してから読む、結果を再利用する、出力を絞る)を提示。 - タスク終了時にステップ数、総推定範囲、最大ステップ、アラート発行回数、最善の次回節約案を含むサマリーを表示。 このスキルは純粋なスキルであるため、OS通知やテキスト色の保証はできませんが、マークダウンとインラインHTML色(サポートされている場合)による可搬性の高いアラートを提供します。

対応~Claude Code~Codex CLI~Cursor
npx skills add kitorz/token-step-tracker

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

乙女座向けじゃないトークンアラート

タスクを中断したり、課金精度を主張したりせずに、おおよそのトークン使用量を追跡します。

追跡を開始する

  1. タスクを意味のある成果ベースのステップに分割します。既存の計画がある場合はそれを維持します。
  2. トークン数値は推定値であり、隠れたシステム、推論、プラットフォームのオーバーヘッドを除外していることを一度明示します。
  3. ユーザーのリクエストから正の整数のアラート間隔を読み取ります(例:alert every 5000 tokens の 5000)。ユーザーが間隔を指定せずにアラートを要求した場合は 10000 を使用します。有効な間隔を一度宣言します。
  4. 次のアラートしきい値を1間隔に設定し、各アラート後にその間隔分だけ進めます。
  5. 推定値を向上させるためだけに、余分なツール呼び出し、ファイルの再読み取り、追加コンテンツの生成を行わないでください。

完了した各ステップを報告する

ステップの有用な結果を報告した後に、次のコンパクトなチェックポイントを追加します。

トークンチェックポイント · ステップ {n}: {name}
今回のステップ: ≈{low}–{high} トークン | 累計: ≈{low}–{high}
主な増加要因: {largest observable source}
次回の節約案: {one actionable suggestion or "No worthwhile change—keep the current approach."}

ステップは、意味のある結果を生成した場合のみカウントします。ステータスメッセージ、承認、待機、または些細な内部アクションに対してチェックポイントを作成しないでください。

しきい値アラートを表示する

各チェックポイントの後、累積範囲の中間点を次のアラートしきい値と比較します。しきい値に達するか超えた場合、以下を追加します。

> :red_circle: トークンアラート | **{threshold} 推定トークン使用**

ポータブルなフォールバックとして、赤丸と太字の数字を使用します。ホストが安全なインラインHTML色をサポートしている場合は、値を <span style="color:#d00"><strong>{threshold}</strong></span> として表示します。生のターミナルエスケープコードは決して発行しないでください。純粋なスキルはオペレーティングシステムの通知を作成したり、テキストの色を保証したりできないため、これをアラートと呼び、システムポップアップとは呼びません。

1つのステップが複数のしきい値を超えた場合は、超えた中で最も高いしきい値に対して1つのアラートを発行し、次のしきい値を累積中間点より先に進めます。既に発行したしきい値を繰り返さないでください。

一貫性をもって推定する

ステップ中に処理または生成された観測可能なコンテンツから推定します。

  • 英文散文: 約1トークン/4文字。
  • 中文散文: 約1トークン/1.5–2文字。
  • コードおよび構造化データ: 約1トークン/3文字。
  • 関連するプロンプトテキスト、新しく読み取ったツール出力、生成コンテンツ、ステップで可視的に再利用されたコンテキストを含めます。
  • 1つのステップ内で同じアーティファクトを二重にカウントしないでください。
  • 少なくとも±25%の幅を持つ範囲を使用します。コンテキストの再利用が不明瞭な場合は幅を広げます。
  • 境界値は妥当な値に丸めます。≈917–1,143 ではなく ≈800–1,200 を優先します。
  • ステップの範囲を累積範囲に加算します。

隠れた推論トークン、プラットフォーム命令、キャッシュ動作、課金、金銭的コストを決して推測しないでください。ランタイムが使用量を明示的に提供する場合は、推定に混ぜるのではなく、正確なランタイム使用量として別途報告します。

節約を推奨する

チェックポイントごとに最大1つの推奨事項を与えます。観測された最大の回避可能なコストを対象とします。

  • 大きなファイル読み取り: まず検索し、一致するセクションのみを読み取ります。
  • 繰り返しの読み取りまたは検索: 既に取得した結果を再利用します。
  • 広範なツール出力: パス、フィールド、日付範囲、または結果数を絞り込みます。
  • 過大なコンテキスト: 先に進む前に安定した調査結果を要約します。
  • 長い生成出力: 詳細が不要な場合は、よりコンパクトなフォーマットを要求または生成します。
  • 繰り返しの失敗: エラーを検査し、再試行する前にアプローチを変更します。
  • 過剰な例: 比較が必要でない限り、代表的な例を1つ保持します。

トークンを減らすためだけに、検証、セキュリティチェック、必要な証拠、またはユーザーが要求した詳細をスキップすることを推奨しないでください。意味のある節約がない場合は、アドバイスをでっち上げる代わりにその旨を伝えてください。

追跡を終了する

タスクの最終結果の後に短いサマリーを含めます。

トークン推定サマリー
ステップ数: {count} | 合計: ≈{low}–{high} トークン
最大ステップ: {step name} (≈{low}–{high})
アラート間隔: {interval} トークン | 発行アラート数: {count}
最善の次回実行節約: {single highest-impact suggestion}
精度: 推定値です。隠れたシステム、推論、キャッシュ、プラットフォームのオーバーヘッドは除外されています。

チェックポイントとサマリーは、ユーザーの実際のタスクに対して二次的なものに保ちます。

関連スキル