tool-usage-tracker

tool-usage-tracker

A small Claude Code plugin that logs every Skill and Agent (subagent/Task) tool invocation to a local JSONL file, and ships a skill that turns the log into an on-demand markdown report.

Built because Claude's built-in analytics dashboards (Team / Enterprise) don't break down usage per skill or per agent — and sometimes you want to know which skills are pulling their weight and which ones never trigger.

What it does

Two things:

1. Tracks every Skill tool call, every subagent run, and every slash command — silently, in the background, via Claude Code hooks. Each invocation gets one line in a local JSONL log.
2. Reports on the log on demand. Ask Claude for a usage report and it runs the bundled skill-usage-tracker skill, which prints a markdown table of which tools you used and how often, over any time window you ask for. Optionally, a second table lists every available tool you haven't touched.

Install

From inside Claude Code, add this repo as a marketplace, then install the plugin from it:

/plugin marketplace add bcoulombel/claude-tool-usage-tracker
/plugin install tool-usage-tracker@bcoulombel

Verify with:

/plugin list

To update later:

/plugin marketplace update bcoulombel
/plugin uninstall tool-usage-tracker@bcoulombel
/plugin install tool-usage-tracker@bcoulombel
/reload-plugins

You may need to restart Claude code to use the latest version and not a cache version.

Use

Two ways to trigger a report — pick whichever feels natural.

Natural language. Just describe what you want in any session:

Show me a tool usage report for the last 7 days

Top skills all-time

What agents have I used this month?

What skills haven't I used this month?

Claude recognises the time window, runs the report script with the right period, and adds --unused only when you explicitly ask about untouched tools.

Slash command. Invoke the skill directly with arguments:

/tool-usage-tracker:skill-usage-tracker report 7d
/tool-usage-tracker:skill-usage-tracker report 30d --unused

Either way, you get back something like:

# Tool usage — last 30 days

| Type | Name | Count |
|------|------|------:|
| agent | Explore | 31 |
| agent | general-purpose | 12 |
| skill | lnb-build-frontend | 42 |
| skill | lnb-review-pr | 18 |
| slash-cmd | ship | 6 |
...

_Total invocations: 187 — source: /Users/you/.claude/local-telemetry/tools_

_Pass `--unused` to also list available tools that were not invoked in this period._

Ask for unused explicitly ("what haven't I used this month?") and you also get:

## Unused tools — available but not invoked in last 30 days

| Type | Name | Description |
|------|------|-------------|
| agent | lnb-rename-auditor | Catches missed references when a PR renames a symbol |
| skill | gstack-canary | Post-deploy canary monitoring |
...

How tracking works

Three Claude Code hooks feed the log, each handling a different event:

• Skill tool calls — when Claude decides to invoke a skill mid-conversation. Captured by a PreToolUse hook.
• Subagent runs (built-in Explore/Plan/general-purpose and custom .claude/agents/*.md). Captured by a SubagentStop hook that fires once per subagent completion. More reliable than PreToolUse on the Agent tool, which empirically misses custom subagents.
• Slash commands typed by you (/lnb-review-pr, /plugin, etc.) — these expand inline and don't go through the Skill tool, so they're caught by a separate UserPromptSubmit hook.

All three append to one local file, one per month:

~/.claude/local-telemetry/
└── tools/
    ├── 2026-04.jsonl
    ├── 2026-05.jsonl
    └── ...

Plain text. Stays on your machine — never uploaded. Each line is one invocation, in one of three shapes:

{"ts":"...","tool":"Skill","skill":"lnb-build-frontend","subagent":null,"slash_command":null, ...}
{"ts":"...","tool":"SubagentStop","skill":null,"subagent":"Explore","slash_command":null,"stop_reason":"completed", ...}
{"ts":"...","tool":"SlashCommand","skill":null,"subagent":null,"slash_command":"lnb-review-pr", ...}

At ~100 tool calls/day this comes out to roughly 1 MB/month — negligible. No rotation needed; old months are kept indefinitely so all-time reports work.

Report shape

The skill-usage-tracker skill prints up to two markdown tables:

• Used tools (always shown) — grouped by Type (agent → skill → slash-cmd), sorted by count.
• Unused tools (opt-in) — every Skill/Agent/slash-command found on disk (in ~/.claude/, the plugin cache, and <cwd>/.claude/) that wasn't invoked in the period, with one-liner descriptions pulled from each tool's frontmatter. Off by default because the list is long; ask the skill for "unused tools" or "what haven't I used" — or pass --unused to the slash form — to include it.