{
  "schemaVersion": "1",
  "revision": "22ce5d34dbcb5a78",
  "id": "factory-packx-quick-reference",
  "slug": "packx-quick-reference",
  "title": "Packx command and filtering reference",
  "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-quick-reference.md"
    }
  ],
  "sourceUnits": [
    "08-oracle-video/skills/oracle/references/packx-quick-reference.md"
  ],
  "collection": "factory",
  "categoryId": "tools",
  "wordCount": 1604,
  "url": "/topics/factory-packx-quick-reference/",
  "markdownUrl": "/markdown/factory-packx-quick-reference.md?raw=1&v=22ce5d34dbcb5a78",
  "jsonUrl": "/api/v1/documents/factory-packx-quick-reference.json",
  "headings": [
    {
      "id": "packx-quick-reference",
      "text": "Packx Quick Reference",
      "level": 2
    },
    {
      "id": "how-file-discovery-works",
      "text": "How File Discovery Works",
      "level": 2
    },
    {
      "id": "auto-excluded-always-skipped",
      "text": "Auto-Excluded (always skipped)",
      "level": 2
    },
    {
      "id": "default-file-types-when-no-i-flag",
      "text": "Default File Types (when no `-i` flag)",
      "level": 2
    },
    {
      "id": "critical-i-glob-requires-prefix",
      "text": "Critical: `-i` Glob Requires `**/` Prefix",
      "level": 2
    },
    {
      "id": "critical-i-fails-with-external-directories",
      "text": "Critical: `-i` Fails with External Directories",
      "level": 2
    },
    {
      "id": "token-budget-k-vs-k",
      "text": "Token Budget: k vs K",
      "level": 2
    },
    {
      "id": "positional-arguments",
      "text": "Positional Arguments",
      "level": 2
    },
    {
      "id": "complete-flag-reference",
      "text": "Complete Flag Reference",
      "level": 2
    },
    {
      "id": "search-filter",
      "text": "Search & Filter",
      "level": 3
    },
    {
      "id": "processing",
      "text": "Processing",
      "level": 3
    },
    {
      "id": "output",
      "text": "Output",
      "level": 3
    },
    {
      "id": "filter-decision-tree",
      "text": "Filter Decision Tree",
      "level": 2
    },
    {
      "id": "bundle-size-management",
      "text": "Bundle Size Management",
      "level": 2
    },
    {
      "id": "common-workflows",
      "text": "Common Workflows",
      "level": 2
    },
    {
      "id": "review-code-by-keyword",
      "text": "Review code by keyword",
      "level": 3
    },
    {
      "id": "analyze-from-entrypoint-best-signal-to-noise",
      "text": "Analyze from entrypoint (best signal-to-noise)",
      "level": 3
    },
    {
      "id": "debug-from-error",
      "text": "Debug from error",
      "level": 3
    },
    {
      "id": "context-line-focused-review-token-efficient",
      "text": "Context-line focused review (token-efficient)",
      "level": 3
    },
    {
      "id": "architecture-overview-with-skeleton-mode",
      "text": "Architecture overview with skeleton mode",
      "level": 3
    },
    {
      "id": "pr-diff-review",
      "text": "PR/diff review",
      "level": 3
    },
    {
      "id": "large-monorepo",
      "text": "Large Monorepo",
      "level": 3
    },
    {
      "id": "fallback-manual-bundle-augmentation",
      "text": "Fallback — Manual Bundle Augmentation",
      "level": 2
    },
    {
      "id": "references",
      "text": "References",
      "level": 2
    }
  ],
  "markdown": "# Packx command and filtering reference\n\nFull context-bundling reference: discovery rules, glob traps, token budgets, output formats, filters, and operational caveats.\n\n## Packx Quick Reference\n\nPackx (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.\n\n## How File Discovery Works\n\n1. **Candidate discovery** — scans directories using glob patterns (ripgrep fast-path when available, Node.js glob fallback)\n2. **Ignore filtering** — applies `.gitignore` (traversed upward from cwd) + `.packignore` + 22 built-in ignore patterns\n3. **Include/exclude pattern matching** — `-i` and `-x` filters via minimatch\n4. **Content filtering** — `-s` search strings and `-S` exclusion strings (up to 50 files in parallel)\n5. **Size/binary filtering** — skips files >10MB silently; detects binary via first 512 bytes (>10% non-printable = binary)\n6. **Token counting** — `js-tiktoken` (OpenAI tokenizer), fallback: `text.length / 4`\n\n## Auto-Excluded (always skipped)\n```\nnode_modules/  .git/  dist/  build/  .next/  coverage/  .cache/  tmp/  temp/\n*.log  .DS_Store  Thumbs.db  package-lock.json  yarn.lock  pnpm-lock.yaml\nbun.lockb  bun.lock  Gemfile.lock  Cargo.lock  poetry.lock  Pipfile.lock  composer.lock\n```\n\n## Default File Types (when no `-i` flag)\n**Code:** js, jsx, ts, tsx, mjs, cjs, py, rb, go, java, cpp, c, h, rs, swift, kt, scala, php\n**Web:** vue, svelte, astro, css, scss, less\n**Config:** json, yaml, yml, toml, xml\n**Docs:** md, mdx, txt\n**Scripts:** sh, bash, zsh, fish\n**Data:** sql, graphql, gql\n\n## Critical: `-i` Glob Requires `**/` Prefix\n\n```bash\n# CORRECT — always use **/ prefix for extension globs\npackx --limit 900k -i \"**/*.ts\" --preview\npackx --limit 900k -i \"src/**/*.tsx\" --preview\n\n# WRONG — bare *.ext matches NOTHING\npackx --limit 900k -i \"*.ts\" --preview    # Empty result!\n```\n\nDirectory-style includes (`-i \"src/\"`) work without `**/`. The `-x` exclude flag is more lenient — `\"*.test.*\"` works for excludes.\n\n## Critical: `-i` Fails with External Directories\n\n**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**.\n\n```bash\n# BROKEN — -i + external path = 0 files every time\npackx --limit 900k -i \"**/*.ts\" --no-interactive --preview ~/dev/other-project\n\n# FIX 1 (Best): cd into the target via subshell\n(cd ~/dev/other-project && packx --limit 900k -i \"**/*.ts\" --no-interactive --preview)\n\n# FIX 2: Positional path alone (all default file types), then exclude unwanted\npackx --limit 900k -x \"*.json\" -x \"*.md\" -x \"*.sh\" --no-interactive --preview ~/dev/other-project\n\n# FIX 3: Use -s (content search) — works fine with external paths\npackx --limit 900k -s \"import\" --no-interactive --preview ~/dev/other-project\n```\n\n**Rule**: If the target directory ≠ cwd, wrap in `(cd TARGET && packx ...)`.\n\n## Token Budget: k vs K\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| Notation | Multiplier | Example | 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\n## Positional Arguments\n\n```bash\npackx src/                  # Directory → scan root\npackx README.md src/auth.ts # Files → explicit includes\npackx \"**/*.test.ts\"        # Glob → include pattern\n```\n\nPositional 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.\n\n## Complete Flag Reference\n\n### Search & Filter\n| Flag | Short | Purpose | Notes |\n|------|-------|---------|-------|\n| `--strings <text>` | `-s` | Include files containing text | Repeatable; case-insensitive by default |\n| `--exclude-strings` | `-S` | Exclude files containing text | Opposite of -s |\n| `--include <glob>` | `-i` | Include by glob | **Must use `**/` prefix for extensions** |\n| `--exclude <glob>` | `-x` | Exclude by filename/glob | More lenient than -i |\n| `--regex` | `-R` | Treat -s patterns as regex | Full regex syntax |\n| `--case-sensitive` | `-C` | Case-sensitive search | Default is case-insensitive |\n| `--staged` | | Git staged files only | `git diff --cached --name-only --diff-filter=ACMR` |\n| `--diff` | | Files changed from main | Uses `git merge-base` to find divergence point |\n| `--dirty` | | Modified + untracked files | Union of modified and `git ls-files --others` |\n| `--no-packignore` | | Ignore .packignore file | |\n\n`--staged`, `--diff`, and `--dirty` are **mutually exclusive**.\n\n### Processing\n| Flag | Short | Purpose | Notes |\n|------|-------|---------|-------|\n| `--strip-comments` | | Remove comments | AST-aware via tree-sitter; regex fallback by language family |\n| `--no-comments` | | Alias for --strip-comments | |\n| `--minify` | | Remove empty lines + trim whitespace | Stacks remaining lines together |\n| `--lines <N>` | `-l` | Extract N context lines around matches | Smart expansion to complete code blocks; overlapping windows auto-merge |\n| `--follow-imports` | | Include imported dependencies | ES6/CJS/dynamic; relative only; max depth 10; tries .ts/.tsx/.js/.jsx extensions |\n| `--related` | `-r` | Include related files | Matches by core filename in same dir (tests, stories, styles) |\n| `--skeleton` | | Interface-only extraction | AST-based: strips function bodies to `{ /* ... */ }` |\n| `--instruction <file>` | | Prepend custom instructions from file | Inserted at top of bundle |\n| `--prompt <text>` | `-p` | Append text to end of output | |\n\n### Output\n| Flag | Short | Purpose | Notes |\n|------|-------|---------|-------|\n| `--copy` | `-c` | Copy to clipboard | pbcopy/clip/xclip; only chunk 1 if splitting |\n| `--stdout` | | Write to stdout | Summaries go to stderr; **disables interactive mode** |\n| `--output <file>` | `-o` | Write to file | |\n| `--format <fmt>` | `-f` | `xml` (default), `markdown`, `plain`, `jsonl` | Use `markdown` for Oracle/ChatGPT |\n| `--preview` | | Show matching files (up to 50) without packing | Dry run for testing filters |\n| `--max-tokens <N>` | `-M` | Split into chunks | Creates file-1.xml, file-2.xml; files never split mid-file |\n| `--limit <size>` | | Token budget | `900k`=900,000; `32K`=32,768; visual progress in interactive mode |\n| `--no-interactive` | | Disable interactive mode | **Required for scripting/piping** |\n\n## Filter Decision Tree\n\n```\nIs the task about a specific feature/module?\n├─ YES → Do you know the entrypoint file?\n│        ├─ YES → --follow-imports <entrypoint>\n│        └─ NO  → -s \"keyword\" -i \"relevant/path/**/*.ts\"\n└─ NO  → Is it a code review / PR?\n         ├─ YES → --diff (or --staged / --dirty)\n         └─ NO  → Is it architecture/overview?\n                  ├─ YES → --skeleton -i \"src/**/*.ts\"\n                  └─ NO  → Is it debugging?\n                           ├─ YES → -s \"error message\" -r -l 20\n                           └─ NO  → -i \"**/*.ts\" (broad scan)\n\nAlways add: --limit 900k --preview (check first) → --no-interactive --stdout -f markdown\nToken-tight? Add: --strip-comments --minify\nStill too big? Add: -x \"**/*.test.*\" -x \"**/stories/**\" then -s \"keyword\" then -l N\n```\n\n## Bundle Size Management\n\n- ALWAYS run `packx --preview [filters]` FIRST to estimate size\n- If preview shows >900k: add `--strip-comments --minify` only if you need to fit under the target; otherwise keep rich context when the user explicitly wants a limit stress test\n- If still >900k: narrow `-i` patterns or add `-x` exclusions\n- If still >900k: add `-s` keyword to filter to only relevant files\n- If context around matches is sufficient: use `-l 20` instead of full files\n\nProgression example:\n\n```bash\n# 1) Preview baseline\npackx --preview -i \"src/**/*.ts\" -i \"apps/web/**/*.tsx\"\n\n# 2) If too many files, strip/minify\npackx --limit 900k -i \"src/**/*.ts\" --strip-comments --minify -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt\n\n# 3) If still >900k, narrow includes/excludes\npackx --limit 900k -i \"src/auth/**/*.ts\" -x \"**/*.test.*\" --strip-comments --minify -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt\n\n# 4) If still >900k, add keyword focus\npackx --limit 900k -i \"src/auth/**/*.ts\" -s \"token session oauth\" -x \"**/*.test.*\" --strip-comments --minify -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt\n\n# 5) If still >900k, use context lines instead of full files\npackx --limit 900k -s \"token session oauth\" -l 15 -x \"**/*.test.*\" --strip-comments -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt\n\n# 6) For architecture overview, use skeleton mode\npackx --limit 900k -i \"src/**/*.ts\" --skeleton -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt\n```\n\n## Common Workflows\n\n### Review code by keyword\n```bash\npackx --limit 900k -s \"auth\" -i \"**/*.ts\" -x \"*.test.*\" -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt\n```\n\n### Analyze from entrypoint (best signal-to-noise)\n```bash\npackx --limit 900k --follow-imports src/server.ts -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt\n```\n\n### Debug from error\n```bash\npackx --limit 900k -s \"TypeError: Cannot read properties\" -r -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt\n```\n\n### Context-line focused review (token-efficient)\n```bash\npackx --limit 900k -s \"catch\" -s \"throw\" -l 15 --strip-comments -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt\n```\n\n### Architecture overview with skeleton mode\n```bash\npackx --limit 900k -i \"src/**/*.ts\" --skeleton -x \"**/*.test.*\" -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt\n```\n\n### PR/diff review\n```bash\npackx --limit 900k --diff -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt\n```\n\n### Large Monorepo\n```bash\npackx --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\n```\n\n## Fallback — Manual Bundle Augmentation\n\nWhen `packx` cannot reach every needed file in one pass:\n\n```bash\npackx --limit 900k -i \"src/**/*.ts\" -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt\ncat docs/auth-decision-record.md >> ~/.oracle/bundles/{slug}.txt\nwc -c ~/.oracle/bundles/{slug}.txt\n```\n\n## References\n\n- [Packx deep technical reference](https://shiny-rosette-m6zy.here.now/skills/oracle/references/packx-deep-reference.md) — full internals, caching, import resolution, AST details"
}
