FolderFuse

High-performance codebase context packager, AST skeletonizer, and multi-model token optimizer engineered for Large Language Models (LLMs).

Overview

FolderFuse packages local codebases, documentation repositories, and mixed-format folders into model-ready, token-optimized context bundles. It operates under a strict dual-entry architecture: a headless Unix-pipe CLI for terminal power users and automated CI/CD pipelines, alongside an embedded local Web UI for interactive preparation.

FolderFuse is strictly an exporter—it never dispatches requests directly to external LLM APIs, ensuring workflows remain 100% private, zero-cost, and completely air-gapped.

┌──────────────────────────────────────────────────────────────────┐
│                         FolderFuse Core                          │
│                                                                  │
│  ┌───────────────────────┐             ┌──────────────────────┐  │
│  │   Headless CLI        │             │   FastAPI Engine     │  │
│  │  (Typer / Rich)       │             │  (Local 127.0.0.1)   │  │
│  └──────────┬────────────┘             └──────────┬───────────┘  │
│             │                                     │              │
│             │                         ┌───────────┴───────────┐  │
│             │                         │  Embedded React UI    │  │
│             │                         │  (Vite + Tailwind)    │  │
│             │                         └───────────┬───────────┘  │
│             └───────────────────┬─────────────────┘              │
│                                 ▼                                │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │                     Processing Pipeline                     │ │
│  │                                                             │ │
│  │  1. Filesystem Crawler (.gitignore, root jail containment)  │ │
│  │  2. Document Extractors (.pdf, .docx, .xlsx, .ipynb)        │ │
│  │  3. AST Skeletonizer (Tree-Sitter multi-language parser)    │ │
│  │  4. Security Sanitizer (Zero-leak session deduplication)    │ │
│  │  5. Multi-Model Tokenizers (Claude, Gemini 3, DeepSeek V4) │ │
│  │  6. KV-Cache Optimizer (5-step layout ordering engine)      │ │
│  └──────────────────────────────┬──────────────────────────────┘ │
│                                 ▼                                │
│                   Export: Stdout / File / Clipboard              │
└──────────────────────────────────────────────────────────────────┘

Core Capabilities

• Dual-Entry Architecture:
  • Headless POSIX CLI: Optimized for Unix piping (folderfuse pack . | pbcopy). Payload directed strictly to stdout; progress spinners, logs, and token meters routed to stderr.
  • Embedded Web Dashboard: Single-command boot (folderfuse ui .) launching an air-gapped React/Vite dashboard served directly from Python wheel assets on 127.0.0.1.
• Multi-Language AST Skeletonization (Tree-Sitter): Prunes function/method implementation bodies while preserving class definitions, method signatures, return types, docstrings, and top-level constants/type aliases. Supports Python, TypeScript, JavaScript, Go, Rust, Java, C, C++, and C#.
• Prompt-Cache Optimization (Anthropic & Gemini): Structures prompt layout deterministically into a 5-step hierarchy to maximize KV-cache hit rates:
  1. System instructions prefix
  2. ASCII repository directory tree
  3. Reference documentation (*.md, docs/**)
  4. Stable source code
  5. Ephemeral / working target files placed at the prompt tail (Git-aware + glob overrides)
• Multi-Model Tokenizer Engine: 100% offline exact token calculations for Anthropic Claude (Claude 3.5 Sonnet, Haiku), Google Gemini (Gemini 3.8 Flash, 3.7 Flash, 3.5 Flash), DeepSeek (DeepSeek-V4.1-Flash, DeepSeek-V4-Pro-0813), and OpenAI (GPT-4o, o200k/cl100k BPE).
• Zero-Leak Secret Sanitization: Detects credentials (OpenAI, Anthropic, AWS, GitHub PATs, JWTs, private keys) and replaces them with deterministic synthetic tokens ([REDACTED:OPENAI_KEY:1]), preserving cross-file references without leaking raw secrets.
• Rich Document Parsing & Statistical Data Profiling:
  • Spreadsheets (.xlsx, .csv): Markdown tables with configurable row/column caps and an automated statistical data profile summary (null percentages, unique counts, numeric stats).
  • Jupyter Notebooks (.ipynb): Strips heavy base64 image plots while preserving code cells and execution output streams.
  • Word Docs (.docx) & PDFs (.pdf): Extracts headings, bullet lists, and page-by-page text.

Installation

Install folderfuse from PyPI:

pip install folderfuse

Or using uv:

uv add folderfuse

Or run directly without permanent installation via pipx:

pipx run folderfuse ui

Quickstart

1. Headless CLI (folderfuse pack)

Package the current repository into an Anthropic Claude XML prompt and copy it directly to your system clipboard:

folderfuse pack . --model claude --clipboard

Stream directly to standard output for Unix pipelines:

# Pipe directly into macOS clipboard
folderfuse pack ./my-project -q | pbcopy

# Save formatted markdown context bundle to disk
folderfuse pack ./my-project --format markdown --output bundle.md

Apply AST skeletonization to secondary libraries:

folderfuse pack . --skeleton "src/utils/**,src/legacy/**" --strict

2. Interactive Local Web Dashboard (folderfuse ui)

Launch the local web server and open the dashboard in your default browser:

folderfuse ui /path/to/project

Options for UI server:

folderfuse ui . --port 8080 --no-browser

CLI Flag Reference (folderfuse pack)

POSIX Exit Codes

• 0: Success (Context bundle generated cleanly).
• 1: General runtime or filesystem write error.
• 2: Target directory not found or invalid path.
• 3: Context window budget overflow (when --strict is set).

Configuration File (folderfuse.yaml)

FolderFuse supports repository-level configuration files (folderfuse.yaml or .folderfuse.json) located at the target directory root:

version: "1"
settings:
  default_model: "claude-3-5-sonnet"
  default_format: "xml"
  max_file_size_kb: 500
  scrub_secrets: true
  strict: false
  include_instructions: true
  instruction_text: "You are an expert systems engineer evaluating this repository."

exclusions:
  - "dist/**"
  - "build/**"
  - "**/*.spec.ts"

skeletonize:
  - "legacy/**/*.py"
  - "src/vendor/**/*.ts"

working_files:
  - "src/active_feature.py"

custom_redactions:
  - name: "INTERNAL_CODENAME"
    regex: "(?i)project-zeus"
    replace: "[PROJECT_ZEUS]"

Precedence: Built-in Defaults < User Global Config (~/.config/folderfuse/config.yaml) < Target Repo Config (folderfuse.yaml) < CLI Flags.

Security & Privacy

• Air-Gapped Operation: FolderFuse makes zero network requests, contains zero analytics SDKs, and bundles all frontend and grammar assets locally inside the Python wheel.
• Localhost-Only Binding: The embedded FastAPI server binds strictly to loopback interfaces (127.0.0.1).
• Root Jail Containment: Symbolic links resolving outside the designated root directory are blocked by default to prevent path traversal attacks.

License

Distributed under the terms of the MIT License.
Copyright © 2026 Latent Oxygen Studios.