Efficiency

llm-usage efficiency places repo-attributed token usage and cost beside your local Git activity. The resulting ratios help with review, but they do not measure code quality, business value, or causal return on investment.

Run the report

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

Start with a monthly view so the raw totals have enough volume to interpret:

llm-usage efficiency monthly --repo-dir /path/to/repo

Other useful forms:

llm-usage efficiency weekly --repo-dir /path/to/repo --json
llm-usage efficiency monthly --repo-dir /path/to/repo --by-source
llm-usage efficiency monthly --repo-dir /path/to/repo --share

--share works for monthly reports and cannot be combined with --by-source.

What the command joins

The command builds two datasets for each period:

Usage events mapped to the selected repository root through source metadata such as a working directory or file path.
Commits and line changes from local Git history for your configured author.

Events without repository attribution stay out of the usage totals. Periods need both Git activity and attributed usage before the renderer emits a row.

Column formulas

Column	Formula
`Tokens/Commit`	`(Input + Output + Reasoning) / Commits`
`$/Commit`	`Cost / Commits`
`$/1k Lines`	`Cost / (ΔLines / 1000)`
`Commits/$`	`Commits / Cost`, when cost is above zero

Tokens/Commit excludes cache read and cache write tokens. The table keeps those buckets visible in the raw usage columns.

A zero denominator renders as - in terminal and Markdown output. JSON omits that derived value. Partial pricing adds a ~ prefix to affected USD metrics.

Read the denominators before the ratios

Review Commits, ΔLines, and Cost first. A small denominator can make a ratio swing even when the underlying usage barely changed.

The ratios also inherit the limits of Git activity:

A commit and a line delta describe repository activity, not correctness or customer value.
Source metadata determines repository attribution. Unattributed events cannot contribute.
Filters can change which commit days qualify, so two filtered runs may not share the same Git denominator.

Use the report to spot periods worth investigating. Do not use one ratio as a developer score.

Per-source view

llm-usage efficiency monthly --repo-dir /path/to/repo --by-source

Source rows show usage and cost under each period subtotal. Git outcomes belong to the repository period, so source rows display - for commits, line changes, and derived ratios. The period subtotal carries those values.

JSON always returns { "grouping", "rows" } under data: grouping is "source" with --by-source and "period" otherwise.

Filters and attribution

Usage filters apply before aggregation:

--source
--provider
--model
source path overrides

These filters also constrain Git attribution. The command counts a commit day only when that day contains a matching repo-attributed usage event.

For a source-specific comparison, run the same date range and repository with a different source filter:

llm-usage efficiency monthly --repo-dir /path/to/repo --source codex
llm-usage efficiency monthly --repo-dir /path/to/repo --source claude

Keep the raw denominators beside the ratios when you compare the results.