AGENTS.md

AGENTS.md (ccusage-hourly)

This repo is a pnpm monorepo fork of ryoppippi/ccusage, with an added hourly usage report (see apps/ccusage).

For deeper, package-specific guidance, also read:

• CLAUDE.md (repo-wide)
• apps/*/CLAUDE.md and packages/*/CLAUDE.md (package-level)

Quick Start

• Install deps: pnpm -w install
• Run all tests: pnpm -w test
• Typecheck: pnpm -w typecheck
• Lint: pnpm -w lint
• Format (writes): pnpm -w format

If you merged/upgraded dependencies and commands fail with missing binaries, refresh workspace links:

• pnpm -r install --force

Repo Map

• apps/ccusage/: main Claude Code usage CLI + library (includes hourly)
• apps/codex/: OpenAI Codex usage CLI
• apps/mcp/: MCP server exposing usage reports
• apps/opencode/, apps/pi/, apps/amp/: additional CLIs
• packages/internal/: shared pricing/logging/format utilities
• packages/terminal/: table + terminal formatting utilities
• docs/: VitePress documentation site

Code Rules (Parity + Safety)

• Apps are bundled CLIs: keep runtime deps in each app’s devDependencies so the bundler owns the runtime payload.
• No console.log: use the package logger modules instead (see apps/*/src/logger.ts).
• Local imports use .ts: e.g. import { x } from "./util.ts".
• Vitest is in-source: tests live in if (import.meta.vitest != null) blocks; globals are enabled (describe/it/expect).
• Never use dynamic await import() (especially in tests).

Upstream Sync

Remotes typically use:

• origin: the fork
• upstream: ryoppippi/ccusage

Common update flow:

• git fetch upstream
• git merge upstream/main