Full context-bundling reference: discovery rules, glob traps, token budgets, output formats, filters, and operational caveats.
Packx Quick Reference
Packx (v4.x) is a native AI context bundler. It discovers files, filters by content/type/git-status, strips noise, counts tokens, and outputs in LLM-friendly formats. Since v4.7.0, bare packx with no output flags enters interactive mode — always use --no-interactive for scripting pipelines.
How File Discovery Works
- Candidate discovery — scans directories using glob patterns (ripgrep fast-path when available, Node.js glob fallback)
- Ignore filtering — applies
.gitignore(traversed upward from cwd) +.packignore+ 22 built-in ignore patterns - Include/exclude pattern matching —
-iand-xfilters via minimatch - Content filtering —
-ssearch strings and-Sexclusion strings (up to 50 files in parallel) - Size/binary filtering — skips files >10MB silently; detects binary via first 512 bytes (>10% non-printable = binary)
- Token counting —
js-tiktoken(OpenAI tokenizer), fallback:text.length / 4
Auto-Excluded (always skipped)
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 File Types (when no -i flag)
Code: js, jsx, ts, tsx, mjs, cjs, py, rb, go, java, cpp, c, h, rs, swift, kt, scala, php Web: vue, svelte, astro, css, scss, less Config: json, yaml, yml, toml, xml Docs: md, mdx, txt Scripts: sh, bash, zsh, fish Data: sql, graphql, gql
Critical: -i Glob Requires **/ Prefix
# CORRECT — always use **/ prefix for extension globs
packx --limit 900k -i "**/*.ts" --preview
packx --limit 900k -i "src/**/*.tsx" --preview
# WRONG — bare *.ext matches NOTHING
packx --limit 900k -i "*.ts" --preview # Empty result!
Directory-style includes (-i "src/") work without **/. The -x exclude flag is more lenient — "*.test.*" works for excludes.
Critical: -i Fails with External Directories
The -i glob is matched against paths relative to cwd. When you pass a positional path outside cwd (e.g., ~/dev/other-project), relative paths start with ../ which ** cannot traverse — silently producing 0 results.
# BROKEN — -i + external path = 0 files every time
packx --limit 900k -i "**/*.ts" --no-interactive --preview ~/dev/other-project
# FIX 1 (Best): cd into the target via subshell
(cd ~/dev/other-project && packx --limit 900k -i "**/*.ts" --no-interactive --preview)
# FIX 2: Positional path alone (all default file types), then exclude unwanted
packx --limit 900k -x "*.json" -x "*.md" -x "*.sh" --no-interactive --preview ~/dev/other-project
# FIX 3: Use -s (content search) — works fine with external paths
packx --limit 900k -s "import" --no-interactive --preview ~/dev/other-project
Rule: If the target directory ≠ cwd, wrap in (cd TARGET && packx ...).
Token Budget: k vs K
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.
| Notation | Multiplier | Example | 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 |
Positional Arguments
packx src/ # Directory → scan root
packx README.md src/auth.ts # Files → explicit includes
packx "**/*.test.ts" # Glob → include pattern
Positional args are classified automatically: directories become scan roots, existing files are explicit includes, patterns with glob characters (*, ?, [], {}) become glob filters. When combined with -i, explicit files must match BOTH conditions.
Complete Flag Reference
Search & Filter
| Flag | Short | Purpose | Notes |
|---|---|---|---|
--strings <text> |
-s |
Include files containing text | Repeatable; case-insensitive by default |
--exclude-strings |
-S |
Exclude files containing text | Opposite of -s |
--include <glob> |
-i |
Include by glob | Must use **/ prefix for extensions |
--exclude <glob> |
-x |
Exclude by filename/glob | More lenient than -i |
--regex |
-R |
Treat -s patterns as regex | Full regex syntax |
--case-sensitive |
-C |
Case-sensitive search | Default is case-insensitive |
--staged |
Git staged files only | git diff --cached --name-only --diff-filter=ACMR |
|
--diff |
Files changed from main | Uses git merge-base to find divergence point |
|
--dirty |
Modified + untracked files | Union of modified and git ls-files --others |
|
--no-packignore |
Ignore .packignore file |
--staged, --diff, and --dirty are mutually exclusive.
Processing
| Flag | Short | Purpose | Notes |
|---|---|---|---|
--strip-comments |
Remove comments | AST-aware via tree-sitter; regex fallback by language family | |
--no-comments |
Alias for --strip-comments | ||
--minify |
Remove empty lines + trim whitespace | Stacks remaining lines together | |
--lines <N> |
-l |
Extract N context lines around matches | Smart expansion to complete code blocks; overlapping windows auto-merge |
--follow-imports |
Include imported dependencies | ES6/CJS/dynamic; relative only; max depth 10; tries .ts/.tsx/.js/.jsx extensions | |
--related |
-r |
Include related files | Matches by core filename in same dir (tests, stories, styles) |
--skeleton |
Interface-only extraction | AST-based: strips function bodies to { /* ... */ } |
|
--instruction <file> |
Prepend custom instructions from file | Inserted at top of bundle | |
--prompt <text> |
-p |
Append text to end of output |
Output
| Flag | Short | Purpose | Notes |
|---|---|---|---|
--copy |
-c |
Copy to clipboard | pbcopy/clip/xclip; only chunk 1 if splitting |
--stdout |
Write to stdout | Summaries go to stderr; disables interactive mode | |
--output <file> |
-o |
Write to file | |
--format <fmt> |
-f |
xml (default), markdown, plain, jsonl |
Use markdown for Oracle/ChatGPT |
--preview |
Show matching files (up to 50) without packing | Dry run for testing filters | |
--max-tokens <N> |
-M |
Split into chunks | Creates file-1.xml, file-2.xml; files never split mid-file |
--limit <size> |
Token budget | 900k=900,000; 32K=32,768; visual progress in interactive mode |
|
--no-interactive |
Disable interactive mode | Required for scripting/piping |
Filter Decision Tree
Is the task about a specific feature/module?
├─ YES → Do you know the entrypoint file?
│ ├─ YES → --follow-imports <entrypoint>
│ └─ NO → -s "keyword" -i "relevant/path/**/*.ts"
└─ NO → Is it a code review / PR?
├─ YES → --diff (or --staged / --dirty)
└─ NO → Is it architecture/overview?
├─ YES → --skeleton -i "src/**/*.ts"
└─ NO → Is it debugging?
├─ YES → -s "error message" -r -l 20
└─ NO → -i "**/*.ts" (broad scan)
Always add: --limit 900k --preview (check first) → --no-interactive --stdout -f markdown
Token-tight? Add: --strip-comments --minify
Still too big? Add: -x "**/*.test.*" -x "**/stories/**" then -s "keyword" then -l N
Bundle Size Management
- ALWAYS run
packx --preview [filters]FIRST to estimate size - If preview shows >900k: add
--strip-comments --minifyonly if you need to fit under the target; otherwise keep rich context when the user explicitly wants a limit stress test - If still >900k: narrow
-ipatterns or add-xexclusions - If still >900k: add
-skeyword to filter to only relevant files - If context around matches is sufficient: use
-l 20instead of full files
Progression example:
# 1) Preview baseline
packx --preview -i "src/**/*.ts" -i "apps/web/**/*.tsx"
# 2) If too many files, strip/minify
packx --limit 900k -i "src/**/*.ts" --strip-comments --minify -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt
# 3) If still >900k, narrow includes/excludes
packx --limit 900k -i "src/auth/**/*.ts" -x "**/*.test.*" --strip-comments --minify -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt
# 4) If still >900k, add keyword focus
packx --limit 900k -i "src/auth/**/*.ts" -s "token session oauth" -x "**/*.test.*" --strip-comments --minify -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt
# 5) If still >900k, use context lines instead of full files
packx --limit 900k -s "token session oauth" -l 15 -x "**/*.test.*" --strip-comments -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt
# 6) For architecture overview, use skeleton mode
packx --limit 900k -i "src/**/*.ts" --skeleton -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt
Common Workflows
Review code by keyword
packx --limit 900k -s "auth" -i "**/*.ts" -x "*.test.*" -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt
Analyze from entrypoint (best signal-to-noise)
packx --limit 900k --follow-imports src/server.ts -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt
Debug from error
packx --limit 900k -s "TypeError: Cannot read properties" -r -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt
Context-line focused review (token-efficient)
packx --limit 900k -s "catch" -s "throw" -l 15 --strip-comments -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt
Architecture overview with skeleton mode
packx --limit 900k -i "src/**/*.ts" --skeleton -x "**/*.test.*" -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt
PR/diff review
packx --limit 900k --diff -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt
Large Monorepo
packx --limit 900k -i "apps/web/src/**/*.tsx" -i "apps/api/src/**/*.ts" -i "packages/auth/src/**/*.ts" -x "**/*.test.*" --strip-comments --minify -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt
Fallback — Manual Bundle Augmentation
When packx cannot reach every needed file in one pass:
packx --limit 900k -i "src/**/*.ts" -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt
cat docs/auth-decision-record.md >> ~/.oracle/bundles/{slug}.txt
wc -c ~/.oracle/bundles/{slug}.txt
References
- Packx deep technical reference — full internals, caching, import resolution, AST details