Getting Started

Install

npm install -g llm-usage-metrics

Run without global install:

npx --yes llm-usage-metrics@latest daily

Requirements

• Node.js 24+
• At least one supported source:
  • .pi sessions (~/.pi/agent/sessions/**/*.jsonl)
  • .codex sessions (~/.codex/sessions/**/*.jsonl)
  • .gemini sessions (~/.gemini/tmp/*/chats/*.json)
  • Droid sessions (~/.factory/sessions/**/*.settings.json)
  • OpenCode SQLite DB (auto-discovered or explicit --opencode-db, requires built-in node:sqlite support)

First report

llm-usage daily

Useful next commands:

llm-usage weekly --timezone Europe/Paris
llm-usage monthly --since 2026-01-01 --until 2026-01-31
llm-usage trends --metric tokens --days 14

Common filters

llm-usage monthly --source pi,codex,gemini,droid
llm-usage monthly --provider openai
llm-usage monthly --model claude

Output modes

llm-usage daily --json
llm-usage daily --markdown
llm-usage monthly --per-model-columns
llm-usage monthly --ignore-pricing-failures

Efficiency quick start

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

See Efficiency for full metric semantics and interpretation rules.

Trends quick start

llm-usage trends
llm-usage trends --metric tokens --days 7
llm-usage trends --by-source --json

See Trends for range rules, metric semantics, and JSON shape.

Gemini explicit path

llm-usage monthly --source gemini --gemini-dir /path/to/.gemini

OpenCode explicit DB path

llm-usage monthly --source opencode --opencode-db /path/to/opencode.db

If no default OpenCode DB is found and no explicit path is given, OpenCode is treated as unavailable for that run.

Droid explicit path

llm-usage monthly --source droid --droid-dir /path/to/.factory/sessions