月10万の大学生から半年でここまで来られたのは、Claudeに環境ごと自律させたからです──そしてその環境が、52日間・2340行にわたってコストをすべてゼロと記録しながら、一度も文句を言わずに動き続けていました。

なぜこの仕組みが効くのか

Claude Codeを使い始めた多くの人は、最初は「便利なチャットAI」として使います。でも、月商が一定額を超えると考え方が変わります。AIに「指示して動かす」のではなく、「環境ごと自律させる」という発想への転換です。

違いを具体的に言うと、こうです。前者は毎回自分がプロンプトを打って結果をもらいます。後者は、自分が寝ている間もhookが走り、スクリプトが実行され、ログが積まれています。わたしの場合、launchdで定時実行されるジョブが十数本あり、Claude Code の Stop hook が毎セッション末に走ります。朝起きるとDesktopに前日のブリーフが届いていて、どのセッションがどれだけトークンを消費したかが ~/.claude/metrics/costs.jsonl に記録されている──それが理想形でした。

なぜコスト追跡が必要かというと、Claude Code のMAX契約は月定額ですが「使いすぎると翌月のキャパが実質的に詰まる」という感覚的な上限があります。どのセッションに、どのモデルで、どれだけ消費したかを可視化しておかないと、コスト感覚がない状態で自律エージェントを走らせ続けることになります。自律環境は便利なほどコストを無自覚に食います。だから計測が先決なのです。

Stop hook はこの計測を担う仕組みです。Claude Code は各セッションが終了するとき（ユーザーが /exit したとき、タイムアウトしたとき）に、settings.json の Stop セクションに登録されたコマンドを実行します。そこにコスト集計スクリプトを置けば、「セッション終了 = 自動で記録」というパイプラインが成立します。人間がコストをExcelに手入力するようなことは不要になります。

「動いている」と「正しく動いている」は違う──この感覚、エンジニアならわかると思います。ログが出続けているのに中身が全部ゼロというのは、エラーより始末が悪いです。エラーは気づきやすいですが、ゼロが並ぶログは「正常に記録されている」という外観を保ちながら、内側が完全に空洞です。わたしはそれを52日間、2340行分見落としていました。

コスト集計が「静かに嘘をついていた」根本原因は、Stop hook の stdin に usage や model フィールドが存在しないという単純な事実でした。最初のバージョンは「Stopフックの stdin にはトークン数が入っているはず」という思い込みで書かれていたのです。

全体の流れ

現在の cost-tracker.js（v2）がどういうパイプラインで動くかを先に把握しておくと、後の解説が入りやすくなります。

Claude Code セッション
  │
  │ （セッション終了イベント）
  ▼
Stop hook 起動
  │
  │ stdin に流れてくるペイロード
  │ { session_id, transcript_path, cwd, hook_event_name, ... }
  │   ↑ usage / model は存在しない ← ここが旧バージョンの穴
  ▼
cost-tracker.js
  │
  │ transcript_path を取り出す
  ▼
セッション JSONL ファイル（Claude Codeが書き続けているログ）
  │
  │ 行ごとにパース
  │ { type: "assistant", message: { model, usage: { ... } } }
  ▼
sumUsageFromTranscript()
  │
  │ 全アシスタントターンを走査して
  │ input_tokens / output_tokens / cache_* を累積加算
  ▼
RATE_TABLE でモデル別レートを掛ける
  │
  │ estimatedCostUsd = Σ tokens × rates / 1e6
  ▼
~/.claude/metrics/costs.jsonl に1行追記

ポイントは「Stopフックで信頼できる唯一のデータソースはtranscriptファイル」という設計思想です。stdin ペイロードに直接 usage が来ることを期待するのではなく、Claude Code がセッション中に書き続けている JSONL ファイルを自分で読む。これが v2 への切り替えの核心です。

モデル別レートテーブル

ファイルの34〜38行目に実際のレートが定義されています。

// Approximate per-1M-token billing rates (USD).
// Cache creation: 1.25x input rate. Cache read: 0.1x input rate.
const RATE_TABLE = {
  haiku:  { in: 0.80,  out: 4.0,  cacheWrite: 1.00,  cacheRead: 0.08 },
  sonnet: { in: 3.00,  out: 15.0, cacheWrite: 3.75,  cacheRead: 0.30 },
  opus:   { in: 15.00, out: 75.0, cacheWrite: 18.75, cacheRead: 1.50 }
};

Haiku・Sonnet・Opus の3段階です。getRates() はモデル名の文字列に 'haiku' 'opus' が含まれるかどうかで振り分け、どちらでもなければ Sonnet として扱います。ここはシンプルに文字列マッチで十分で、正規表現を使うほどのものではありません。

キャッシュはコスト計算で意外と効いてきます。cache_creation_input_tokens（初回キャッシュ書き込み）は通常入力の1.25倍、cache_read_input_tokens（2回目以降の読み出し）は0.1倍です。Opus で大量にキャッシュを使えば読み出し単価は実質1.50ドル/100万トークンで、Haiku の通常入力より安くなることもあります。

transcriptを走査する関数

57〜90行目が今回の修正の核心です。

function sumUsageFromTranscript(transcriptPath) {
  let content;
  try {
    content = fs.readFileSync(transcriptPath, 'utf8');
  } catch {
    return null;  // 読めなければ null を返してゼロ扱いにする
  }

  let inputTokens = 0;
  let outputTokens = 0;
  let cacheWriteTokens = 0;
  let cacheReadTokens = 0;
  let model = 'unknown';

  for (const line of content.split('\n')) {
    if (!line.trim()) continue;
    let entry;
    try { entry = JSON.parse(line); } catch { continue; }

    if (entry.type !== 'assistant') continue;  // user/tool行はスキップ
    const msg = entry.message;
    if (!msg || !msg.usage) continue;

    const u = msg.usage;
    inputTokens      += toNumber(u.input_tokens);
    outputTokens     += toNumber(u.output_tokens);
    cacheWriteTokens += toNumber(u.cache_creation_input_tokens);
    cacheReadTokens  += toNumber(u.cache_read_input_tokens);

    if (msg.model && msg.model !== 'unknown') model = msg.model;
  }

  return { inputTokens, outputTokens, cacheWriteTokens, cacheReadTokens, model };
}

行ごとに JSON をパースして type === 'assistant' のエントリだけを取り出し、message.usage を累積加算します。モデル名は最後に見つかったものを使います（セッション途中でモデルが切り替わっても、末尾のアシスタントターンが正しいモデルを持っているという想定です）。

エラー処理は意図的にゆるくなっています。ファイルが読めなければ null、行がパースできなければ continue。どちらの場合も Stop hook 全体を失敗させないようにしてあります。コスト記録が欠けることより、Stop hook がエラーを吐いて Claude Code のセッション終了に影響する方が問題だからです。

stdinの読み取りとフロー全体

100行目から始まる stdin 処理の部分も確認しておきます。

const MAX_STDIN = 64 * 1024;
let raw = '';

process.stdin.setEncoding('utf8');
process.stdin.on('data', chunk => {
  if (raw.length < MAX_STDIN) raw += chunk.substring(0, MAX_STDIN - raw.length);
});

process.stdin.on('end', () => {
  try {
    const input = raw.trim() ? JSON.parse(raw) : {};

    const transcriptPath = (typeof input.transcript_path === 'string' && input.transcript_path)
      ? input.transcript_path
      : process.env.CLAUDE_TRANSCRIPT_PATH || null;

    // ...
    let usageTotals = null;
    if (transcriptPath && fs.existsSync(transcriptPath)) {
      usageTotals = sumUsageFromTranscript(transcriptPath);
    }
  } catch {
    // Non-blocking — never fail the Stop hook.
  }

  process.stdout.write(raw);  // ECC hook convention: stdin をそのまま stdout に流す
});

stdin から受け取るのは最大64KBです。Claude Code の Stop hook ペイロード自体は数百バイト程度なのでこれで十分ですが、上限を設けておくことで巨大な入力が流れ込んでも詰まらない設計にしてあります。

transcript_path の取り出しは二段構えで、stdin の JSON にあればそれを使い、なければ環境変数 CLAUDE_TRANSCRIPT_PATH にフォールバックします。どちらもない場合は null になり、usageTotals は null のままなのでトークン数は全部 0 として記録されます──これは旧バージョンと同じ結果ですが、意図的なゼロです。フォールバック先が存在するため、ファイルパスが取れる通常ケースでは必ず transcript が読まれます。

最後の process.stdout.write(raw) は ECC hook の規約に従ったものです。Stop hook は stdin を stdout に流すことで次のフックにデータを渡せるようになっており、このスクリプトはコスト集計を副作用として行いながら、ペイロードをそのまま透過させます。

1セッション1行の累積設計

コメントの20〜22行目に書かれた挙動が地味に重要です。

// Cumulative behavior: Stop fires per assistant response, not per session.
// Each row therefore represents the cumulative session total up to that point.
// To get per-session cost, take the last row per session_id.

Stop hook はアシスタントターンごとに発火します。つまり、1セッションで10回アシスタントが応答すれば costs.jsonl に10行追記されます。各行はその時点までのセッション累積トークン数なので、「1セッションのコスト」を取り出したければ同じ session_id の行群のうち最後の1行を使います。日次集計なら session_id でグルーピングして末尾行を取り、それらを date でまとめる形になります。

この設計はシンプルですが、途中クラッシュした場合でも最後に記録された行まで使えるという耐障害性があります。セッションが正常終了しなくても、その時点までの累積は残ります。

実装の詳細

toNumber() ── 「型が合わない」を黙って吸収する関数

前半で紹介した sumUsageFromTranscript() の中で、すべての加算が toNumber(v) を通っています（47〜50行目）。

function toNumber(v) {
  const n = Number(v);
  return Number.isFinite(n) ? n : 0;
}

たった3行ですが、これがなければ事故が起きます。Claude Code の JSONL には、フィールドが欠落している行、null が入っている行、稀にキャッシュ関連フィールドが文字列として入っている行が混在します。Number(null) は 0 になりますが、Number(undefined) も Number(null) も NaN + 正常値 = NaN になります。一箇所でも NaN が混入すると累積合計全体が NaN になり、最終的なコスト推計が NaN として JSONL に書かれます。後から集計スクリプトを書いたとき、NaN の行が混じっていると合計が壊れます。

Number.isFinite() を使っているのは isNaN() より厳密だからです。isNaN(Infinity) は false を返します。コスト計算に Infinity が入れば合計が壊れるので、isFinite でまとめて弾いています。

「防御的すぎる」と感じるかもしれませんが、Stop hook は毎セッション末に無人で走るものです。人間がその都度確認するわけではないので、想定外の入力を受け取ったときに静かにゼロとして扱い、ログ全体を壊さないことの方が重要です。

session_id の三重フォールバック

108〜112行目の sessionId の取り出し方を見てください。

const sessionId =
  sanitizeSessionId(input.session_id) ||
  sanitizeSessionId(process.env.ECC_SESSION_ID) ||
  sanitizeSessionId(process.env.CLAUDE_SESSION_ID) ||
  'default';

三段階のフォールバックがあります。なぜこうなっているかというと、Stop hook の実行環境がセッションの文脈によって少しずつ違うからです。

Claude Code が直接起動したセッションでは input.session_id が正常に来ます。ですが、launchd から呼ばれるラッパースクリプト経由でセッションを起動した場合や、テスト目的で hook を単体実行する場合は、stdin ペイロードが省略されたり別形式になることがあります。ECC_SESSION_ID と CLAUDE_SESSION_ID は、そういったケースに備えて環境変数として渡せるようにしてあります。

sanitizeSessionId() は session-bridge.js からインポートした関数で、英数字とハイフン・アンダースコア以外を除去してパス等に安全に使えるようにサニタイズします。Stop hook 経由でファイルに書かれるセッション ID はそのまま costs.jsonl の行に入るため、改行やスラッシュが混入すると後の集計スクリプトが壊れます。

最後の 'default' フォールバックは「どこからもセッション ID が取れなかった」という最悪ケースです。この場合、複数のセッションが全部 session_id: "default" として記録されてしまい、セッション単位の集計が意味をなさなくなります。実際にこのパスに落ちたら異常事態なので、後述するデバッグの際に「default という ID の行が溜まっている」という現象が手がかりになることがあります。

コスト計算の精度と Math.round() の意図

128〜133行目のコスト計算の書き方はやや特徴的です。

const estimatedCostUsd = Math.round((
  (inputTokens      / 1e6) * rates.in +
  (outputTokens     / 1e6) * rates.out +
  (cacheWriteTokens / 1e6) * rates.cacheWrite +
  (cacheReadTokens  / 1e6) * rates.cacheRead
) * 1e6) / 1e6;

* 1e6 してから Math.round() し、また / 1e6 で戻しています。これは浮動小数点の丸め誤差を小数点以下6桁で抑えるためです。

JavaScript の Number は IEEE 754 倍精度浮動小数点なので、0.1 + 0.2 === 0.3 が false になるのと同じ理由で、複数のレートを掛け合わせた累積に丸め誤差が乗ります。0.000003000000000000001 のような値が JSONL に入っても人間には読みにくく、後で集計するときも誤差が気になります。

小数点以下6桁に丸めているのは「USD で1マイクロドル未満の精度は不要」という判断です。Haiku のインプット単価は 0.80 ドル/百万トークンなので、1万トークン処理したとして0.008ドル、1000トークンなら0.0008ドルです。6桁あれば十分なコスト感覚が掴めます。

appendFile と JSONL 形式の設計判断

150行目の書き出しはシンプルです。

appendFile(path.join(metricsDir, 'costs.jsonl'), `${JSON.stringify(row)}\n`);

JSONL（JSON Lines）を選んでいる理由は、追記が安全にできるからです。JSON 配列ファイルに追記しようとすると、末尾の ] を書き換えなければならないため、書き込み途中でプロセスが死んだらファイル全体が壊れます。JSONL は「1行 = 1オブジェクト」の形式なので、追記は末尾に1行足すだけです。途中でプロセスが落ちても既存の行は無事です。

Stop hook は Claude Code の終了シーケンスの中で走るため、書き込み中に強制終了されるリスクがゼロではありません。そういう状況でもデータが最小限の損失で済む形式を選んでいます。

ensureDir(metricsDir) は ~/.claude/metrics/ が存在しなければ作るユーティリティです。Stop hook を初めて実行するときにディレクトリが存在しないと appendFile が失敗するため、毎回チェックしています。fs.mkdirSync(path, { recursive: true }) のラッパーで、ディレクトリが存在する場合は何もしません。

process.stdout.write(raw) ── パイプラインを壊さないための規約

最後の1行（156行目）の意味を前半で触れましたが、もう少し掘り下げます。

process.stdout.write(raw);

ECC（Enhanced Claude Code）のフック規約では、Stop hook は stdin を stdout にそのまま流すことが求められています。これは複数の Stop hook を直列に繋ぐためです。

Claude Code の settings.json では Stop セクションに複数のコマンドを並べられます。この場合、各コマンドが stdin を受け取り、stdout に流すことで次のコマンドがそのデータを受け取れます。コスト追跡 hook が途中でデータを飲み込んでしまうと、後続の hook（例えばセルフ監査 hook）がペイロードを受け取れなくなります。

cost-tracker.js はコスト集計を副作用として行い、パイプライン上の透過的な中継点として振る舞います。このため、エラーが起きても catch {} でスキップして最後に必ず process.stdout.write(raw) まで到達するようになっています。コスト記録が欠けることより、パイプラインが途切れることの方が影響が大きいからです。

私が詰まった話

52日間気づかなかった理由

~/.claude/metrics/costs.jsonl のゼロ記録に気づいたのは、週次レポートを生成しようとして集計スクリプトを走らせたときです。52日分の JSONL を集計すると、2340行すべての estimated_cost_usd が 0 でした。

最初は「無料枠で動いているから当然では？」と思いました。Claude Code の MAX 契約はトークン課金ではなく月定額なので、コストが0なのは正しいとも言えます。ですが、input_tokens まで全行 0 なのはおかしい。実際に何千回もアシスタントが応答しているのに、トークン数が記録されていないはずがありません。

問題はログが「エラーなく動いていた」ことです。hook の実行は毎セッション正常に完了していました。costs.jsonl にはちゃんと行が追記され続けていました。タイムスタンプも正しい。ただ、数値フィールドが全部ゼロでした。

「動いているように見えるが中身が空洞」──これが一番発見を遅らせる障害パターンです。エラーログがあれば即座に気づけます。サイレントな誤動作は、意識的にデータを確認するまで存在しません。

v1 の何がまずかったか

旧バージョンのコードは手元に残っていませんが、動作から逆算すると構造は明らかです。Stop hook の stdin ペイロードを受け取り、そこから直接 usage や model を取り出そうとしていました。

// v1 の想定（実際は存在しないフィールド）
const { usage, model, session_id } = JSON.parse(raw);
const inputTokens = usage?.input_tokens ?? 0;

Stop hook の stdin に来る実際のペイロードは settings.json のコメント（9〜10行目）に書いてある通りで、usage も model も含まれていません。

{ session_id, transcript_path, cwd, hook_event_name, ... }

usage?.input_tokens はオプショナルチェーンなので undefined が返り、?? 0 でゼロになります。エラーは一切発生せず、ただ毎回ゼロが記録されます。

わたしが見落としていた前提は「Stop hook の stdin にはセッション全体のコスト情報が集約されて入っている」という思い込みでした。実際はそうではありません。Stop hook のペイロードはセッション管理に必要な最小限の情報だけで、具体的なトークン使用量はトランスクリプトファイルを読まなければ取れません。Claude Code の公式ドキュメントにも明示的な記述がなく、この挙動はトランスクリプトを実際に読んで確かめるまでわかりませんでした。

transcript_path が取れないときの沼

v2 に書き直した後、別の詰まりがありました。ローカル環境では正常に動いているのに、launchd 経由で起動したセッションの hook がゼロのまま記録される行が散発的に混じるのです。

調べると、transcriptPath && fs.existsSync(transcriptPath) の条件が false になっているケースがありました。原因は2つありました。

1つ目は PATH の問題です。 launchd の環境変数 PATH は /usr/bin:/bin:/usr/sbin:/sbin が基本で、Node.js のある /opt/homebrew/bin や nvm 配下が含まれません。cost-tracker.js は Node.js スクリプトなので、PATH が正しくないと hook そのものが起動せず、Claude Code が fallback としてペイロードをそのまま流す挙動になります。この場合 costs.jsonl には何も書かれないため、行数が少ない日 = hook が動いていない日、という形で検出できます。plist に PATH を明示的に設定することで解消しました。

2つ目は transcript_path の絶対パス問題です。 Claude Code がセッション JSONL ファイルを書くパスは ~/.claude/projects/ 以下の固定位置ですが、transcript_path フィールドに入ってくる文字列が環境によっては相対パスになっているケースがありました。fs.existsSync は相対パスをカレントディレクトリ基準で解決するため、launchd から起動した場合の CWD（通常 /）で展開されると当然ファイルは見つかりません。

修正は transcript_path を受け取ったら path.resolve(transcript_path) で絶対化することです。ただ、現在の v2 コードを見ると path.resolve() は入っていません。実際に問題が再現した環境でのみ相対パスが来ており、通常の Claude Code セッションでは絶対パスが来るため、リスクは限定的と判断して対応を保留しています。もし「launchd 経由でのみゼロ記録が散発する」という症状が出たら、まずここを疑うのが近道です。

null 返しが「透明なゼロ」になる問題

sumUsageFromTranscript() は読み取りに失敗すると null を返します（62行目の return null）。呼び出し側の 125行目でこう展開されます。

const {
  inputTokens = 0,
  outputTokens = 0,
  // ...
} = usageTotals || {};

null が来ると {} に展開され、すべてのデフォルト値 0 が使われます。結果として、「transcript が読めなかった行」と「transcript を読んだが本当にトークンがゼロだった行（ほぼありえない）」が、costs.jsonl 上では区別できません。

これが判明したのは、「ある日の記録が妙に少ない」というときに手動で costs.jsonl を開いて確認したときです。transcript_path: "" という行が混じっていました。transcript_path が空文字のとき、fs.existsSync("") は false を返すため sumUsageFromTranscript() が呼ばれず、usageTotals は null のまま、結果ゼロ記録になります。

根本原因は session_id が取れていても transcript_path が取れないケースがあるということです。v2 コードの 141行目に transcript_path: transcriptPath || '' とあるので、パスが取れないときは空文字が記録されます。後から集計スクリプトで transcript_path が空の行を除外するか、estimated_cost_usd === 0 && input_tokens === 0 && transcript_path === "" の条件でゼロ記録を「データなし」として扱うことで対処しています。

「累積設計」を知らずにコストを7倍に計算した話

v2 が正しく動き始めた後、日次コスト集計スクリプトを書いたときにまた詰まりました。1日のコストを出そうとして全行を単純合計すると、実際の感覚より何倍も多い数字が出ました。

コメントの 19〜21 行目（前半で引用）を読み直して「あ、累積設計だ」と気づきました。Stop hook はアシスタントターンごとに発火するため、1セッションで 10 回応答があれば 10 行が追記され、それぞれが「1回目まで」「2回目まで」という累積トークン数を持っています。全行を足すと、1ターン目のトークンが10回分、2ターン目のトークンが9回分…と二重三重に計上されます。

正しい集計の書き方は、同じ session_id の行をグループ化して、各グループの最後の1行だけを取ることです。

const sessions = {};
for (const line of lines) {
  const row = JSON.parse(line);
  sessions[row.session_id] = row;  // 後から来る行で上書きされる
}
const dailyCost = Object.values(sessions)
  .filter(r => r.timestamp.startsWith('2026-07-08'))
  .reduce((sum, r) => sum + r.estimated_cost_usd, 0);

このバグを入れた状態で「1日のコスト」を計算すると、セッション内の応答回数が多いほど数字が膨らみます。10回応答するセッションは1回応答するセッションの約10倍の「見かけのコスト」になりますが、実際には同じモデルを使っているはずなのに数字に大きなばらつきが出る形で気づきました。

「データは正しく記録されているがレポートが嘘をついている」── これも、エラーなく動いているように見える沼のひとつです。集計ロジックを書くときは、サンプルデータを手動で確認してから実装するのが確実です。わたしの場合、session_id が同じ行を grep で抜き出して目視するまで、設計の意図に気づきませんでした。

デバッグに使えるワンライナー

詰まったときに手元でよく使ったコマンドを残しておきます。

ゼロ記録の行数を確認する:

node -e "
const fs = require('fs');
const lines = fs.readFileSync(process.env.HOME + '/.claude/metrics/costs.jsonl','utf8')
  .split('\n').filter(Boolean).map(JSON.parse);
const zeros = lines.filter(r => r.input_tokens === 0);
console.log('total:', lines.length, 'zeros:', zeros.length);
"

transcript_pathが空の行を探す:

node -e "
const fs = require('fs');
const lines = fs.readFileSync(process.env.HOME + '/.claude/metrics/costs.jsonl','utf8')
  .split('\n').filter(Boolean).map(JSON.parse);
lines.filter(r => !r.transcript_path).forEach(r => console.log(r.timestamp, r.session_id));
"

v2 に切り替えた後に上記を実行したとき、1行目のコマンドで zeros: 0 が出ればすべての記録にトークン数が入っています。ゼロが残っている場合は、transcript_path の取得に問題があるか、フォールバックパスに落ちているケースです。

52日分のゼロ記録を捨てるしかなかったのは痛かったですが、v2 に切り替えてからは毎セッション正確なトークン数が積まれています。自律環境のコスト感覚を持てるようになって初めて、「どの作業が消費が多く、どこを効率化すべきか」という議論ができるようになりました。ゼロが並ぶログは「動いている証拠」ではなく「何も記録していない証拠」です──そのことを、2340行かけて学びました。

つまずきポイント

前段で紹介した「52日ゼロ記録」「cumulative設計の誤集計」「launchd PATH欠落」のほかにも、Stop hookを実運用していると詰まる場所はいくつかあります。ここでは網羅的に列挙します。

① モデル名が将来マッチしなくなる

getRates() は文字列に 'haiku' 'opus' が含まれるかどうかで振り分け、それ以外は Sonnet として扱います。現行のモデル命名規則（claude-haiku-4-5-20251001 など）ではこれで十分ですが、将来 Anthropic がファミリー名を変更したとき（たとえば haiku 系列に別称がつく、など）、マッチが外れてすべてが Sonnet レートになります。エラーは出ず、レートだけ静かにずれます。定期的にコードと最新モデル名を照合する運用か、マッチ失敗時にログを残す分岐を入れておくのが安全です。

② Stop hookが発火しないケース

Claude Code がプロセスを SIGKILL で強制終了された場合（システムOOMやバッテリー切れなど）、Stop hookは実行されません。正常な /exit とタイムアウトでは発火しますが、強制終了はセッション終了シーケンスをスキップするため、そのセッション分の記録が丸ごと欠落します。月間コスト集計の誤差を気にするなら「記録がない = ゼロではなくデータ欠損」という解釈を集計スクリプト側に入れておく必要があります。具体的には、セッション数と行数の比率を監視して「期待行数より著しく少ない日」をアラートの対象にする方法があります。

③ 長大トランスクリプトの同期読み込みブロッキング

sumUsageFromTranscript() は fs.readFileSync() を使っています。Claude Code の長いセッション（数十ターン以上の複雑な実装タスク）では、トランスクリプト JSONL が数十MB になることがあります。readFileSync は同期呼び出しなので、その間 Node.js のイベントループが止まります。Stop hook 自体は単発実行なのでイベントループが止まっても問題はありませんが、読み込みに2〜3秒かかると Claude Code のセッション終了レスポンスが遅れる形として体感されます。実測で問題になった場合は、ストリームで先頭から行単位に読む実装に切り替えることで、ファイル全体を一度にメモリに載せるのを避けられます。

④ hook chain でのstdin競合

Stop セクションに複数の hook を登録した場合、各 hook は直列に実行され、前の hook の stdout が次の hook の stdin になります。cost-tracker.js の最後の process.stdout.write(raw) は、この規約を守るためのものです。もし chain の途中に process.exit(0) を呼ぶ hook が割り込むか、stdout に raw 以外のデータを流す hook が存在すると、後続の hook がペイロードを正しく受け取れなくなります。chain の各 hook を書くときは「stdin を受け取り、stdout にそのまま流す」形を徹底する必要があります。cost-tracker に限らず、Stop hook 全般に言える規律です。

⑤ costs.jsonl の肥大化

Stop hook はアシスタントターンごとに発火し、1行追記します。1日10セッションで平均20ターンなら、1日200行が積まれます。1年継続すると7万行を超えます。costs.jsonl 自体は各行が数百バイト程度なのでストレージはさほど問題になりませんが、後から書く集計スクリプトが全行を読む構造だと、時間が経つほどスキャン時間が増えます。定期的に古い行を年次ファイルにアーカイブする運用か、集計クエリを「直近N日だけスキャン」する形にしておくと長期運用が楽です。

⑥ タイムゾーン問題

new Date().toISOString() が書く timestamp は UTC です。日次集計を JST 基準でやりたい場合、2026-07-09T00:30:00.000Z という行は JST では7月9日ですが、UTC では7月8日のカウントになります。日をまたぐ深夜のセッションで集計日付がずれる現象として現れます。修正は timestamp を取り出すときに +9h して JST の日付文字列に変換することですが、JSONL に入っている値は UTC のままにしておき、集計時に変換する方が一貫性を保てます。JSONL の値を JST で書き直すと、後から UTC ベースに戻したくなったときに元データが失われます。

⑦ 書き込み中トランスクリプトの読み込みタイミング

Claude Code がアシスタントターンを書いている最中に Stop hook が走るエッジケースがあります（非常に短いターンの応答後など）。このとき、トランスクリプト JSONL の末尾行が不完全な JSON で終わっている可能性があります。sumUsageFromTranscript() のパース部分は try { entry = JSON.parse(line); } catch { continue; } で行単位に処理するので、壊れた末尾行は continue でスキップされます。結果として、その行分のトークンが集計されない（直前の正常行まで集計される）という挙動になります。実際にこれが問題になることはほぼありませんが、「コストが微妙に少なく記録される」ことの一因にはなりえます。

⑧ session_id重複と 'default' フォールバック

前段で触れた通り、session_id がどこからも取れない場合は 'default' という固定値になります。もし複数の Claude Code インスタンスが同時に動いていて（launchd ジョブが並走するケースなど）、それぞれが 'default' として記録されると、cumulative 設計の「session_id でグループ化して最後の1行を使う」集計が崩れます。'default' でグループされた行群のうち最後の1行だけが使われ、それが最も小さいセッション分だったり最も大きい分だったりと、結果が不定になります。session_id: "default" の行を定期的に grep で確認して、発生頻度を把握しておくことをおすすめします。

⑨ require() と Node.js バージョンの不一致

cost-tracker.js は CommonJS（'use strict'; const fs = require('fs');）で書かれています。nvm で Node.js のバージョンを上げた直後や、依存ライブラリが ESM 専用に移行した場合、require() で ESM モジュールをロードしようとして ERR_REQUIRE_ESM エラーが出ます。このエラーは hook 実行時に Node.js が stderr に吐きますが、Claude Code の通常出力には現れません。hook が静かに失敗して costs.jsonl に何も書かれない形になるため、「ゼロ記録」と区別がつきません。node --version と依存関係の ESM 対応状況を Node.js アップグレード時に必ず確認する必要があります。

ベストプラクティス

52日間の失敗と、そこからの v2 への書き直し、その後の細かい詰まりを経て、Stop hook でコスト追跡をする際のベストプラクティスとしてまとめられるものは次の通りです。

① Stopフックで信頼できるデータソースはtranscriptファイルだけ

最も重要な教訓です。stdin ペイロードにはトークン使用量は入っていません。transcript_path を受け取り、セッション JSONL を自分で読む。この設計に気づくまでの52日が、この記事全体の背景にある事実です。何かを計測しようとするなら、まずそのデータがどこにあるかを確認する。「あるはずだ」という前提でコードを書くと、サイレントに嘘をつくツールができあがります。

② Stop hookは絶対に失敗させない

コスト記録が欠けることよりも、Stop hook がエラーを吐いて Claude Code のセッション終了シーケンスに影響する方が問題です。メイン処理全体を try { ... } catch { } で包み、エラーが起きても process.stdout.write(raw) まで必ず到達する設計にする。cost-tracker.js の151〜156行がそのパターンです。「ログが欠ける日があってもいい、セッションが壊れてはいけない」という優先順位の判断です。

③ stdin → stdout の透過パターンを守る

chain 内の全 hook が stdin を受けて stdout に流す という規約を守れば、任意の数の hook を直列に繋げます。この規約を破ると、後続の hook が静かに動かなくなります。hook を書くときは機能実装を副作用に留め、パイプラインへの影響を最小化する発想が大切です。

④ 型変換は toNumber() で防御的に一元化する

外部データ（トランスクリプト JSONL）から読んだ値を直接算術演算に使わない。NaN が一箇所でも累積合計に混入すると、その集計全体が NaN になります。Number.isFinite() を使って NaN と Infinity を両方弾く関数を一個置いておく。3行で書けて、数週間後の自分を助けます。

⑤ 追記ファイルはJSONLで書く

JSON 配列ではなく JSON Lines（1行1オブジェクト）を選ぶ理由はシンプルです。JSON 配列への追記はファイル末尾を書き換えるため、途中でプロセスが落ちるとファイル全体が壊れます。JSONL なら追記は末尾に1行足すだけ。Stop hook は Claude Code の終了シーケンス中で動くため、書き込み中に強制終了されるリスクがゼロではありません。JSONL はその状況でも最小限の損失で済む形式です。

⑥ 集計はsession_id最終行を使う

Stop hook はターンごとに発火するため、1セッションが複数行になります。全行を単純合計するとコストが何倍にも膨らみます。集計は session_id でグループ化し、各グループの最後の1行だけを使う。この設計はコメント（cost-tracker.js の19〜21行目）に明記されていますが、コードを読まずに集計スクリプトを書くと必ず踏む穴です。

const sessions = {};
for (const line of lines) {
  const row = JSON.parse(line);
  sessions[row.session_id] = row;  // 後の行で上書き → 自動的に最終行が残る
}

⑦ launchd plistにPATHを明示する

launchd の実行環境は /usr/bin:/bin:/usr/sbin:/sbin が基本 PATH で、Node.js が /opt/homebrew/bin にある場合も nvm 配下にある場合も、PATH が通っていなければ hook が起動しません。静かに失敗して costs.jsonl に何も書かれない形になります。plist に <key>EnvironmentVariables</key> で PATH を明示し、Node.js の実パスを含めておく。この対処は launchd で動く全スクリプトに共通の基本です。

⑧ metricsディレクトリを毎回 ensureDir で作る

~/.claude/metrics/ が存在しない状態で appendFile を呼ぶとエラーになります。hook を初めてセットアップした直後や、ディレクトリを誤って消した場合に発生します。fs.mkdirSync(path, { recursive: true }) のラッパーを毎回呼ぶ。ディレクトリが存在すれば何もしないので、オーバーヘッドはほぼゼロです。「あって当然」のディレクトリを前提にしたコードは、環境が変わると静かに壊れます。

⑨ stdin に上限を設ける

const MAX_STDIN = 64 * 1024;
if (raw.length < MAX_STDIN) raw += chunk.substring(0, MAX_STDIN - raw.length);

Stop hook のペイロード自体は数百バイトですが、上限なしに読むと何らかの異常で巨大な入力が流れ込んだとき Node.js のヒープを圧迫します。64KB を上限にすることで、通常ケースには影響なく、異常ケースで詰まらない設計になります。

⑩ session_id はサニタイズしてから使う

セッション ID をそのままファイルに書くと、将来そのフィールドでファイル名を作ったりパスに組み込んだりするときにインジェクションリスクが生じます。英数字・ハイフン・アンダースコア以外を除去するサニタイズを一枚かましておく。sanitizeSessionId() を session-bridge.js に切り出しているのは、同じロジックが複数 hook で使われるためです。共通ロジックは lib/ に置いて import する。手抜きで重複コピーしないことが、後の保守コストを下げます。

⑪ 相対パスはpath.resolve()で絶対化する

fs.existsSync(transcriptPath) は相対パスをカレントディレクトリ基準で解決します。launchd から起動した場合の CWD は通常 / なので、相対パスが来ると意図しない場所を参照します。transcript_path を受け取った直後に path.resolve(transcriptPath) で絶対化する一行を入れておくと、起動元に依存しない動作になります。現行の v2 ではこの処理が省かれており、通常の Claude Code セッションでは問題ないですが、launchd 経由での散発的なゼロ記録が気になる場合は最初に疑う箇所です。

⑫ タイムゾーンはUTCで記録・変換は集計時に行う

JSONL の timestamp は new Date().toISOString()（UTC）で記録し、JST への変換は集計スクリプト側でやる。元データを特定タイムゾーンで書き直すと「元に戻せない」状況が生まれます。UTC で保存しておけば後から任意のタイムゾーンに変換できます。日次集計を JST 基準でやるなら new Date(timestamp).toLocaleDateString('ja-JP', { timeZone: 'Asia/Tokyo' }) で変換する集計関数を一本書けば済みます。

⑬ 「ゼロ記録」と「データなし」を区別する

transcript_path が空文字の行と、transcript が読めて本当にトークンゼロだった行は、現行の JSONL では区別できません。集計スクリプトで「estimated_cost_usd === 0 && input_tokens === 0 && transcript_path === ''」の組み合わせを「データなし」として除外すると、ゼロが混じった日の集計精度が上がります。サイレントなゼロを信頼するより、「これはデータがない行だ」と明示的にラベルできる構造にする方が、長期運用で正確な感覚を保てます。

まとめ

Stop hook に usage や model が来ると思って書いたコードが、52日間・2340行にわたって全行ゼロを吐き続けた──これは「動いているように見える」という状態の怖さを体感した経験でした。エラーが出ていれば翌日には気づけたはずです。サイレントに嘘をつくバグは、意識的にデータを確認するまで存在が見えません。

v2 への修正の核心は一行です。「stdin から usage を読む」のをやめて、「stdin から transcript_path を読み、そのファイルを自分で読む」に変えた。それだけで52日分の空洞が埋まりました。

Stopフックで信頼できる唯一のデータソースはtranscriptファイル──この教訓は Claude Code に限らず、「フックやイベントのペイロードに欲しいデータが入っているはずだ」という前提で自動化を書くすべての場面に通じます。ペイロードの仕様を確認せずに書き始めると、自分でデータを読みに行かなければいけない場合に静かに壊れるコードができあがります。

自律環境の精度は、計測の精度に依存します。コストが正しく記録されるまで、「どのセッションが重く、どこを削れるか」という議論は成立しません。コスト追跡は環境構築の最後ではなく、最初に確かめるべき基盤です。

仕組みの全体像・月120万の内訳・30日手順は有料noteにまとめています。
📕 Claude Code自律環境で、実際どう稼ぐか ― 仕組み・実例・始め方・サポート

Lily（@bokuwalily）― 個人開発者。Claude Code で自動化基盤を組みながら、iOSアプリやWebサービスを量産しています

制作物・記事は bokuwalily.com にまとめています🖥️
AIで「寝てても回る仕組み」を作って月120万にした話は noteの有料記事に💰
OSS: github.com/bokuwalily 🐙
最新情報・お問い合わせは X @bokuwalily へ🌍

皆さんの ❤️ やシェアが励みになります！