Nomira — User Guide

From install to first insight in under 15 minutes.

Goal: from install to your first real insight in under 15 minutes, with no account, no server, and nothing leaving your machine.

Requirements

• Python 3.9+ (standard library only — no pip install needed).
• Local logs from a supported assistant:
• Claude Code → ~/.claude/projects/…
• Codex → ~/.codex/sessions/…

1. Your newest session

python nomira.py

Shows total (API-equivalent) cost, the cache-vs-visible gap, cost by component and model, the most expensive turns (and why), and waste signals.

2. Other inputs

python nomira.py --all              # aggregate across all local sessions
python nomira.py --list             # list sessions Nomira can see
python nomira.py <path/to/session.jsonl>
python nomira.py --source codex      # analyze Codex instead
python nomira.py --source cursor     # availability report (Cursor stores no local tokens)
python nomira.py ... --json          # machine-readable output

3. Compare developers / projects (efficiency)

python nomira.py --compare              # by session
python nomira.py --compare --by-project # by project

Columns: cost, calls, $/call, $/1k output, and cache-reuse % (higher = context reused rather than rebuilt = cheaper).

4. Team dashboard (self-hosted)

python nomira.py --ship --developer alice   # write usage-only events to the store
python nomira.py --serve                    # open http://127.0.0.1:8787

Each teammate runs --ship (optionally pointing at a shared --db or a remote collector). The dashboard shows cost by developer, project, model, and trend. Only usage metadata is stored — never prompts or responses.

Reading the numbers

• Subscription tools (Claude Code/Codex): the dollar is the *API-equivalent

value* of your usage, plus allowance used — judge if you're getting your plan's worth, not a bill.

• Token-billed APIs: the dollar is the actual bill.
• Rates are matched to published pricing; reconcile against a real invoice before

treating absolute dollars as exact. Relative breakdowns are reliable now.

Troubleshooting

• "No sessions found" → check the assistant is installed and has run; try --list.
• Unicode/encoding errors → Nomira sets UTF-8 output; ensure a modern terminal.
• Wrong-looking totals → check the model is recognized (COST BY MODEL); unknown

models are flagged and excluded, never guessed.