foldermix Docs

foldermix packs a directory into a single LLM-friendly context file. The v1 docs site is intentionally one page: enough to install the tool, run it immediately, and find the core commands without reading the full README end to end.

What It Does

Use foldermix when you want to turn a folder of text and document files into one context artifact for an LLM workflow.

Core capabilities: - pack a folder into md, xml, or jsonl - preview what will be included or skipped before packing - handle optional PDF and Office converters when installed - emit a machine-readable report for audits and cleanup workflows

Install

Core install

pip install foldermix

Homebrew

brew tap foldermix/foldermix
brew install foldermix

Homebrew installs the core feature set only.

Full optional converter support

# uv (recommended)
uv tool install "foldermix[all,markitdown]"

# pipx
pipx install "foldermix[all,markitdown]"

Optional extras: - pdf: native PDF text extraction - ocr: OCR fallback for textless PDFs - office: docx / xlsx / pptx - markitdown: additional converter support

Super Quick Start

Run this from the folder you want to pack:

foldermix pack . --out context.md

This writes one Markdown bundle to ./context.md.

Defaults worth knowing: - default output format is Markdown (md) - if you omit --out, foldermix writes a timestamped Markdown file such as foldermix_20260307_120000.md

Core Commands

pack

foldermix pack PATH [--out FILE] [--format md|xml|jsonl]

Use pack to create the final bundle.

Common flags: - --report report.json: write a machine-readable report - --dedupe-content: skip later exact-duplicate files by content hash - --include-ext, --exclude-ext, --exclude-dirs, --exclude-glob - --pdf-ocr: enable OCR fallback when OCR dependencies are installed

list

foldermix list PATH

Shows which files would be included by the current pack-style filtering rules.

skiplist

foldermix skiplist PATH

Shows which files would be skipped and why.

stats

foldermix stats PATH

Shows extension and byte-size statistics for the selected tree.

version

foldermix version

Prints the installed version.

Common Workflows

Config-first project workflow

foldermix init --profile engineering-docs
foldermix pack . --config foldermix.toml --format md --out context.md --report report.json

Research corpus batch run

find ./corpus -type f -print0 | foldermix pack ./corpus --config foldermix.toml --stdin --null --format jsonl --out research-context.jsonl --report research-report.json

Course refresh bundle

foldermix init --profile course-refresh --out foldermix.toml --force
foldermix pack ./previous-course --config foldermix.toml --format md --out course-refresh-context.md --report course-refresh-report.json

Duplicate cleanup before LLM ingestion

foldermix pack ./corpus --format md --out deduped-context.md --report dedupe-report.json --dedupe-content

Optional Dependency Guidance

Choose the install method based on the workflow: - Homebrew: fastest system install, core features only - uv tool: best isolated global install with extras - pipx: similar isolated global install if you already use pipx - virtualenv + pip: project-specific environments

If you already installed via Homebrew and later need extras, uninstall the Homebrew package and reinstall via uv tool, pipx, or a virtualenv.

Build And Publish

This docs site is built with MkDocs and published to GitHub Pages.

Local build:

pip install -e ".[docs]"
mkdocs serve
mkdocs build --strict

Publish path: - the docs-site.yml workflow builds on pull requests - pushes to main deploy the site to GitHub Pages

More Detailed Docs

This site is intentionally concise. For deeper details, use: - README - Config-first workflows - Compliance and safety - Contributing