# ContextCraft

> Open-source Python tool that compresses a Git repository into a token-budgeted Markdown, XML, or JSON context artifact for LLMs using AST analysis and dependency-graph ranking.

ContextCraft is an open-source Python tool, published under the MIT License, that compiles a Git repository into a Markdown, Claude XML, or JSON context artifact sized to a chosen token budget such as 4k, 16k, 32k, or 128k. It is available as a command-line tool, a Python SDK, and a local web playground. The latest release listed on GitHub is v0.3.1.

## What It Is

ContextCraft is a codebase compressor for LLM prompts. Rather than concatenating every file verbatim, it parses source with Tree-sitter, ranks files by architectural importance, and decides how much detail each file gets so the output fits a target token budget. The README positions it against repository packers such as repomix, gitingest, and code2prompt.

## How the Compression Pipeline Works

The README describes a five-stage pipeline:

- A repository scanner honors hierarchical .gitignore and .contextignore files, filters binary and oversized files, and a sanitizer scrubs API keys, PEM blocks, and high-entropy secrets before parsing.
- A registry of 35 languages and formats produces ASTs with symbols, docstrings, and a lexical scope graph, and unused imports are trimmed in signature mode.
- A dependency-graph scorer combines Personalized PageRank with BM25F, biased by an optional focus query, to rank files.
- Each file is rendered at one of four fidelity tiers: FULL, SKEL (signatures, types, and docstrings), SIGS (public declarations), or TREE (a directory-tree entry).
- A multiple-choice knapsack optimizer allocates tiers by marginal utility density, which keeps very large files from consuming the full-detail budget.

## Usage Paths

The CLI runs via uvx or after pip install contextcraft-ai, with options for budget, focus query, output format, clipboard copy, tokenizer encoding, and include/exclude patterns. The Python SDK can analyze a repository once and then render several budgets or formats from the same snapshot without reparsing. A FastAPI-based web playground lets users tune budgets, inspect PageRank scores, and compress public GitHub repositories by URL.

## Benchmark Claims

The README reports a reproducible benchmark on its own repository (258 files, 119,813 raw tokens), with an 8k budget emitting 7,991 tokens at a stated 14.99x compression ratio. The README also recommends pairing the output with local models for offline workflows.

## Features
- AST-aware parsing of 35 languages and formats with Tree-sitter
- Personalized PageRank and BM25F file ranking with focus query
- Token-budgeted output via multiple-choice knapsack optimizer
- Four fidelity tiers: FULL, SKEL, SIGS, TREE
- Markdown, Claude XML, and JSON output formats
- Secret sanitization of API keys, PEM blocks, and high-entropy strings
- Hierarchical .gitignore and .contextignore support
- Include/exclude patterns and focus-file scoping
- Selectable tokenizer encoding (cl100k_base, o200k_base)
- Python SDK with reusable analyzed snapshots
- Interactive web playground with GitHub URL swap
- Clipboard copy of output

## Integrations
Tree-sitter, PyPI, uvx, Ollama, vLLM, llama.cpp, Anthropic Claude XML

## Platforms
WEB, API, DEVELOPER_SDK, CLI

## Pricing
Open Source

## Version
v0.3.1

## Links
- Website: https://khanhtq29vn.github.io/contextcraft/
- Documentation: https://khanhtq29vn.github.io/contextcraft/
- Repository: https://github.com/khanhtq29vn/contextcraft
- EveryDev.ai: https://www.everydev.ai/tools/contextcraft