https://github.com/effet/cxusage
Codex usage analytics CLI that scans ~/.codex/sessions, aggregates tokens by day or model, and estimates cost using OpenRouter pricing.
https://github.com/effet/cxusage
anthropic claude cli codex command-line-tool cost-estimation daily-reports data-aggregation developer-tools jsonl log-analysis metrics nodejs observability openai openrouter reporting token-usage typescript usage-analytics
Last synced: 7 months ago
JSON representation
Codex usage analytics CLI that scans ~/.codex/sessions, aggregates tokens by day or model, and estimates cost using OpenRouter pricing.
- Host: GitHub
- URL: https://github.com/effet/cxusage
- Owner: Effet
- License: mit
- Created: 2025-09-12T03:23:36.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2025-09-12T08:44:41.000Z (7 months ago)
- Last Synced: 2025-09-12T09:25:44.394Z (7 months ago)
- Topics: anthropic, claude, cli, codex, command-line-tool, cost-estimation, daily-reports, data-aggregation, developer-tools, jsonl, log-analysis, metrics, nodejs, observability, openai, openrouter, reporting, token-usage, typescript, usage-analytics
- Language: TypeScript
- Homepage:
- Size: 27.3 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# cxusage
Analyze Codex daily usage from session logs. Similar to `ccusage`, this Node.js CLI scans JSONL session logs under `~/.codex/sessions` and aggregates token counts by day or by model within each day.
- Input: JSONL logs (recursively) under `~/.codex/sessions` by default
- Output: Plain table (default), Markdown table (`--md`), or JSON lines (`--json`)
- Grouping: By day (default) or by model-within-day (`--by model`)
- Timezone: Local timezone by default, or specify via `--tz` with an IANA TZ
## Quickstart
- After publish to npm: `npx cxusage --help`
- From GitHub (before publish): `npx github:Effet/cxusage -- --help`
- Typical commands:
- `npx cxusage daily --from 2025-01-01 --to 2025-01-31 --md`
- `npx cxusage daily --by model --json`
## Usage
The top-level command is `cxusage`. The primary subcommand is `daily`.
- Default root: `~/.codex/sessions`
- Date range: `--from YYYY-MM-DD`, `--to YYYY-MM-DD`
- Grouping: `--by day` (default) or `--by model`
- Output format: `--md` (Markdown) or `--json` (JSONL), default is a plain table
- Empty days: include zero-usage days via `--empty`
Examples:
- `cxusage daily`
- `cxusage daily --from 2025-01-01 --to 2025-01-31 --md`
- `cxusage daily --by model --json`
- Use a specific timezone: `cxusage daily --tz Asia/Shanghai`
## Pricing
The CLI automatically fetches model pricing from the public OpenRouter models API and estimates cost based on input/output tokens per model.
- API: `https://openrouter.ai/api/v1/models`
- Fallback: when a model name is missing (`unknown`), cxusage attempts a fallback chain: `openai/gpt-5` → `openai/gpt-4o` → `anthropic/claude-3.5-sonnet`. The first available price is used.
- Disable fallback with `--no-fallback`. With fallback disabled, unknown models show `$0.00`.
Notes about token counts: cxusage sums numeric fields commonly used for token counts (e.g., `input_tokens`, `output_tokens`, `promptTokenCount`, `completionTokenCount`, etc.). If older logs don’t include any of these fields, tokens will appear as zero even though events are counted. Use `--by model --debug` to inspect which model names are detected in your logs.
## Programmatic invocation
This package exposes only a CLI. If you need a library API, please open an issue to discuss the desired interface.
## Development
- Node 18+ required
- `npm i`
- `npm run build`
- `node dist/cli.js --help`
### Contribution Guide
- Issues: https://github.com/Effet/cxusage/issues
- Pull Requests: welcome! Please read CONTRIBUTING.md
### Release
- CI runs on pushes/PRs to verify install and build.
- Stable release: create a Git tag like `v0.1.0` to publish to npm as `latest`.
- The workflow automatically sets `package.json` version from the Git tag (stripping the leading `v`).
- Pre-release tags (containing a hyphen, e.g. `v0.2.0-rc.1`) publish with the `next` dist-tag.
- The release workflow requires a repository secret `NPM_TOKEN` with publish permissions.