Efficiency

Efficiency reporting is the core value proposition of llm-usage-metrics. By correlating local Git outcomes with LLM costs, you can derive the true ROI of your AI-assisted development workflow.

The ROI Equation

llm-usage efficiency joins two high-signal datasets:

1. Repo-Attributed Usage: Token counts and costs mapped to your project root.
2. Git Outcomes: Local commit volume and line-delta metrics for your author.

This join allows you to answer questions like: How much does a commit actually cost in tokens? and What is my USD spend per 1k lines of code?

Command structure

llm-usage efficiency <daily|weekly|monthly> [options]

Examples:

llm-usage efficiency daily
llm-usage efficiency weekly --repo-dir /path/to/repo
llm-usage efficiency monthly --repo-dir /path/to/repo --json
llm-usage efficiency monthly --repo-dir /path/to/repo --source codex

What is joined

Efficiency rows are built from two datasets per period:

• repo-attributed usage totals (Input, Output, Reasoning, Cache Read, Cache Write, Total, Cost)
• Git outcomes for your configured author (Commits, +Lines, -Lines, ΔLines)

Only usage events mapped to the selected repository root are included.

Column formulas

• All Tokens/Commit = Total / Commits
• Non-Cache/Commit = (Input + Output + Reasoning) / Commits
• $/Commit = Cost / Commits
• $/1k Lines = Cost / (ΔLines / 1000)
• Commits/$ = Commits / Cost (only when Cost > 0)

Rendering rules:

• period rows are emitted only when both Git outcomes and repo-attributed usage signal exist
• if a denominator is zero, the derived value is - (terminal/markdown) or omitted in JSON
• when pricing is incomplete, affected USD values are approximate (~ prefix in terminal/markdown)

Scope and attribution semantics

Repository root

• default repo is current working directory
• override with --repo-dir
• usage events that cannot be mapped to a repo are counted as unattributed and excluded

Filters

Usage filters apply before efficiency aggregation:

• --source
• --provider
• --model
• source path overrides (--pi-dir, --codex-dir, --gemini-dir, --droid-dir, --opencode-db, --source-dir)

Important: these filters also affect commit attribution. Only commit days with matching repo-attributed usage events are counted in efficiency outcomes.

Reading results without being misled

• All Tokens/Commit includes cache read/write tokens by design.
• Non-Cache/Commit is the cleaner metric for direct prompt/response intensity.
• Compare both together:
  • high All Tokens/Commit + much lower Non-Cache/Commit usually means cache-heavy traffic
  • both high means high non-cache workload

For source comparisons, run the same command per source:

llm-usage efficiency monthly --repo-dir /path/to/repo --source pi
llm-usage efficiency monthly --repo-dir /path/to/repo --source codex
llm-usage efficiency monthly --repo-dir /path/to/repo --source gemini
llm-usage efficiency monthly --repo-dir /path/to/repo --source droid
llm-usage efficiency monthly --repo-dir /path/to/repo --source opencode

Recommended review workflow

1. Start with monthly for stability.
2. Check Commits, ΔLines, and Cost first (raw denominators).
3. Then interpret derived ratios ($/Commit, $/1k Lines, token/commit metrics).
4. Drill into source/provider/model filters only after baseline sanity checks.