AI agent skill · by @ccusage

Rust

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.

Archived 2026-10-23 · Source updated 2026-10-12. Check the original repository for the latest version.

SKILL.md instructions

# 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`.