@f6n/cli-usage

@f6n/cli-usage reads local Codex and Copilot CLI session files and prints clear token-usage tables grouped by app, model, and time period.

Live site: https://cli-usage.f6n.run
Repository: https://github.com/Ashwinning/cli-usage

Latest release: 0.1.4
Changelog: CHANGELOG.md

What This App Does

This app gives you one local report for:

• Codex usage from local Codex session JSONL files
• Copilot usage from captured summaries and fallback Copilot session event files
• Token totals split into Input, Cached, Output, Reasoning, and Total

It does not require API keys or a hosted backend. It works directly from files on your machine.

How It Works

1. It scans local Codex and Copilot data sources.
2. It normalizes records into one schema.
3. It applies your app/model filters (with wildcard support).
4. If no --period is provided, it auto-picks one view:
   • under 1 day span -> session
   • under 1 month span -> day
   • 1 month or more -> month
5. You can also explicitly request one or more periods (session, day, week, month).
6. It renders grouped tables (app-model, app, or model).

First-Time Setup (Step by Step)

From this package directory (apps/cli-usage) or after global install:

1. Install and build:

npm install
npm run build

2. Run your first combined usage report:

cli-usage

3. If you use Copilot CLI, run it through the wrapper so future usage is captured:

f6n-copilot -- [copilot args...]

4. Re-run the report:

cli-usage

Recommended Daily Workflow

1. Use Codex and Copilot normally.
2. For Copilot, prefer running through f6n-copilot / wrap.js.
3. Run cli-usage any time you want a current usage report.
4. If Copilot logs are missing, run bunx @f6n/copilot-usage instead of copilot each time.

Output You Will See

Example format:

Weekly token usage (grouped by app)
+----------+---------+----------+-------+--------+--------+-----------+-------+
| Week     | App     | Sessions | Input | Cached | Output | Reasoning | Total |
+----------+---------+----------+-------+--------+--------+-----------+-------+
| 2026-W03 | codex   | 1        | 160   | 30     | 70     | 20        | 250   |
| 2026-W03 | copilot | 1        | 70    | 5      | 35     | 0         | 105   |
+----------+---------+----------+-------+--------+--------+-----------+-------+

Columns:

• Day / Week / Month / session day (depends on selected period)
• Grouping columns: App and/or Model (depends on --group-by)
• Sessions: unique sessions in that period and grouping
• Input, Cached, Output, Reasoning, Total: token counts

CLI Reference

cli-usage [options]

Options:

• --codex-home <path> override CODEX_HOME (default ~/.codex)
• --copilot-home <path> override COPILOT_HOME (default ~/.copilot)
• --f6n-home <path> override F6N_CLI_USAGE_HOME state root
• --group-by <value> app-model (default), app, or model
• --period <value> session, day, week, month, all, or comma list like session,day
• --app <pattern> wildcard filter for app (* and ? supported)
• --model <pattern> wildcard filter for model (* and ? supported)
• -h, --help show help

Examples:

cli-usage
cli-usage --period session
cli-usage --period week --group-by app
cli-usage --period day --group-by model --model "gpt-5*"
cli-usage --period month --app "copilot"
cli-usage --period session,day,week,month --app "*" --model "*codex*"

Copilot Wrapper

f6n-copilot-wrap [--copilot-home <path>] [--f6n-home <path>] [--capture-dir <path>] [--copilot-bin <bin>] [-- <copilot args>]

Installed binary names:

• cli-usage -> dist/cli.js
• f6n-usage -> dist/cli.js (legacy alias)
• f6n-copilot-wrap / f6n-copilot -> dist/wrap.js

Data Sources

Codex:

• ~/.codex/sessions/**/*.jsonl (or --codex-home, or CODEX_HOME)

Copilot usage summaries:

• <f6n-state>/copilot/usage-summaries.jsonl
• ~/.f6n-copilot-usage/usage-summaries.jsonl (or platform equivalent)
• <copilot-home>/f6n-usage/usage-summaries.jsonl

Copilot archive/event fallback:

• <f6n-state>/copilot/session-archive/*.events.jsonl
• ~/.f6n-copilot-usage/session-archive/*.events.jsonl
• <copilot-home>/session-state/**/events.jsonl

State Directory Defaults

f6n state root (F6N_CLI_USAGE_HOME or --f6n-home):

• Windows: %USERPROFILE%\\.f6n-cli-usage\\
• macOS: ~/Library/Application Support/f6n-cli-usage/
• Linux: $XDG_STATE_HOME/f6n-cli-usage/ or ~/.f6n-cli-usage/

Copilot home (COPILOT_HOME or --copilot-home):

• $XDG_STATE_HOME/.copilot if XDG_STATE_HOME is set
• otherwise ~/.copilot

Notes and Limitations

• Historical Copilot usage can be incomplete if events were not captured while sessions were active.
• If Copilot logs are missing, run bunx @f6n/copilot-usage instead of copilot each time so usage is captured.
• Copilot event types such as assistant.usage and session.shutdown can be ephemeral depending on local session-state persistence.
• Wrapper parsing is best-effort and based on Copilot terminal output.

Development

npm run build
npm run test

Links

• CLI usage website: https://cli-usage.f6n.run
• CLI usage repository: https://github.com/Ashwinning/cli-usage
• f6n.run monorepo: https://github.com/Ashwinning/f6n.run