claude-code-usage-analyzer: Instructions file for Claude Code

Claude Coding Rules

Overview

Coding standards and best practices for all code in this repository. These rules prioritize maintainability, simplicity, and modern Python development.

Core Principles

• Write code with minimal complexity for maximum maintainability and clarity.
• Choose simple, readable solutions over clever or complex implementations.
• Prioritize code that any team member can confidently understand, modify, and debug.

What this repository is

A command-line usage-and-cost analysis tool for Claude Code. It shells out to the ccusage npm CLI to gather aggregated usage data, downloads a pricing table from LiteLLM over HTTPS, computes statistics, and writes a JSON analysis, a Markdown report, and a self-contained HTML dashboard, plus optional PNG charts. There is no web server or database. Pricing is resolved dynamically from LiteLLM against whatever models appear in the data, so new models work with no code change.

Technology Stack

Package Management

• Always use uv and pyproject.toml for package management. Never use pip directly.

Libraries

• The core tool depends only on the Python standard library, so it runs with uv run and no install step. Charts are an optional extra (matplotlib, numpy) declared under [project.optional-dependencies].
• Formatting/Linting: use ruff for both linting and formatting.
• Type Checking: use mypy.
• Security: use bandit.
• Testing: use pytest with pytest-cov.
• Do not add a runtime dependency where the standard library will do.

Code Style

Function Structure

• Internal/private functions start with an underscore (_) and are placed at the top of the file, followed by public functions.
• Keep functions modular -- no more than 30-50 lines.
• Two blank lines between function definitions; one parameter per line for readability.

Type Annotations (Python 3.10+)

Use modern PEP 604/585 syntax -- built-in generics and | unions -- instead of importing from typing.