CLAUDE.md

Guidance for Claude Code sessions working in this repository.

What ccgraph is

ccgraph is a CLI that analyzes Claude Code session logs for a repository — a token/cost/time leaderboard across sessions, plus a session → tool → file dependency graph. Rust binary crate, edition 2024, licensed MIT-0.

Build / test / lint commands

Green gate: every change must leave fmt / clippy / build / test green before it's considered done. Run all four.

Source file header

Prefix every source file with this header (adapt the comment syntax per language):

// SPDX-License-Identifier: MIT-0
//
//  -- File content -- //
//  one line: what this file is
//
//  -- Dependencies -- //
//  one or two lines: who uses it, what it uses

Keep it to ~4 lines. The header is a // comment, so rustdoc never sees it — the real description belongs in the //! module doc, and duplicating it in both places means two things to keep in sync.

References to anything a reader of the repo alone can't open — design doc §, .local/ paths, task ids — go in the header or a // comment, never in /// docs. ADR numbers are the exception: docs/adr/ is committed, so citing ADR 0004 from a /// doc resolves for everyone. Prefer that over restating a decision's rationale in the code.

Documentation style

Docs explain what the code can't. The signature already states types, ownership, and nullability — don't restate it in prose.

• Write the non-obvious: invariants, sentinels (e.g. f64::INFINITY for zero-input), why an arm is explicit, failure modes a caller must handle.
• Skip restatement: no /// The session's UUID. on session_id: String, and no inline comment narrating the line below it.
• Use # Errors on functions returning Result, and # Panics where a panic is reachable or an unwrap needs justifying. These are the conventional rustdoc headings and clippy can enforce them; Rust has no @param/@return.
• Prefer one dense paragraph over a bulleted restatement of each field.
• src/cli.rs is special: clap prints its /// docs as --help, so write those for end users and document every value-enum variant.

Enabled crate-wide in main.rs: missing_docs, rustdoc::all, clippy::doc_markdown. Deliberately not enabled: clippy::missing_docs_in_private_items — it forces a doc on every field and manufactures restatement.

Module map

Architecture per design doc §4 — one responsibility per module:

Decisions with consequences outside the module that made them are recorded as ADRs in docs/adr/ — pricing (0001), the efficiency metric (0002), the chars/4 context estimate (0003), what makes a signal fire (0004), aggregated graph-node granularity (0005), SVG via the Graphviz dot binary (0006 — superseded; DOT/SVG were replaced by an HTML viewer + JSON), import-edge languages/parsing/resolution (0007), and reading the working tree as-is now for imports (0008). Cite them by number from code rather than restating the rationale inline.

Domain primer

ccgraph reads Claude Code session logs under ~/.claude/projects/<repo-path>/<uuid>.jsonl, where <repo-path> is the absolute repo path with every non-alphanumeric char replaced by - (not just / — . and _ are collapsed too; e.g. /Users/x/my-project → -Users-x-my-project, /Users/x/HR/CV_LdM → -Users-x-HR-CV-LdM). Each session is a UUID-named JSONL file directly inside that directory.

• Records: one JSON object per line; the type field is the discriminant (assistant, user, mode, system, …). assistant entries are the main data source.
• Usage: token counts live at message.usage (input/output/cache tokens).
• Cost: there is no costUSD field — cost is computed from a pricing table keyed by model, not read from the log.
• Synthetic entries: <synthetic> model entries are filtered out.

Full schema: .local/starter-design-doc.md §3. Note that starter doc is a seed, not the per-story authority — the per-story design lives under .local/user-stories/<story>/design-doc.md.