User question
    ↓
1. DECOMPOSE — break into sub-questions (code-focused + doc-focused)
    ↓
2. EXPLORE — FastContext 4B model searches the codebase via Grep/Glob/Read
    ↓
3. EXTRACT — fuzzy matching extracts only relevant lines from found files
    ↓
4. GAP-FILL — ripgrep + Levenshtein distance catches what the model missed
    ↓
Snippets (~5K tokens) → fed to larger LLM for synthesis

APPROACH COMPARISON (tested on business-auditor, 1170 files)
═══════════════════════════════════════════════════════════════════════════

Method                          Concept     Answerable   Context/Question
                                Coverage
───────────────────────────────────────────────────────────────────────────
Raw FastContext (no pipeline)   50%         3/6          N/A (model output)
+ Path resolution fix           67%         4/6          N/A
+ Hybrid pipeline (unlimited)   97%         6/6          308K tokens
+ Hybrid pipeline (optimized)   92%         6/6           5K tokens  ← this
───────────────────────────────────────────────────────────────────────────

Layer                   What it does                            Gain
──────────────────────────────────────────────────────────────────────
FastContext 4B          Finds relevant files via tool calls     Baseline
Query decomposition     Breaks Q into doc + code sub-questions  +17%
Fuzzy snippet extract   camelCase split + Levenshtein matching  +15%
Gap-fill (ripgrep)      Catches what model missed               +25%
──────────────────────────────────────────────────────────────────────
Total: 50% → 92% concept coverage (+84% improvement)

Without optimization:  308K tokens/question  (loads full files)
With optimization:       5K tokens/question  (extracts relevant lines only)
Reduction:               62x smaller context

git clone https://github.com/LyuboslavLyubenov/fastcontext-hybrid-mcp
cd fastcontext-hybrid-mcp
chmod +x setup-mac.sh start.sh

# One-command setup (installs dependencies, builds llama.cpp with Metal, downloads model)
./setup-mac.sh

# Start with your project
./start.sh /path/to/your/project

git clone https://github.com/LyuboslavLyubenov/fastcontext-hybrid-mcp
cd fastcontext-hybrid-mcp
chmod +x setup.sh start.sh

./setup.sh

# Start with your project
./start.sh /path/to/your/project

WORK_DIR=/path/to/your/project docker compose up fastcontext-cpu

git clone https://github.com/LyuboslavLyubenov/fastcontext-hybrid-mcp
cd fastcontext-hybrid-mcp

WORK_DIR=/path/to/your/project docker compose up fastcontext-cpu

WORK_DIR=/path/to/your/project docker compose up fastcontext-vulkan

./start.sh /path/to/default/project

{
  "mcp": {
    "fastcontext": {
      "type": "remote",
      "url": "http://127.0.0.1:8090/mcp",
      "enabled": true
    }
  }
}

distill(question="...", work_dir="/path/to/project-a")
distill(question="...", work_dir="/path/to/project-b")

mcp_servers:
  fastcontext:
    command: "python3"
    args: ["/path/to/fastcontext-hybrid-mcp/mcp_server.py"]
    env:
      FASTCONTEXT_WORK_DIR: "/path/to/your/project"
      FASTCONTEXT_SERVER: "http://127.0.0.1:8080"
    timeout: 120

WORK_DIR=/path/to/your/project docker compose up fastcontext-cpu

{
  "mcp": {
    "fastcontext": {
      "type": "remote",
      "url": "http://localhost:8090/mcp",
      "enabled": true
    }
  }
}

Args:
  question: str        — The question (conceptual or code-specific)
  work_dir: str        — Path to codebase
  seed: int            — Random seed (default: 42)
  max_anchors: int     — Max anchor files to gather evidence from (default: 4)
  evidence_chars: int  — Char budget for gathered evidence (default: 8000)

Returns:
  JSON with:
    answer: str               — Grounded answer citing file:line (when model cooperates)
    artifacts: list           — Verified symbols/values with file + line ranges
    evidence: list            — File:line + actual code region for each anchor
    confidence: str           — high | low | none
    ungrounded_dropped: list  — Model claims that failed validation
    identifiers_used: list    — Identifiers resolved from the question
    identifier_source: str    — literal | concept

Args:
  filepath: str          — Absolute path to file
  concepts: list[str]    — Concepts to search for
  context_lines: int     — Surrounding lines (default: 2)