contextcraft 1.0.2

A CLI toolkit to generate comprehensive project context for LLMs.

ContextCraft

A powerful CLI toolkit to generate comprehensive project context for Large Language Models (LLMs).

ContextCraft transforms your codebase into well-structured, LLM-friendly documentation by intelligently aggregating directory trees, code files, dependencies, and Git context into clean, consumable formats. It's like a translator between your repo and the digital mind you just hired to read it.

Transform your entire codebase into AI-ready context with one command. No more copy-paste nightmares. No more explaining your project structure. Just instant, comprehensive context that LLMs actually understand.

✨ Features

🌳 Smart Directory Trees

• Beautiful, hierarchical project structure visualization
• Rich console output with emojis and colors
• Intelligent filtering with .llmignore support
• Clean file output for documentation

📄 Code Flattening

• Concatenate multiple files into organized documents
• Clear file markers and intelligent content handling
• Support for include/exclude patterns
• Binary file detection and graceful handling

📦 Dependency Analysis

• Multi-language dependency extraction (Python, Node.js)
• Support for Poetry, pip, npm, and yarn
• Clean Markdown output with language grouping
• Extensible architecture for additional languages

🔄 Git Context

• Current branch and status information
• Recent commit history with configurable depth
• Diff analysis for understanding changes
• Graceful handling of non-Git repositories

📋 Context Bundling

• Aggregate multiple tools into comprehensive bundles
• Configurable section inclusion/exclusion
• Well-structured Markdown with navigation
• Perfect for LLM consumption

📋 Clipboard Integration

• Copy output directly to clipboard with --to-clipboard or -c
• Available for all commands (tree, flatten, deps, git-info, bundle)
• Smart behavior: only works when no output file specified
• Cross-platform support with graceful error handling

🎯 Intelligent Filtering

• .llmignore files with .gitignore-style syntax
• Configurable global patterns via pyproject.toml
• Smart precedence hierarchy
• Tool-specific fallback exclusions

---

🚀 Quick Start

Installation

# Install from PyPI (coming soon)
pip install contextcraft

# Or install from source
git clone https://github.com/Shorzinator/ContextCraft.git
cd ContextCraft
poetry install

Basic Usage

# Generate a directory tree
contextcraft tree

# Save tree to file
contextcraft tree -o project_structure.txt

# Copy tree to clipboard
contextcraft tree --to-clipboard

# Flatten code files
contextcraft flatten src/ -o flattened_code.md

# Copy flattened code to clipboard
contextcraft flatten src/ -c

# Analyze dependencies
contextcraft deps

# Get Git context
contextcraft git-info

# Create a comprehensive bundle
contextcraft bundle -o project_context.md

# Copy bundle to clipboard
contextcraft bundle --to-clipboard

Configuration

Create a .llmignore file to exclude files and directories:

# .llmignore
*.log
__pycache__/
node_modules/
.env
build/
dist/

Configure defaults in pyproject.toml:

[tool.contextcraft]
default_output_filename_tree = "project_tree.txt"
default_output_filename_flatten = "flattened_code.md"
default_output_filename_deps = "dependencies.md"
default_output_filename_git_info = "git_context.md"
default_output_filename_bundle = "project_bundle.md"

global_exclude_patterns = [
    "*.tmp",
    "temp/",
    ".cache/"
]

📖 Documentation

🌐 Live Documentation Website

Comprehensive documentation including:

• Getting Started - Installation and basic usage
• CLI Commands - Complete command reference
• Configuration - Advanced configuration options
• API Reference - Detailed API documentation
• Examples - Real-world usage examples
• Tutorials - Step-by-step guides

🛠️ Development

Prerequisites

• Python 3.9+
• Poetry
• Git

Setup

# Clone the repository
git clone https://github.com/Shorzinator/ContextCraft.git
cd ContextCraft

# Install dependencies
poetry install --with dev

# Install pre-commit hooks
poetry run pre-commit install

# Run tests
poetry run pytest

# Run with coverage
poetry run pytest --cov=src/contextcraft --cov-report=html

Code Quality

We maintain high code quality standards. Some say it's obsessive. We say it's... necessary:

• Linting: Ruff for fast Python linting (not a dog, but still keeps your repo clean)
• Formatting: Ruff formatter for consistent code style
• Security: Bandit for security vulnerability scanning
• Testing: Pytest with 77%+ coverage (because 100% would be... suspicious)
• Commits: Conventional Commits for clear history and less git shame

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details on:

• Reporting bugs and requesting features
• Development setup and workflow
• Code standards and testing
• Pull request process

📄 License

This project is licensed under the MIT License - see the LICENSE file for details. (TL;DR: Use it, don’t sue us.)

🙏 Acknowledgments

• Built with Typer for the CLI framework
• Styled with Rich for beautiful terminal output
• Powered by Poetry for dependency management
• Quality assured with Ruff and Pytest

📊 Project Status

ContextCraft is actively developed and maintained. Current status:

• ✅ Core Tools: All primary tools implemented and tested
• ✅ CLI Interface: Complete command-line interface
• ✅ Documentation: Comprehensive docs with examples
• ✅ Testing: 175+ tests with 77% coverage
• ✅ CI/CD: Automated testing and quality checks
• 🚀 V1.0: Feature-complete and production-ready

---

📖 Documentation • 🐛 Issues • 💬 Discussions

Made with ❤️ for the developer community