rust

name	rust
description	Guides ccusage Rust implementation work. Use when editing rust/crates or rust/adapters, adapter module layout, crate visibility and hawk findings, embedded pricing, or Rust behavior parity.
paths	["rust/**/*.rs","rust/**/*.toml","rust/**/build.rs"]
globs	rust/**/*.rs,rust/**/*.toml,rust/**/build.rs

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.md and rust/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 a src/README.md describing 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.