tuyv ccusage Development
Repository Shape
This is a monorepo. Check the nearest package-specific CLAUDE.md before editing a package:
apps/ccusage/CLAUDE.md- main Claude Code usage CLI and librarydocs/CLAUDE.md- VitePress documentation site
The production CLI implementation is Rust-first under rust/crates/ccusage.
The apps/ccusage package now mainly provides npm metadata, a TypeScript bin
launcher, generated schema artifacts, benchmarks, and release packaging.
The canonical user-facing command is ccusage with agent subcommands:
ccusage daily
ccusage codex daily
ccusage opencode daily
ccusage amp daily
ccusage pi daily
Standalone agent wrapper packages have been removed. Prefer ccusage <agent> ... in docs, tests, examples, and new behavior, and do not reintroduce wrapper commands such as ccusage-codex, ccusage-opencode, ccusage-amp, or ccusage-pi.
Agent implementations live in the Rust CLI unless the work is specifically about
the remaining TypeScript package surface. Treat package runtime libraries as
bundled assets: add dependencies to each package's devDependencies unless the
user explicitly asks otherwise.
Common Commands
Use root commands unless a narrower package command is more appropriate. Read references/commands.md for root and main CLI command examples.
LOG_LEVEL controls logging verbosity from 0 silent through 5 trace.
Environment and Tooling
This repo requires the Nix flake development environment with nix-direnv for contributor setup. Use the activated direnv shell so the pinned Rust, Bun, pnpm, git hooks, agent skills, and repository CLIs are all on PATH.
Use the activated direnv environment for normal work. For non-interactive one-offs from outside the shell, prefer direnv exec . <command>.
Tools are managed by flake.nix and package.json. Use comma or nix run for one-off investigation when appropriate, but add recurring project tools to the repo instead:
- Add system/dev-shell CLIs to
flake.nix, and include the matchingflake.lockupdate in the same commit. - Add JavaScript/TypeScript tools and scripts to
package.json, and include the matching lockfile update in the same commit. - Keep each tool addition independently revertable; do not commit a lockfile update without the manifest change that explains it.
- Project-local Claude skills under
.claude/skillsare generated byagent-skills-nixfrom.agents/skills; do not edit or commit.claude/skills.
Code Style
- For Rust CLI work, use the
ccusage-rustskill before editingrust/crates/**, native packaging behavior, or Rust pricing embedding. Useccusage-rust-profilefor Rust performance work. - Keep Rust modules small and responsibility-focused. Prefer
pub(crate)over broader visibility, avoid unnecessaryStringcloning in hot paths, and put unit tests beside the module they exercise. - For TypeScript package/tooling code, use the
ccusage-typescriptskill andtypescript-stylebefore editing. Keepsatisfiesandas const satisfiesguidance there instead of mixing TypeScript details into Rust workflow rules. - Only export constants, functions, and types used by other modules.
- Keep internal-only files and helpers private where possible.
- Dependency additions go in
devDependenciesfor bundled/private packages.
Post-Change Workflow
After code changes, run formatting first when formatting may apply because it mutates files:
pnpm run format
Git hooks and CI cover the standard validation path. Run typecheck and tests manually when the change touches behavior, types, package code, or when hooks/CI do not cover the edited files:
pnpm typecheck
pnpm run test
For package-local work, run the narrower package scripts during iteration when they are faster, then run the root workflow before finishing.
Performance and CLI Output
Use ccusage-rust-profile for native CLI performance optimization, Rust
profiling, hyperfine A/B comparisons, and branch-vs-main profiling. Use
bun-cpu-profile for TypeScript launcher, benchmark, or packaging scripts.
Use the cmux-debug skill when validating terminal rendering, responsive tables, long-running CLI output, or output that depends on real terminal geometry.
Commit and PR Names
Use the commit skill for commit structure, Conventional Commits, scope selection, and detailed commit message requirements.
Use the create-pr skill after opening a PR or pushing follow-up commits so AI and human review comments are requested, inspected, answered, and incorporated through small revertible commits.