ccaudit CLAUDE.md

CLAUDE.md

Project memory for AI coding assistants working in this repo. For end-user docs see README.md; release notes in CHANGELOG.md; JSON envelope reference in docs/JSON-SCHEMA.md.

Project

ccaudit is a CLI that audits Claude Code's ghost inventory: agents, skills, MCP servers, commands, hooks, and memory files defined once but rarely invoked. It quantifies the per-session token cost and ships one reversible command to archive ghosts. Companion tool to ccusage.

Tech stack

TypeScript / Node ≥20 / pnpm 10 monorepo. CLI built on gunshi. JSON validation via valibot.safeParse. Globbing via tinyglobby. Tables via cli-table3. Bundled via tsdown (Rolldown). Tested via vitest 4.1. Formatted via oxfmt. Linted via eslint 9 flat config. Zero runtime dependencies: everything is devDependencies and bundled into dist/.

Monorepo layout

apps/ccaudit/        CLI entry, subcommand wrappers, integration tests, dist/ bundle
packages/internal/   Domain code: scanner, remediation, framework, token, history, report
packages/terminal/   Terminal renderers (tables, panels, color)
docs/                User-facing reference docs

Commands

pnpm verify         # full gate: typecheck + lint + build + test + format:check
pnpm test           # vitest only (TZ=UTC enforced, no watch in CI)
pnpm build          # tsdown bundle into apps/ccaudit/dist/
pnpm format         # oxfmt --write .

CI is tag-triggered only. Pre-push hook runs format + lint (not tests). Run pnpm verify locally before opening a PR.

Conventions

• In-source tests belong in if (import.meta.vitest) { ... } blocks at the bottom of source files. Integration tests live under apps/ccaudit/src/__tests__/. The bundler strips in-source tests via define: { 'import.meta.vitest': 'undefined' }.
• Result types: prefer @praha/byethrow Result over throwing across module boundaries.
• Paths: use forward slashes in glob patterns (tinyglobby normalizes). os.homedir() for home expansion. Never hard-code /Users/... or /home/....
• Time: ISO 8601 UTC strings (new Date().toISOString()). Tests run with TZ=UTC.
• Errors at boundaries: at the outermost layer (CLI command, history writer), catch and degrade gracefully. Inside the domain, propagate via Result.
• Frontmatter writes on memory files: always go through writeFilePreservingMtime from packages/internal/src/remediation/fs-utils.ts. A bare fs.writeFile destroys the staleness signal.