ccusage Rust
The native Rust CLI is the production implementation. rust/adapters/<agent> holds
one crate per usage source; rust/crates holds everything not tied to a single
source.
Read before editing:
rust/adapters/README.mdandrust/adapters/AGENTS.md— adapter architecture, the shared-vs-source boundary, module shape, and the checklist for adding an agent.rust/adapters/opencode/src/is a compact worked example.- the crate's own
README.md— what it owns and which Crane artifact layer it builds in, which is what a change to it costs. Some adapters add asrc/README.mddescribing the source format.
Two boundaries the crate names hide: ccusage-cli holds the plain
argument types while ccusage-cli-parser holds the parser, help renderer, and
embedded help JSON that only the binary depends on; rust/crates/ccusage stays
thin on purpose, holding dispatch plus the commands that are not an agent report.
Behavior two adapters need moves into ccusage-adapter-common
(rust/adapters/common) instead of becoming an adapter-to-adapter dependency.
For splitting large modules or hunting duplication, use the reduce-similarities
skill.
Behavior Parity
Preserve existing Rust behavior unless the user explicitly scopes a behavior
change: report semantics, JSON fields, table columns, progress and spinner text,
agent grouping, date filtering, --offline, CLAUDE_CONFIG_DIR, and
source-specific environment variables.
origin/main no longer contains the TypeScript adapters. When porting historical
behavior, compare against a commit that still has them
(git log -1 -- apps/ccusage/src/adapter). Fix the comparison window — current
main, a previous release, or that pinned commit — before changing behavior.
Visibility
In this workspace pub is only for what another crate actually uses; everything
else is pub(crate), including items other modules in the same crate reach
through a module chain.
just hawk reports the difference, and nix flake check gates on the same thing
through checks.<system>.ccusage-hawk. When a finding looks wrong, check
rust/hawk.toml for a missing shipped entry point before narrowing anything;
adding --fix to the underlying cargo hawk check applies the narrowing.
hawk only runs on the toolchain it was built against, so rust-toolchain.toml and
nix/cargo-hawk.nix move together — that file's header explains the pinning and
lists the hashes a version bump has to change.
https://github.com/astral-sh/hawk
Pricing Embedding
Two snapshots ship inside the binary, both fed by pinned flake inputs and loaded
by rust/crates/ccusage-core/src/pricing.rs;
rust/crates/ccusage-core/README.md and its build.rs cover the build-time half.
LiteLLM is the primary table. It is compacted into OUT_DIR at build time and
never committed: Nix builds and the dev shell hand build.rs the locked snapshot
through CCUSAGE_PRICING_JSON_PATH, and the off-by-default
fetch-litellm-pricing feature downloads it instead for plain cargo build on
platforms Nix cannot target. Keep it off by default — its rustls stack is the most
expensive build-dependency in the workspace. just update-litellm-pricing
re-locks the input and validates.
models.dev is the committed offline fallback:
rust/crates/ccusage-core/src/models-dev-pricing.json and
rust/adapters/codex/src/codex-auto-review-fallbacks.json, both regenerated by
just gen-models-dev-pricing (just update-models-dev-pricing bumps the pinned
input first). rust/crates/ccusage-core/src/fast-multiplier-overrides.json sits
beside them but is hand-maintained.
Filtering and compacting belong in build.rs, so runtime code loads the generated
build-time snapshot first, then built-in model overrides, then a runtime fetch when
not --offline. Cover embedded/offline pricing and context limits with tests.
Validation
Test commands live in the testing skill; performance work and branch-vs-main
comparisons in profile; repo-wide format and check recipes in development.
