ts-context-bundle

Generate deterministic LLM context bundles from TypeScript entrypoints. The CLI emits a single Markdown file that lists included files and embeds each file’s contents in fenced code blocks. Two inclusion strategies are supported:

• closure: walk the static import/export graph (default)
• bundle: use esbuild tree-shaking to get the actual input file set
• both: emit both sections and show differences

Install

npm i -g ts-context-bundle
# or
pnpm add -g ts-context-bundle

Node.js >= 20 is required.

Usage

ts-context-bundle src/index.ts

ts-context-bundle \
  src/index.ts \
  --entry src/worker.ts \
  --no-enhance \
  --mode bundle \
  --include-bundle-output \
  --out context.md

ts-context-bundle \
  src/index.ts \
  --dir src/features \
  --mode both \
  --depth 2 \
  --exclude "**/generated/**" \
  --json

CLI Flags

• <entry-file> (required, positional): primary TypeScript entry file.
• --entry <file> (repeatable): additional TypeScript entry files.
• --dir <path> (repeatable): directory mode. Every .ts / .tsx (and optional .d.ts) file in the directory becomes an entrypoint, then results are unioned and deduped.
• --tsconfig <path>: defaults to nearest tsconfig.json found by walking upward from cwd.
• --out <file>: default context.md.
• --mode closure|bundle|both: default closure.
• --depth <n>: default 2 (closure only).
• --exclude <glob> (repeatable): overrides default excludes.
• --include-node-modules: include resolved files under node_modules.
• --max-file-kb <n>: default 512 (large files are truncated, not skipped).
• --max-total-kb <n>: default 8192 (budget for included content).
• --include-dts: include .d.ts files.
• --include-bundle-output: append bundled JS (bundle/both modes).
• --enhance / --no-enhance: run an AI file-list refinement pass via codex CLI (codex-5.3-spark). Enabled by default when codex is installed.
• --quiet: suppress non-error logging.
• --json: emit context.stats.json next to the output file.

Default exclude globs (unless --exclude is provided):

• **/node_modules/**
• **/dist/**
• **/build/**
• **/.next/**
• **/coverage/**
• **/*.map
• **/*.snap

Closure vs Bundle

• closure follows import/export declarations and import("...") with string literals. It respects tsconfig baseUrl and paths mappings.
• bundle runs esbuild with tree-shaking and uses the metafile to determine the actual input files.

Output format

The Markdown bundle:

1. A header block with the command, version, mode, depth, tsconfig, and counts.
2. A deterministic list of included files.
3. Each file’s contents in fenced code blocks, separated by ---.

When enhancement adds files, those files are explicitly labeled as [AI-added context] in the file list and in each file section heading note.

Large files (over --max-file-kb) are truncated to the first 200 lines and last 50 lines with a note. If --max-total-kb is exceeded, the tool stops adding files and records a note about skipped files.

JSON stats

When --json is provided, a context.stats.json file is written next to the output Markdown. It contains:

• includedFiles: { path, bytes, truncated, reasonIfSkipped }
• skippedFiles: { path, reason, detail? }
• totals: counts and included byte totals
• mode, tsconfig, and depth metadata

For mode=both, the JSON contains closure and bundle sections plus a diff summary.

Assumptions and behavior notes

• Directory paths are only accepted via --dir. Passing a directory via <entry-file> or --entry is a usage error.
• --dir mode treats each matched TypeScript file in that directory tree as an entrypoint.
• Explicit entry files are always included, even if they match an exclude glob.
• --exclude replaces the default excludes entirely.
• Non-TypeScript files are skipped. Only .ts, .tsx, and optional .d.ts are supported.
• Enhancement mode asks Codex to prune noisy files and optionally add missing TypeScript files for debugging context. If codex CLI is not installed, enhancement is skipped automatically.
• Bundle mode stubs common asset imports (for example .png, .svg, fonts, and media), and those files are not included in the context.
• When --include-bundle-output is used with multiple entrypoints, outputs are concatenated in a single section with file markers.

Troubleshooting: “Why wasn’t a file included?”

Common reasons:

• The import was unresolved (typo, missing extension, or not covered by tsconfig paths).
• The file is under node_modules and --include-node-modules was not set.
• The file matched an exclude glob.
• The file was beyond the closure --depth.
• The file extension is not supported.
• The --max-total-kb budget was exceeded.