呼ばれていないエージェントを炙り出す ― Stop hookで使用率ログを取ってゾンビを刈る

前回、ターミナルをタイル状に自動配置する話を書きました。今回は環境の中身の話に戻ります ―― ~/.claude/agents/ にサブエージェントを何本も定義してきましたが、実際に呼ばれているのはそのうち何本か、誰も数えていませんでした。この記事は、Stop hookで呼び出しをログに落とし、7d/30d窓で集計して「定義したのに一度も呼ばれていないエージェント」を機械で炙り出す仕組みの話です。

困りごと：エージェントは定義した瞬間から見えなくなる

~/.claude/agents/*.md にサブエージェントを追加するのは簡単です。frontmatterを書いてmarkdownを置くだけ。問題はその後で、呼ばれているかどうかを確認する手段がないことでした。Claude Codeのセッション内でTaskツール（サブエージェント起動）が呼ばれても、その記録はセッションのtranscriptに埋もれたまま消えていきます。

結果、architect や planner のような「あると便利そうだから作った」系のエージェントが、実際には一度も起動されずにagents/ディレクトリに居座り続けます。数が増えるほど、どれが生きていてどれが死んでいるか判別できなくなる ―― これは前々回書いた自己増殖するスキルと同じ問題の、エージェント版です。

記録層：Stop hookでtranscriptからAgent呼び出しを拾う

セッション終了時に走るstop_agent_tracker.shが、そのセッションのtranscript.jsonlを読んで呼び出しを1行ずつJSONLに落とします。

for b in content:
    btype = b.get("type")
    if btype == "tool_use" and b.get("name") == "Agent":
        inp = b.get("input") or {}
        if "subagent_type" not in inp:
            continue
        uid = b.get("id")
        uses[uid] = (ts, b.get("name"), inp, b.get("caller"))
    elif btype == "tool_result":
        rid = b.get("tool_use_id")
        results[rid] = (ts, bool(b.get("is_error")))

ここで非自明なのが、コメントにも書いてある通り「Claude Code のtranscriptでは『Task』ツールは name="Agent" として記録される」という点です。ツール名の表記ゆれを知らずにフィルタを書くと、何も拾えずに空振りします。

tool_useとtool_resultをidで突き合わせて所要時間を出し、セッション内で既に記録済みのtool_use_idは重複書き込みしない設計です（同一セッションでStop hookが複数回走っても二重記録しない）。

rec = {
    "ts": use_ts, "session_id": sid, "cwd": cwd,
    "tool_use_id": uid, "subagent_type": subagent_type,
    "description": description, "duration_ms": duration_ms,
    "status": status, "caller": caller,
}
out.write(json.dumps(rec, ensure_ascii=False) + "\n")

出力先は~/.claude/logs/agent-invocations.jsonl。今実測すると665行、最古のレコードは2026-05-28まで遡ります。

集計層：7d/30d窓でTop10と0回一覧を出す

agent-usage-summary.shがこのログを読み、指定した窓（デフォルト7d）でTop10と「定義されているのに0回」のエージェント一覧を出します。0回判定の母集団は~/.claude/agents/*.mdのファイル名です。

known_agents = set()
for fp in glob.glob(os.path.join(agents_dir, "*.md")):
    known_agents.add(os.path.splitext(os.path.basename(fp))[0])

for w in windows:
    cutoff = now - td
    recent = [r for r in records if r["_dt"] >= cutoff]
    counts = Counter(r.get("subagent_type", "") for r in recent if r.get("subagent_type"))
    used = set(counts.keys())
    unused = sorted(known_agents - used)

実際にlaunchdの日次ジョブが吐いた最新レポート（2026-08-08 10:15実行分）がこれです。

=== Agent usage (last 7d) ===
total invocations: 16  unique types: 3
  Explore                                      12       0
  general-purpose                               3       0
  code-reviewer                                 1       0

0-call agents (defined locally but not used in 7d): 7
  - INDEX / architect / database-reviewer / planner
  - python-reviewer / security-reviewer / typescript-reviewer

=== Agent usage (last 30d) ===
total invocations: 200  unique types: 7
  general-purpose                             117
  Explore                                       74
  reviewer                                       3
  Content Creator                                2
  fork                                           2
  security-reviewer                              1
  code-reviewer                                  1

0-call agents (defined locally but not used in 30d): 6
  - INDEX / architect / database-reviewer / planner
  - python-reviewer / typescript-reviewer

30日窓で見ると、~/.claude/agents/に定義された実質7本のエージェント（INDEXはファイルであってエージェントではない、後述）のうち5本が0回でした。general-purposeとExploreだけで全呼び出しの95%を占め、architect・database-reviewer・planner・python-reviewer・typescript-reviewerは定義されているだけで一度も選ばれていません。

索引の自動再生成：agents-index.sh

集計と対になっているのがagents-index.shです。こちらは呼び出し実績ではなく、~/.claude/agents/*.mdのfrontmatterを集約してINDEX.mdを機械生成します。

def load_frontmatter(path: pathlib.Path):
    text = path.read_text(encoding="utf-8", errors="replace")
    m = re.match(r"^---\n(.*?)\n---\n", text, flags=re.DOTALL)
    if not m:
        return None, "missing frontmatter"
    ...

for p in sorted(pathlib.Path(agents_dir).glob("*.md")):
    if p.name == "INDEX.md":
        continue
    fm, err = load_frontmatter(p)
    if not fm.get("name"):
        warnings.append(f"{p.name}: missing 'name'")

nameやdescriptionが欠けているエージェント定義は## ⚠️ Validation warningsとしてINDEX.mdの末尾に出ます。PyYAML依存を避けて1階層のkey: valueだけを拾う簡易パーサにしているので、複雑なfrontmatterは書けませんが、その分依存が要らず壊れにくいです。

見つけた炙り出し：集計スクリプト自身がゾンビを1本作っていた

2つのスクリプトを読み比べていて気づいたのが、agents-index.shはif p.name == "INDEX.md": continueと明示的に自分の生成物を除外しているのに、agent-usage-summary.shのknown_agents収集にはこの除外がないことです。

# agent-usage-summary.sh 側（除外なし）
for fp in glob.glob(os.path.join(agents_dir, "*.md")):
    known_agents.add(os.path.splitext(os.path.basename(fp))[0])

結果、agents-index.shが生成したINDEX.md自体が「定義されているのに0回呼ばれていないエージェント」として毎回レポートに混入します。実害はレポートの末尾に無意味な1行が増えるだけですが、2つの集計ロジックが同じ*.mdグロブに依存しながら、片方だけ自分の生成物を除外し忘れるという、この手のペア運用にありがちな不整合の実例です。

launchdでの日次配信

配信はcom.shun.agent-usage-dailyが担当します。

<key>ProgramArguments</key>
<array>
    <string>/bin/zsh</string>
    <string>-c</string>
    <string>~/.claude/scripts/agent-usage-summary.sh 7d 30d &gt; ~/.claude/logs/agent-usage-latest.md 2&gt;&amp;1</string>
</array>
<key>StartCalendarInterval</key>
<dict>
    <key>Hour</key><integer>10</integer>
    <key>Minute</key><integer>15</integer>
</dict>

毎朝10:15に7dと30dを両方回してagent-usage-latest.mdに上書き。LowPriorityIOとNice 10を付けて、他の作業を邪魔しないバックグラウンド扱いにしています。集計自体はログをPythonでメモリに載せて回すだけの軽い処理なので、優先度を下げても待たされることはありません。

運用して分かったこと

• 上位2本（general-purpose・Explore）で30日間の呼び出しの95.5%（191/200）を占める。 ロングテールはreviewer3回・Content Creator2回・fork2回・security-reviewer1回・code-reviewer1回と、1桁の実績しかありません。
• 専門特化エージェントほど呼ばれない。 python-reviewerやtypescript-reviewerのような言語特化型、architect・plannerのような設計特化型が軒並み0回でした。用途を絞ったエージェントを作るときの見積もりが甘かった、というより「言語系タスクを振る導線自体が今の作業内容に存在しない」が実情に近く、ログを見るまでは気づけませんでした。
• 「定義しただけで満足する」を数字で否定できる。 主観では「使ってるつもり」でも、実測は5/7が0回。CLAUDE.mdのimplementation-model-routingルールでCodex優先を明記した後、Sonnetサブエージェントへの委譲自体が減っているのも一因と考えられます。

踏んだ落とし穴

• Taskツールはtranscript上でname="Agent"。 素直にname == "Task"でフィルタすると何も拾えない
• 重複記録防止はセッション単位のtool_use_id比較。 グローバルにdedupeすると同じセッションの再実行を弾き損ねる
• known_agentsのグロブが自分の生成物（INDEX.md）を除外し忘れる。 集計ロジックが2箇所に分かれていると、片方だけ除外条件が漏れる
• 0回リストは「不要」の証明にはならない。 security-reviewerは7d窓では0回だが30d窓では1回。窓の切り方次第で結論が変わるので、削除判断は必ず長い窓（30d）を見る

まとめ

• Stop hookでtranscriptからAgent呼び出しを拾い、JSONLに1行ずつ記録する
• agent-usage-summary.shが7d/30d窓でTop10と「定義されているのに0回」を機械的に出す
• agents-index.shのfrontmatter集約とペアで運用すると、定義と実績の両方が可視化される
• launchdで毎朝10:15に自動配信。人間はagent-usage-latest.mdを見るだけでいい
• 実測では定義した7本中5本が30日間0回。削除判断はこの数字を根拠にできる

次回は、この0回リストをもとに実際にエージェントを削った後、Codex優先ルール導入前後でサブエージェント委譲そのものがどれだけ減ったかを数字で見る回にします。

---

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

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

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