reflect-usage skill
✓ VerifiedAnalyze local AI coding-agent telemetry to inspect token usage, costs, model performance, and session efficiency.
- GitHub stars
- 20
- Files
- 2
- Last commit
- Nov 10, 2026
- License
- Apache-2.0
- Allowed tools
- —
What does the reflect-usage skill do?
reflect-usage analyzes local AI coding-agent telemetry to inspect token usage, costs, model performance, and session efficiency.
Summary generated from the skill's SKILL.md.
About the reflect-usage skill
Analyzing local AI coding-agent telemetry to understand token consumption and costs is what this skill enables. Developers can use it to investigate why specific sessions used high amounts of tokens or to evaluate the efficiency of their workflows across tools like Cursor, Claude, Copilot, and Gemini. It functions by querying a local SQLite database that serves as the source of truth for captured session data.
An agent should load this skill when a user asks about token spend, model performance, or session duration. The skill provides detailed breakdowns of input, output, cache-write, cache-read, and reasoning tokens. It also tracks tool, MCP, and subagent counts to provide context for the usage. Users can query the current runtime session, a specific session ID, or global data spanning a day, week, month, or the entire history. While it provides estimated costs and identifies drivers like subagent fan-out or repeated failures, it does not assign specific token counts to individual tools or replace official provider billing records.
What an agent can do with it
- 1Investigate high token usageAsk the agent to explain why a specific coding session consumed an unexpected number of tokens.
- 2Evaluate session efficiencyDetermine if a coding session was productive or inefficient based on tool activity and failure rates.
- 3Analyze global agent costsRequest a summary of total costs and token usage across all agents over the last seven days.
- 4Audit model performanceCompare how different models or agents are performing in terms of cost and success rates.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the reflect-usage skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the reflect-usage skill in Claude Code
~/.claude/skills/reflect-usage/SKILL.md
$ npx degit o11y-dev/reflect/src/reflect/data/skills/reflect-usage ~/.claude/skills/reflect-usageInstall the reflect-usage skill in Claude Code (project)
.claude/skills/reflect-usage/SKILL.md
$ npx degit o11y-dev/reflect/src/reflect/data/skills/reflect-usage .claude/skills/reflect-usageInstall the reflect-usage skill in Codex
~/.agents/skills/reflect-usage/SKILL.md
$ npx degit o11y-dev/reflect/src/reflect/data/skills/reflect-usage ~/.agents/skills/reflect-usageInstall the reflect-usage skill in Gemini CLI
~/.gemini/skills/reflect-usage/SKILL.md
$ npx degit o11y-dev/reflect/src/reflect/data/skills/reflect-usage ~/.gemini/skills/reflect-usageInstall the reflect-usage skill in Claude.ai
npx degit o11y-dev/reflect/src/reflect/data/skills/reflect-usage reflect-usage && zip -r reflect-usage.zip reflect-usage # claude.ai → Customize → Skills → + → Create skill → Upload a skill → reflect-usage.zip
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the scripts before you let an agent run them. How checks work
- Source repository linked and reachableo11y-dev/reflect/src/reflect/data/skills/reflect-usage is public and reachablegithub.com/o11y-dev/reflect/tree/HEAD/src/reflect/data/skill ↗Pass
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit 2026-11-10github.com/o11y-dev/reflect/commits ↗Pass
- No download-and-run or credential theft in scriptsNo scripts in the skill folderPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/o11y-dev/reflect/blob/HEAD/src/reflect/data/skill ↗Pass
- Pre-approved tools are scopedNo pre-approved tools; the agent asks before using onegithub.com/o11y-dev/reflect/blob/HEAD/src/reflect/data/skill ↗Pass
- SKILL.md follows the Agent Skills formatValid name and description; says when to use it; 56 linesgithub.com/o11y-dev/reflect/blob/HEAD/src/reflect/data/skill ↗Pass
SKILL.md
View on GitHubreflect-usage
Use Reflect's canonical local SQLite telemetry as the source of truth for usage questions.
Commands
Run the narrowest matching command and prefer JSON when preparing an answer:
reflect usage --json # current runtime session
reflect usage --session SESSION_ID --json # selected session
reflect usage --global --period day --json # all local usage in 24 hours
reflect usage --global --period week --json # all local usage in 7 days
reflect usage --global --period month --json # all local usage in 30 days
reflect usage --global --period all --json # all captured local usage
reflect usage --global --period week --agent codex --json
reflect usage --refresh --json # ingest local sources first when freshness matters
--agent is valid only with --global. Global queries aggregate the complete matching SQLite cohort and do not inherit the browser's session-page limit.
Normal usage opens the prepared SQLite store in query-only mode. It never
migrates the schema or repairs rollups. A missing, outdated, empty, or
maintenance-stale snapshot returns an actionable error. Use --refresh when
the active session is missing or the operator explicitly needs newly captured
native sessions; use reflect refresh for a complete snapshot rebuild. Either
refresh can take longer on large local stores.
Analysis workflow
- Establish scope and freshness. Name the session or period and preserve any resolution or limitation warning.
- Account for the spend. Show recorded input, output, cache-write, cache-read, and reasoning tokens separately; do not hide cache or reasoning inside one unexplained total.
- Explain where it went. Attribute input/output tokens and estimated cost by model or agent when available. Treat tool, MCP, and subagent counts as workflow context, not token attribution: the usage report does not assign tokens to individual tools.
- Explain likely drivers. Relate the spend to observed LLM calls, tool intensity, subagent fan-out, duration, failures, and recoveries. Mark causal explanations as
Inference. - Judge the result. Use
productive,mixed,inefficient, orindeterminate, followed by the strongest one or two reasons. A low token count is not automatically good, a high count is not automatically bad, and output-token volume is not a quality score. - Suggest one concrete next check or improvement only when the evidence supports it.
For a global scope, normalize raw totals with useful rates such as tokens or cost per session, failures per session, and recovery rate. Avoid comparing periods or agents with materially different session counts using totals alone.
Useful evidence for a productive judgment includes a completed session, few unresolved failures, successful recovery, and tool or subagent activity consistent with the task. Useful evidence for an inefficient judgment includes repeated failures, excessive retries or fan-out, long duration, or large context/cache creation without corresponding progress. If outcome evidence is absent, return indeterminate rather than inventing value.
Reporting contract
- Lead with the requested total and verdict, then add only the breakdowns that explain the spend.
- Prefer this compact answer shape:
Spend,Where it went,Why, andVerdict. - Label the evidence
Local telemetry. Estimated costs are not provider invoices, quotas, or billing records. - Label behavioral explanations and value judgments
Inference; never present tool counts as exact token ownership. - Preserve any
limitationsfrom the JSON response. Ifresolutionstarts withinferred_, say that the current session was inferred because its telemetry was not yet present locally. - Do not run
reflect setup, install hooks, or change capture settings automatically. If no sessions exist, explain that limitation and offer the setup command. - Use the general
$reflectskill only when the question also needs workflow guidance, provider quota reconciliation, or broader telemetry diagnosis.
Files in this skill
2reflect-usage skill questions
How do I install the reflect-usage skill in Claude Code?
Run npx degit o11y-dev/reflect/src/reflect/data/skills/reflect-usage ~/.claude/skills/reflect-usage. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the reflect-usage skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
How can I see my token usage for a specific time period?
You can use the global flag with a period argument, such as --period day, week, month, or all, to view usage over those durations.
Does the usage report assign specific tokens to individual tools?
No, the usage report does not assign tokens to individual tools; tool, MCP, and subagent counts are treated as workflow context rather than token attribution.
What should I do if my session data is missing or outdated?
You can use the --refresh flag to ingest local sources first, or use 'reflect refresh' for a complete snapshot rebuild.