# Ccusage Agent Sources > Guides ccusage agent source work for Rust CLI parsers, log paths, token mappings, costs, reports, and adapter command behavior. - Skill: `tuyv/ccusage-agent-sources` (Agent Skill, multi-file: 4 files) - Install (CLI): `npx skillmds@latest add tuyv/ccusage-agent-sources` - Raw SKILL.md: https://api.skillmd.com/api/skills/tuyv/ccusage-agent-sources/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: tuyv (https://skillmd.com/u/tuyv) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tuyv/ccusage-agent-sources --- # ccusage Agent Sources Use this skill when touching data loading, token normalization, cost calculation, or commands for any ccusage agent adapter. ## Shared Report Concepts Reports aggregate raw usage into daily, monthly, session, or billing-block summaries and output either tables or JSON. The canonical command surface is the unified `ccusage` CLI: ```sh ccusage daily ccusage codex daily ccusage opencode daily ccusage amp daily ccusage pi daily ``` Standalone agent wrapper packages have been removed. Use the unified `ccusage ...` commands in docs, tests, and examples, and do not reintroduce wrapper commands such as `ccusage-codex`, `ccusage-opencode`, `ccusage-amp`, or `ccusage-pi`. Cost modes: - `auto` - prefer pre-calculated `costUSD` when available, otherwise calculate from tokens. - `calculate` - calculate from token counts and ignore pre-calculated costs. - `display` - use pre-calculated costs and show `0` when missing. Pricing generally comes from LiteLLM's `model_prices_and_context_window.json`. The `--offline` flag forces embedded pricing snapshots where supported. ## Agent Details Read only the relevant reference before changing parser behavior, token mappings, data directory detection, fallback models, or agent-specific CLI flags: - Claude Code: `references/claude-code.md` - Codex: `references/codex.md` - OpenCode: `references/opencode.md` - Amp: `references/amp.md` - pi-agent: `references/pi-agent.md` ## Implementation Notes - Treat Codex, OpenCode, Amp, and pi-agent as agent subcommands under the unified `ccusage` CLI. - Reuse shared Rust modules for rendering, table layout, logging, date formatting, progress, pricing, file walking, and aggregation where appropriate. - Keep command names and flag semantics aligned unless the source data forces a difference. - Internal workspace runtime libraries for bundled/private packages belong in `devDependencies`. ## Adapter Layout New or migrated runtime agent implementations belong under `rust/crates/ccusage/src/adapter//`. Keep agent-specific code there. Split files by responsibility when the implementation grows: - `mod.rs` - public adapter surface and command wiring. - `paths.rs` - environment variables, default directories, and path discovery. - `parser.rs` - raw record parsing and token/model mapping. - `loader.rs` - file walking, SQLite reads, dedupe, and date filtering entry points. - `report.rs` - JSON/table row shaping when agent-specific. - `types.rs` - source-local types when they are not shared outside the adapter. Use `apps/ccusage/src` only for the remaining npm launcher, package scripts, schema artifacts, and benchmarks. Do not add new TypeScript runtime adapter logic unless the user explicitly scopes work to the package layer. When moving an existing loader into an adapter, update internal imports to the adapter path instead of adding compatibility re-export shims. Keep old root-level modules only when they are part of the package's declared public exports or are dedicated packaging entries. Use shared ccusage foundation for rendering, table layout, logging, date formatting, progress, pricing fetcher lifecycle, JSONL walking, SQLite loading, dedupe, and aggregation wherever the source data permits. Agent adapters should mainly own source-specific log discovery, parsing, token mapping, model mapping, and source-specific metadata. Treat "same foundation as Claude" as more than shared file walking. JSONL adapters should use shared scanning helpers when stable row markers exist, and high-volume paths should avoid returning large intermediate object vectors when worker-side aggregation or typed transfer payloads can preserve the same output. When several adapters expose the same raw-log shape, prefer a small shared Rust helper over duplicating period/session aggregation. Keep highly specialized loaders such as Codex parsing separate when their file format or pricing semantics require it. ## Adapter Migration Checklist For each migrated or new agent: - Put all source-specific runtime logic under `rust/crates/ccusage/src/adapter//`. - Implement fast detection that short-circuits once a usable source file is found. - Use shared file walking, JSONL scanning where applicable, SQLite loading, logging, pricing fetcher lifecycle, date formatting, table rendering, and all-agent aggregation. - Keep adapter code responsible for source paths, raw parsing, token mapping, model mapping, source metadata, and agent-specific pricing. - Add Rust fixture-backed tests for path discovery, parser behavior, aggregation totals, and important legacy compatibility. - Add skipped local-data smoke tests when real user log directories are useful for catching schema drift. - Add or update CLI JSON assertions and table snapshots for affected report modes. - Audit every user-facing entrypoint that lists supported agents, commands, options, report modes, or examples. Update the root `README.md`, `apps/ccusage/README.md`, `docs/guide/`, and VitePress navigation when the adapter changes what users can run or discover. Use the `ccusage-docs` skill for docs conventions. - When adding a new agent guide, include README usage examples, docs guide content, related guide links, and VitePress navigation in the same change unless the user explicitly scopes documentation out. - Validate terminal output with `cmux-debug` when changing table layout, progress, spinners, or responsive behavior. - Benchmark affected agents against main or the previous tag, and record whether JSON output still matches for the comparison window.