Architecture

ctxpack walks a directory honoring ignore rules, reads each file, redacts secrets, and packs files into one output until a token budget is reached.

flowchart LR
  ROOT["directory"] --> W["walkFiles<br/>(ignore rules + .gitignore)"]
  W --> RD["read file"]
  RD --> BIN{"binary / too big?"}
  BIN -- yes --> SK["skip"]
  BIN -- no --> RE["redactSecrets"]
  RE --> B{"within token budget?"}
  B -- no --> SK
  B -- yes --> ADD["append block"]
  ADD --> OUT["Markdown / XML + file tree"]

Module map

Module	Responsibility
ignore.ts	Compile .gitignore-style patterns into a matcher
walk.ts	Recursively list included files (prunes ignored dirs)
redact.ts	Replace common secrets with placeholders
tokens.ts	Estimate tokens (~4 chars each)
pack.ts	Read, redact, budget and assemble the output

Design principles

• Safe by default — secrets are redacted and binaries/oversized files skipped unless you opt out.
• Budget-aware — inclusion stops at the estimated token limit; skipped files are reported.
• Deterministic & offline — pure functions over the filesystem, no network, zero dependencies.
• Honest scope — the ignore matcher is a common .gitignore subset, documented as such.