Complete technical reference for packx v4.x — the AI context bundler.
File Discovery Pipeline
Processing Order
- Candidate discovery — by extension + glob patterns + git mode
- Ignore filtering —
.gitignore(traversed upward) +.packignore+ default ignores - Content filtering — search strings (
-s) and exclusion strings (-S) - Size filtering — skip files > 10MB silently
- Binary detection — first 512 bytes checked for null bytes; >10% non-printable = binary → skip
- Pattern matching — minimatch for
-i/-xpatterns - Token counting — js-tiktoken (GPT tokenizer), fallback:
text.length / 4
Auto-Excluded Directories & Files (DEFAULT_IGNORE_PATTERNS)
**/node_modules/** **/.git/** **/dist/**
**/build/** **/.next/** **/coverage/**
**/.cache/** **/tmp/** **/temp/**
**/*.log **/.DS_Store **/Thumbs.db
**/package-lock.json **/yarn.lock **/pnpm-lock.yaml
**/bun.lockb **/bun.lock **/Gemfile.lock
**/Cargo.lock **/poetry.lock **/Pipfile.lock
**/composer.lock
Default Extensions (no -i flag)
Languages: js, jsx, ts, tsx, mjs, cjs, py, rb, go, java, cpp, c, h, rs, swift, kt, scala, php Web Frameworks: vue, svelte, astro Styles: css, scss, less Config: json, yaml, yml, toml, xml Documentation: md, mdx, txt Scripts: sh, bash, zsh, fish Data: sql, graphql, gql
The -i Include Glob: Critical Behavior
The -i flag requires **/ prefix for extension matching:
# CORRECT — always use **/ prefix for extensions
packx --limit 900k -i "**/*.ts" --preview
packx --limit 900k -i "src/**/*.tsx" --preview
# WRONG — bare *.ext does NOT match
packx --limit 900k -i "*.ts" --preview # Matches nothing!
Directory-style includes (-i "src/") work without **/.
The -x exclude flag is more lenient — "*.test.*" works for excludes.
Token Budget (--limit)
Oracle browser-mode packx workflows now target up to ~900k tokens. The previous ~49k target is obsolete; keep bundles rich unless the question is narrow or the user asks for a smaller context.
k vs K Notation
| Notation | Multiplier | Example | Exact Result |
|---|---|---|---|
lowercase k |
× 1,000 (SI) | 900k |
900,000 tokens |
UPPERCASE K |
× 1,024 (binary) | 32K |
32,768 tokens |
| No suffix | Raw number | 50000 |
50,000 tokens |
| Decimal | Works with both | 1.5k |
1,500 tokens |
Token Counting
- Uses
js-tiktoken(OpenAI's tokenizer) for accurate GPT token counts - Fallback:
Math.round(text.length / 4)if tiktoken fails - Counts are cached per-file in
.packx_cache/cache.json
Interactive Mode + Limit
When --limit is used with interactive mode (-I), a visual progress bar shows real-time token consumption as files are selected/deselected.
Import Following (--follow-imports)
Supported Import Styles
- ES6:
import ... from "..."andexport ... from "..." - CommonJS:
require("...") - Dynamic:
import("...")
Resolution
- Only follows relative imports (
./or../), nevernode_modules - Max depth: 10 levels
- Circular dependencies handled via visited-path Set
Resolution extensions tried (in order):
"", .ts, .tsx, .js, .jsx, .mts, .mjs, .cts, .cjs, .json
Extension mappings:
.js→ tries.ts,.tsx,.js,.jsx.mjs→ tries.mts,.mjs.cjs→ tries.cts,.cjs.jsx→ tries.tsx,.jsx
Index files for directory imports:
index.ts, index.tsx, index.js, index.jsx, index.mts, index.mjs
Parse Strategy
- Tree-sitter AST parsing first (for .ts, .js, etc.)
- Regex fallback if AST unavailable:
import\s+(?:[\w\s{},*]+\s+from\s+)?["']([^"']+)["']
export\s+(?:[\w\s{},*]+\s+from\s+)?["']([^"']+)["']
require\s*\(\s*["']([^"']+)["']\s*\)
import\s*\(\s*["']([^"']+)["']\s*\)
Related Files (-r / --related)
Extracts base name (before first dot after name), then finds all files in the same directory with the same core name:
Button.tsx→ findsButton.test.tsx,Button.stories.tsx,Button.module.css, etc.- Recursively expands matched files with their related files
Comment Stripping (--strip-comments)
AST-Based (primary — tree-sitter)
- Language-specific tree-sitter grammar
- Collects all comment nodes from AST
- Removes entire lines if only whitespace surrounds the comment
- Otherwise removes inline comments preserving code
Regex Fallback (by language family)
| Language Family | Languages | Patterns |
|---|---|---|
| C-style | js, jsx, ts, tsx, java, c, cpp, go, rust, swift, php, css, scss, less | /* ... */ and // ... |
| Hash-style | py, rb, sh, bash, zsh, yaml, yml, toml | # ... |
| HTML-style | html, xml, md, mdx, vue, svelte, astro | <!-- ... --> |
| Lua-style | lua, sql | -- ... |
All regex fallbacks preserve quoted strings.
Context Lines (-l / --lines)
Smart Context Mode
- Extracts N lines around each match
- Tries to expand to complete code blocks using tree-sitter AST
- Falls back to indent-based block detection
- Max expansion:
contextLines × 2
Overlap Merging
Windows sorted by start line, then merged if window.startLine <= current.endLine + 1. Matches from overlapping regions are combined.
Indent-Based Block Detection (fallback)
- Scans upward for lower indentation level (block openers:
{,:, function/class/if keywords) - Scans downward for closing braces or lower indentation
Git Integration
--staged
git diff --cached --name-only --diff-filter=ACMR
(Added, Copied, Modified, Renamed)
--dirty
git diff --name-only --diff-filter=ACMR # modified
git ls-files --others --exclude-standard # untracked
Returns deduplicated union.
--diff
git merge-base <branch> HEAD # find common ancestor
git diff --name-only --diff-filter=ACMR <base> # diff from there
Falls back to branch name directly if merge-base fails.
These three flags are mutually exclusive.
Output Formats
XML (default)
<file_summary>
<purpose>...</purpose>
</file_summary>
<directory_structure>file paths</directory_structure>
<files>
<file path="src/auth.ts" matches="3" windows="2">
...content or context windows...
</file>
</files>
Markdown (-f markdown)
# Packx Output
This file contains X filtered files...
## Files
### src/auth.ts (3 matches)
```ts
...content...
```
JSONL (-f jsonl)
One JSON object per line:
{"path":"src/auth.ts","content":"...","tokens":150,"matches":[{"line":10,"column":5,"match":"..."}]}
Plain (-f plain)
Like markdown but simpler header, no fenced blocks.
Caching (.packx_cache/)
Cache file: .packx_cache/cache.json (version 2)
Entry structure:
{
"mtime": 1702000000000,
"size": 4096,
"contentHash": "sha256hex...",
"isBinary": false,
"tokens": 342
}
Validation strategy:
- mtime AND size match → cache hit (fast path)
- Size differs → cache miss
- mtime differs but size same → compute SHA-256 → compare hash
- Hash matches → update mtime, keep entry
- Hash differs → cache miss, recompute
Bypass: --no-cache
Prune: Stale entries for deleted files cleaned on next run
Bundles (-b / --bundle)
- Stored in
.pack/bundles/directory - Extensions:
.bundle,.pack,.txt - Format: gitignore-style patterns (one per line,
#for comments) - In interactive mode: loads bundles as pre-selected file sets
- With
-b name: loads non-interactively and outputs directly
Interactive Mode (-I)
Default since v4.7.0 — running packx with no output flags enters interactive mode.
Features
- Tree-based file browser with token counts
- Live preview pane with syntax highlighting
- Token budget progress bar (
--limit) - Git status decorators:
[M]Modified,[A]Added,[?]Untracked .packignorefiles shown but start unselected- Fuzzy search filtering
- Visual dependency graph
Key Bindings
| Key | Action |
|---|---|
j/k or ↑/↓ |
Navigate |
Space |
Toggle selection |
Shift+Space / v |
Range selection (anchor) |
Tab |
Toggle preview focus |
PgUp/PgDn |
Scroll preview |
g/G |
Jump to top/bottom |
h/l |
Collapse/expand folder |
o |
Open in editor |
d |
Resolve dependencies |
c |
Toggle comment stripping |
+/- |
Adjust context lines |
x |
Banish to .packignore |
? |
Full-screen help overlay |
Enter |
Confirm selection |
After Selection
- Option to save glob pattern to
.packignore - Option to save selection as named bundle
- Choose output: clipboard, file, stdout, or skip
Watch Mode (-w)
- Uses
chokidarwith 150ms debounce - File stabilization: 100ms threshold, 50ms poll interval
- Watches:
change,add,unlinkevents - Requires
--outputor--copy - Cannot combine with
-I(interactive) - Ctrl+C for graceful shutdown
--instruction and --prompt
| Flag | Position | Input |
|---|---|---|
--instruction <file> |
Prepends to TOP of output | File path |
--prompt <text> / -p |
Appends to END of output | Inline text |
--preview Mode
- Dry run: shows matching files without packing content
- Displays up to 50 files (rest counted as "... and X more")
- Shows file count total
- Useful for testing filter combinations before committing
--explain Mode
- Full dry run with detailed logging
- Shows: resolved config options, file discovery process, pattern matching, what would be included
- No output generated
--skeleton Mode (v4.15.0+)
- AST-based: strips function bodies to
{ /* ... */ } - Keeps interfaces, type definitions, function signatures
- Great for architecture review at minimal token cost
Secret Redaction (v4.15.0+)
Automatically detects and redacts 22 pattern types:
AWS keys, GitHub tokens, JWTs, database connection strings, API keys, private keys, etc.
Replaces matches with <REDACTED:TYPE>.
--minify Behavior
content.split('\n')
.map(line => line.trim())
.filter(line => line.length > 0)
.join('\n')
Removes empty lines, trims whitespace per line.
Token Splitting (--max-tokens / -M)
- Reserves ~50 tokens per chunk for headers/footers
- Files are never split mid-file
- A single file exceeding the budget is skipped entirely (marked "oversized")
- Creates:
output-1.xml,output-2.xml, etc. - Only chunk 1 copied to clipboard; rest go to files
Concurrency
- Files analyzed in parallel using
p-limit CONCURRENCY_LIMIT = 50- Progress emitted every 50 files or 10% of total
.packignore
- Gitignore syntax (processed by
ignorenpm library) - Auto-loaded from project root
--no-packignoreto disable- In interactive mode: matching files shown but unselected
xhotkey in interactive mode banishes files to.packignore
Positional Path Arguments
packx src/ # Directory → scan root
packx README.md # File → explicit include
packx "**/*.test.ts" # Glob pattern → include pattern
Classification:
- Contains
*,?,[,],{,},!→ treated as glob pattern - Exists as directory → treated as scan root
- Exists as file → treated as explicit file include
Interaction with filters:
- Explicit files +
-ipatterns: must match BOTH - Positional roots: used as starting directories for scanning
- Positional globs: added to include patterns
Gotchas & Edge Cases
| Issue | Detail |
|---|---|
-i "*.ts" matches nothing |
Must use "**/*.ts" with **/ prefix for extensions |
| Interactive is default | Since v4.7.0, bare packx enters interactive mode. Use --no-interactive for scripting |
--stdout disables interactive |
Can't combine --stdout with -I |
--watch + -I incompatible |
Watch requires output target, can't be interactive |
| Files >10MB silently skipped | No warning — use --explain to debug missing files |
Single file > --max-tokens |
Entire file skipped, not split |
| Clipboard: only chunk 1 | When splitting, remaining chunks go to files |
| Binary files silently skipped | >10% non-printable chars in first 512 bytes |
Operational boundaries
- Processing order, cache format, secret-detector coverage, AST fallbacks, and numeric limits describe the referenced implementation. Confirm the installed version; stripped or minified context may omit semantics needed for the question.