Ccusage Agent Sources

ccusage Agent Sources

Use this skill when touching data loading, token normalization, cost calculation, or commands for any ccusage agent adapter.

Shared Report Concepts

Reports aggregate raw usage into daily, monthly, session, or billing-block summaries and output either tables or JSON.

The canonical command surface is the unified ccusage CLI:

ccusage daily
ccusage codex daily
ccusage opencode daily
ccusage amp daily
ccusage pi daily

Standalone agent wrapper packages have been removed. Use the unified ccusage <agent> ... commands in docs, tests, and examples, and do not reintroduce wrapper commands such as ccusage-codex, ccusage-opencode, ccusage-amp, or ccusage-pi.

Cost modes:

• auto - prefer pre-calculated costUSD when available, otherwise calculate from tokens.
• calculate - calculate from token counts and ignore pre-calculated costs.
• display - use pre-calculated costs and show 0 when missing.

Pricing generally comes from LiteLLM's model_prices_and_context_window.json. The --offline flag forces embedded pricing snapshots where supported.

Agent Details

Read only the relevant reference before changing parser behavior, token mappings, data directory detection, fallback models, or agent-specific CLI flags:

• Claude Code: references/claude-code.md
• Codex: references/codex.md
• OpenCode: references/opencode.md
• Amp: references/amp.md
• pi-agent: references/pi-agent.md

Implementation Notes

• Treat Codex, OpenCode, Amp, and pi-agent as agent subcommands under the unified ccusage CLI.
• Reuse shared Rust modules for rendering, table layout, logging, date formatting, progress, pricing, file walking, and aggregation where appropriate.
• Keep command names and flag semantics aligned unless the source data forces a difference.
• Internal workspace runtime libraries for bundled/private packages belong in devDependencies.

Adapter Layout

New or migrated runtime agent implementations belong under rust/crates/ccusage/src/adapter/<agent>/. Keep agent-specific code there. Split files by responsibility when the implementation grows:

• mod.rs - public adapter surface and command wiring.
• paths.rs - environment variables, default directories, and path discovery.
• parser.rs - raw record parsing and token/model mapping.
• loader.rs - file walking, SQLite reads, dedupe, and date filtering entry points.
• report.rs - JSON/table row shaping when agent-specific.
• types.rs - source-local types when they are not shared outside the adapter.

Use apps/ccusage/src only for the remaining npm launcher, package scripts, schema artifacts, and benchmarks. Do not add new TypeScript runtime adapter logic unless the user explicitly scopes work to the package layer.

When moving an existing loader into an adapter, update internal imports to the adapter path instead of adding compatibility re-export shims. Keep old root-level modules only when they are part of the package's declared public exports or are dedicated packaging entries.

Use shared ccusage foundation for rendering, table layout, logging, date formatting, progress, pricing fetcher lifecycle, JSONL walking, SQLite loading, dedupe, and aggregation wherever the source data permits. Agent adapters should mainly own source-specific log discovery, parsing, token mapping, model mapping, and source-specific metadata.

Treat "same foundation as Claude" as more than shared file walking. JSONL adapters should use shared scanning helpers when stable row markers exist, and high-volume paths should avoid returning large intermediate object vectors when worker-side aggregation or typed transfer payloads can preserve the same output.

When several adapters expose the same raw-log shape, prefer a small shared Rust helper over duplicating period/session aggregation. Keep highly specialized loaders such as Codex parsing separate when their file format or pricing semantics require it.

Adapter Migration Checklist

For each migrated or new agent:

• Put all source-specific runtime logic under rust/crates/ccusage/src/adapter/<agent>/.
• Implement fast detection that short-circuits once a usable source file is found.
• Use shared file walking, JSONL scanning where applicable, SQLite loading, logging, pricing fetcher lifecycle, date formatting, table rendering, and all-agent aggregation.
• Keep adapter code responsible for source paths, raw parsing, token mapping, model mapping, source metadata, and agent-specific pricing.
• Add Rust fixture-backed tests for path discovery, parser behavior, aggregation totals, and important legacy compatibility.
• Add skipped local-data smoke tests when real user log directories are useful for catching schema drift.
• Add or update CLI JSON assertions and table snapshots for affected report modes.
• Audit every user-facing entrypoint that lists supported agents, commands, options, report modes, or examples. Update the root README.md, apps/ccusage/README.md, docs/guide/, and VitePress navigation when the adapter changes what users can run or discover. Use the ccusage-docs skill for docs conventions.
• When adding a new agent guide, include README usage examples, docs guide content, related guide links, and VitePress navigation in the same change unless the user explicitly scopes documentation out.
• Validate terminal output with cmux-debug when changing table layout, progress, spinners, or responsive behavior.
• Benchmark affected agents against main or the previous tag, and record whether JSON output still matches for the comparison window.