model-usage AGENTS.md

Model Usage

Zero-config CLI for analyzing AI model usage & costs across all local TUI tools — pi, Claude Code, Codex, Gemini CLI, OpenCode, and more.

Project Structure

├── src/
│   ├── cli.ts               # CLI entry point (Commander setup)
│   ├── display.ts            # Output formatting (tables, models, projects)
│   ├── usage.ts              # Read usage data (auto-detect all sources)
│   ├── aggregator.ts         # Aggregate messages by project/date
│   ├── filters.ts            # Time and project filtering
│   ├── sorter.ts             # Sorting by cost/time/tokens/project
│   ├── pricing.ts            # Fetch model pricing from LiteLLM
│   ├── project-detector.ts   # Auto-detect current project
│   ├── update-checker.ts     # Check for npm updates
│   ├── github-prompt.ts      # GitHub star prompt
│   ├── source-selector.ts    # Interactive TUI source picker
│   ├── util.ts               # Shared utilities (path, fetch)
│   ├── types.ts              # TypeScript type definitions
│   ├── cli-table3.d.ts       # Type declarations for cli-table3
│   └── sources/              # Auto-discovered source adapters
│       ├── index.ts          # Auto-discovery (no manual imports needed)
│       ├── common.ts         # Shared utilities for all sources
│       ├── pi.ts             # pi sessions
│       ├── claude.ts         # Claude Code sessions
│       ├── codex.ts          # Codex CLI sessions
│       ├── gemini.ts         # Gemini CLI sessions
│       ├── opencode.ts       # OpenCode sessions (SQLite)
│       └── grok.ts           # Grok CLI sessions (SQLite)
├── dist/                     # Compiled output (gitignored)
├── tsconfig.json
└── package.json

Key Commands

# Default (interactive source selection if TTY, else all sources)
mu                     # Show all usage for auto-detected project
mu -a                  # Show all projects (skip auto-detection)

# Source selection
mu -s pi,opencode      # Only query specific TUI tools (long form: --sources)
mu --sources all          # Query all sources (skip selection)
mu                        # Interactive checkbox UI to pick sources

# Filtering
mu -t 7d               # Last 7 days (rolling, relative to "now"); also 30min, 2h, 1m, 1y
mu -t today            # Calendar keywords: today, yesterday, thisweek, lastweek,
                       # thismonth, lastmonth, thisyear, lastyear (week starts Monday;
                       # hyphenated aliases like this-week work too)
mu -t 7-8              # Month range this year; july-august or 2025-7-2026-8 also work
mu -t 2026-07-25       # A single date — that whole calendar day
mu -p <project>        # Filter by project (partial match: "model", "obix")
mu -m <model>          # Filter by model (partial match: "sonnet", "gpt-5")

# Sorting
mu -k cost -o desc     # Sort by cost descending
mu -k time -o asc      # Sort by time ascending (default)

# View modes
mu -d                  # Detailed view (individual messages)
mu -b                  # Aggregate by date only (combines all projects)

# Lists
mu -P                  # List projects
mu -M                  # List models with pricing

# Combined
mu -m sonnet -t 7d     # Last 7 days, sonnet models only
mu -m haiku -p myproject --by-date  # Per-day, haiku only, specific project