claude-code-types AGENTS.md

claude-code-types

Types-only npm package for Claude Code chat history JSONL files.

Project Structure

index.d.ts                      # All type definitions (the package payload)
scripts/scan-transcripts.ts     # Coverage scanner: finds JSONL values index.d.ts doesn't model yet
scripts/lib/extract-types.ts    # Parses index.d.ts (TS compiler API) — single source of truth for known values
test/smoke.local.test.ts        # Smoke test against real JSONL files (KNOWN_TYPES derived from index.d.ts)
package.json                    # types field, no main/module
tsconfig.json                   # Strict TS config for validation
scripts/tsconfig.json           # Strict TS config for the scanner + test
CHANGELOG.md                    # Keep a Changelog format
.github/workflows/ci.yml       # CI: typecheck + verify docs freshness on PRs and main pushes
.github/workflows/auto-tag.yml # Auto-creates v* tag from package.json on main push
.github/workflows/publish.yml  # Single job: validate → npm publish → GitHub Release, on v* tag push

Commands

• npm run typecheck — Validate index.d.ts compiles under strict mode
• npm run typecheck:scripts — Typecheck the scanner and test under strict mode
• npm run scan — Scan ~/.claude/projects/ and report every discriminator/union value and entry field not yet covered by index.d.ts, with counts and samples. Exits non-zero when anything is uncovered. Run this first when refreshing types. Flags: --dir <path>, --json, --no-samples.
• npm test — Run smoke tests (requires ~/.claude/projects/ to contain JSONL files)

Refreshing types from logs

scripts/lib/extract-types.ts parses index.d.ts as the source of truth, so the scanner and smoke test automatically track whatever the union declares — never hardcode a parallel list. To refresh:

1. npm run scan — lists new entry types, system subtypes, attachment types, tools, models, stop reasons, permission modes, queue ops, cache-miss reasons, content-block/citation types, and undeclared top-level fields per entry type. Each new value comes with a count and a sample JSON line.
2. For each reported value, add it to the location named in the report (e.g. a new Attachment member + interface, or a field on EntryBase). For new entry/attachment interfaces, use the sample to type the payload.
3. Re-run npm run scan until it reports full coverage, then npm run typecheck && npm test.