CcGlanceLine: Instructions file for Claude Code

CLAUDE.md

Guidance for working in this repo. See docs/development.md (and its zh-CN counterpart) for deeper build/test/cache internals.

What this is

@cxmyu/ccglance — a Claude Code status-line renderer. Claude Code pipes JSON on stdin per redraw; dist/cli.js renders one line to stdout. Zero runtime dependencies; the CLI is spawned fresh on every redraw, so cold-start latency matters.

Core rules

• src/ is the only source of truth. Never hand-edit dist/ — it is gitignored and rebuilt by npm run build (and by npm ci via prepare).
• Keep the style fixed and built-in: no user config loader, no external style file, no runtime style discovery.
• Keep runtime dependencies at zero. New deps must be build-time only.
• Verify local changes with npm run preview / node dist/cli.js, never a bare ccglance (that is the published global install on PATH).

Build / test

npm run typecheck   # tsc --noEmit (strict)
npm run build       # clean + compile src/ -> dist/
npm test            # build + node:test (fixtures / snapshots / smoke)
npm run preview     # render this repo's dist/

Tests and benchmarks isolate CLAUDE_CONFIG_DIR to a temp dir; they never touch the real ~/.claude/ccglance/ cache.

Background refresh (Windows footgun)

Git/version refreshes queue during render and flush after stdout as a single detached helper (dist/runtime/bg.js). On Windows the helper MUST be spawned as spawn(node, [...], { detached: true, windowsHide: true }) — spawning Node directly, never through a cmd/start trampoline. detached maps to DETACHED_PROCESS (no console allocated → no black window flash); a cmd start trampoline flashes a window on every cold refresh (the 1.1.0 regression fixed in 1.1.1). Dropping detached makes the helper die when the parent exits, so the cache never gets written. See src/runtime/refresh.ts.

Release process (publish a new version)

Publishing is done through a GitHub Release, which triggers .github/workflows/publish.yml (release: published). CI runs npm ci → npm run typecheck → npm test → npm publish --provenance --access public (OIDC provenance; NPM_TOKEN secret must bypass 2FA). Do not npm publish locally.