Packx Deep Reference

Complete technical reference for packx v4.x — the AI context bundler.

File Discovery Pipeline

Processing Order

  1. Candidate discovery — by extension + glob patterns + git mode
  2. Ignore filtering — .gitignore (traversed upward) + .packignore + default ignores
  3. Content filtering — search strings (-s) and exclusion strings (-S)
  4. Size filtering — skip files > 10MB silently
  5. Binary detection — first 512 bytes checked for null bytes; >10% non-printable = binary → skip
  6. Pattern matching — minimatch for -i/-x patterns
  7. 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

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

  1. ES6: import ... from "..." and export ... from "..."
  2. CommonJS: require("...")
  3. Dynamic: import("...")

Resolution

Resolution extensions tried (in order): "", .ts, .tsx, .js, .jsx, .mts, .mjs, .cts, .cjs, .json

Extension mappings:

Index files for directory imports: index.ts, index.tsx, index.js, index.jsx, index.mts, index.mjs

Parse Strategy

  1. Tree-sitter AST parsing first (for .ts, .js, etc.)
  2. 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:

Comment Stripping (--strip-comments)

AST-Based (primary — tree-sitter)

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

  1. Extracts N lines around each match
  2. Tries to expand to complete code blocks using tree-sitter AST
  3. Falls back to indent-based block detection
  4. 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)

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:

  1. mtime AND size match → cache hit (fast path)
  2. Size differs → cache miss
  3. mtime differs but size same → compute SHA-256 → compare hash
  4. Hash matches → update mtime, keep entry
  5. Hash differs → cache miss, recompute

Bypass: --no-cache Prune: Stale entries for deleted files cleaned on next run

Bundles (-b / --bundle)

Interactive Mode (-I)

Default since v4.7.0 — running packx with no output flags enters interactive mode.

Features

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

Watch Mode (-w)

--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

--explain Mode

--skeleton Mode (v4.15.0+)

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)

Concurrency

.packignore

Positional Path Arguments

packx src/          # Directory → scan root
packx README.md     # File → explicit include
packx "**/*.test.ts" # Glob pattern → include pattern

Classification:

Interaction with filters:

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
# Packx Deep Reference

Complete technical reference for packx v4.x — the AI context bundler.

## File Discovery Pipeline

### Processing Order
1. **Candidate discovery** — by extension + glob patterns + git mode
2. **Ignore filtering** — `.gitignore` (traversed upward) + `.packignore` + default ignores
3. **Content filtering** — search strings (`-s`) and exclusion strings (`-S`)
4. **Size filtering** — skip files > 10MB silently
5. **Binary detection** — first 512 bytes checked for null bytes; >10% non-printable = binary → skip
6. **Pattern matching** — minimatch for `-i`/`-x` patterns
7. **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:**

```bash
# 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
1. ES6: `import ... from "..."` and `export ... from "..."`
2. CommonJS: `require("...")`
3. Dynamic: `import("...")`

### Resolution
- **Only follows relative imports** (`./` or `../`), never `node_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
1. Tree-sitter AST parsing first (for .ts, .js, etc.)
2. 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` → finds `Button.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
1. Extracts N lines around each match
2. **Tries to expand to complete code blocks** using tree-sitter AST
3. Falls back to indent-based block detection
4. 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)
```xml
<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`)
```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:
```json
{"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:**
```json
{
  "mtime": 1702000000000,
  "size": 4096,
  "contentHash": "sha256hex...",
  "isBinary": false,
  "tokens": 342
}
```

**Validation strategy:**
1. mtime AND size match → cache hit (fast path)
2. Size differs → cache miss
3. mtime differs but size same → compute SHA-256 → compare hash
4. Hash matches → update mtime, keep entry
5. 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
- `.packignore` files 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 `chokidar` with 150ms debounce
- File stabilization: 100ms threshold, 50ms poll interval
- Watches: `change`, `add`, `unlink` events
- **Requires** `--output` or `--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

```javascript
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 `ignore` npm library)
- Auto-loaded from project root
- `--no-packignore` to disable
- In interactive mode: matching files shown but unselected
- `x` hotkey in interactive mode banishes files to `.packignore`

## Positional Path Arguments

```bash
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 + `-i` patterns: 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 |