# Ccusage Development

> Guides ccusage monorepo development. Use when editing packages, docs, shared configuration, bundled CLI packaging, dependencies, exports, or validation commands.

- Skill: `tuyv/ccusage-development` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add tuyv/ccusage-development`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tuyv/ccusage-development/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tuyv (https://skillmd.com/u/tuyv)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tuyv/ccusage-development

---


# 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 library
- `docs/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:

```sh
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 matching `flake.lock` update 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/skills` are generated by `agent-skills-nix` from `.agents/skills`; do not edit or commit `.claude/skills`.

## Code Style

- For Rust CLI work, use the `ccusage-rust` skill before editing `rust/crates/**`,
  native packaging behavior, or Rust pricing embedding. Use
  `ccusage-rust-profile` for Rust performance work.
- Keep Rust modules small and responsibility-focused. Prefer `pub(crate)` over
  broader visibility, avoid unnecessary `String` cloning in hot paths, and put
  unit tests beside the module they exercise.
- For TypeScript package/tooling code, use the `ccusage-typescript` skill and
  `typescript-style` before editing. Keep `satisfies` and `as const satisfies`
  guidance 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 `devDependencies` for bundled/private packages.

## Post-Change Workflow

After code changes, run formatting first when formatting may apply because it mutates files:

```sh
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:

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