agent-usage-analyzer

agent-usage-analyzer is an open-source AI agent usage analyzer and installable agent skill for counting skills, tools, commands, and MCP actions from local session histories.

It is designed for people who use AI coding agents such as Codex and Claude Code and want clear answers to questions like:

• "How many skills did I use last week?"
• "Give me the top 5 skills I used in Codex."
• "Show my Claude Code skill usage for the last 7 days."
• "Compare skill usage by agent."

The skill runs a bundled local analyzer behind the scenes and returns a usage table with coverage notes. The primary deliverable is the repo root itself, which is the real skill folder.

The scope is broader than skills alone. When asked, the analyzer can also report tool, command, and MCP usage from the same session histories.

What is agent-usage-analyzer?

agent-usage-analyzer helps you analyze local AI agent session history and answer questions about:

• skill usage
• tool usage
• command usage
• MCP usage
• recent activity by agent
• top items used over a date range

For normal users, the main workflow is simple:

1. Install the skill into your agent.
2. Ask your agent a natural-language question.
3. Get a local, read-only usage report with coverage notes.

Who is this for?

This project is for:

• Codex users who want to see which skills, tools, or MCP actions they actually used
• Claude Code users who want recent skill usage reports
• teams comparing usage across agents
• developers who want a local-first session-history analytics tool
• power users who want JSON or CSV exports for their own analysis

What questions can it answer?

Examples:

• "How many skills did I use last week?"
• "Give me the top 5 skills I used."
• "Show my top tools from the last 30 days."
• "Compare Codex and Claude Code skill usage."
• "Show MCP actions I used most this week."
• "Export the full report as CSV."

Features

• Root-level installable skill folder with SKILL.md
• Skill-first workflow for Codex and Claude Code
• Broader invocation analysis for skills, tools, commands, and MCP actions
• Local-only, read-only analysis of session histories
• Conservative counting from structured signals only
• Coverage reporting for counted, skipped, partial, and heuristic sessions
• Markdown, JSON, and CSV outputs
• Optional alias mapping from YAML or JSON

Tested agents

• Codex
• Claude Code

Other agents may work through the export-dir path when their session history is available in a compatible structured format. Codex and Claude Code are the verified integrations today.

What does it count?

This project is primarily about agent skill usage, but it can also analyze broader invocation activity:

• skill
• tool
• command
• mcp

For Codex and Claude Code event-log formats that do not expose a dedicated skill_invocation field, the analyzer counts skill activations from structured loads of .../skills/<name>/SKILL.md.

It does not count names from plain transcript prose, markdown tables, summaries, or handoff text.

Normal user expectation:

• ask about skills by default
• ask about tools, commands, or MCP explicitly when that is what you want
• treat those categories as separate unless you intentionally request a broader combined view

Runtime requirements

• Node.js 22+
• Local filesystem access
• No network dependency during analysis

Install the skill

Recommended: use the Skills CLI.

From a local checkout:

npx skills add . -a codex
npx skills add . -a claude-code

After publishing the repo, install from GitHub:

npx skills add yctimlin/agent-usage-analyzer -a codex
npx skills add yctimlin/agent-usage-analyzer -a claude-code

Alternative: use the bundled installer when you want explicit copy or symlink control:

node scripts/install.mjs --agent codex --scope user --mode symlink
node scripts/install.mjs --agent claude --scope project --repo /path/to/project --mode copy

Manual targets:

• Codex user scope: ~/.agents/skills/agent-usage-analyzer
• Codex project scope: <repo>/.agents/skills/agent-usage-analyzer
• Claude user scope: ~/.claude/skills/agent-usage-analyzer
• Claude project scope: <repo>/.claude/skills/agent-usage-analyzer

How to use it in your agent

After installation, ask your agent directly.

Examples:

• "How many skills did I use last week?"
• "Give me the top 5 skills I used."
• "Show skill usage for Claude Code only."
• "Compare my Codex and Claude skill usage for the last 7 days."
• "Show my top tools from the last 7 days."
• "Compare MCP usage by agent."
• "Export my full skill usage report as CSV."

The skill should infer filters from the request, run the local analyzer, and return a markdown table plus coverage notes.

Example prompts

• "How many skills did I use last week? Give me top 5."
• "Show my recent Codex skill usage."
• "Show my Claude Code skill usage for the last 7 days."
• "Compare skill usage by agent."
• "Show my top tools from the last 30 days."
• "Show MCP actions I used most in Claude Code."
• "Compare tools vs skills for the last week."
• "Show raw invocation names, not normalized buckets."
• "Export the full report as CSV."

Advanced CLI usage

The skill uses scripts/analyze.mjs internally. Most users do not need to run it directly, but the CLI is available for debugging, exports, or custom automation.

Analyze an export directory:

node scripts/analyze.mjs --provider export-dir --input ./session-export --format markdown

Use the conservative auto mode:

node scripts/analyze.mjs --provider auto --input ./session-export --agent codex --since 2026-01-01 --format json

Export CSV:

node scripts/analyze.mjs --provider export-dir --input ./session-export --format csv --output ./agent-usage.csv

Filter to one category:

node scripts/analyze.mjs --provider export-dir --input ./session-export --kind skill --format markdown
node scripts/analyze.mjs --provider export-dir --input ./session-export --kind tool --format markdown

Provider model

v1 ships one provider:

• export-dir: reads .json and .jsonl files from a local directory tree

auto is supported as a stable CLI surface, but in v1 it only resolves when --input is supplied. The analyzer does not scan arbitrary filesystem locations or call remote services.

The provider model is agent-neutral. In practice, the project currently has first-class tested parsers for Codex archived event logs and Claude Code project session logs. Other agents can work if their exports contain compatible structured usage summaries, raw invocation events, structured activity blocks, or structured skill-load signals.

Alias configuration

Alias files may be YAML or JSON. See references/ALIASES.example.yaml.

node scripts/analyze.mjs --provider export-dir --input ./session-export --aliases ./aliases.yaml

Privacy posture

• Analysis is local-only
• Raw session files are never modified
• No network calls are made during analysis
• Samples are off by default
• Heuristic parsing is off by default

FAQ

Is this a skill or a CLI?

Both, but the project is skill-first. Most users install it as a skill and never run the CLI manually.

Does it only work for skills?

No. The default user story is skill usage analysis, but it can also report tool, command, and MCP usage.

Does it upload my session history?

No. Analysis is local-only and read-only.

Does it only support Codex and Claude Code?

Those are the tested integrations today. Other agents can work if you can provide compatible JSON or JSONL session-history exports.

Can I export the results?

Yes. The analyzer can render Markdown, JSON, and CSV.

Troubleshooting

• Missing dist/ runtime: run npm install and npm run build
• --provider auto without --input: provide an explicit export directory in v1
• Empty coverage: your export likely lacks structured invocation data, or filters excluded the sessions
• Skills CLI install: use npx skills add . -a codex or npx skills add . -a claude-code from the repo root during local development