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