codebrief

The missing link between your codebase and AI assistants.

Stop copying files. Start solving problems.

codebrief is a production-ready CLI toolkit that solves the core problem developers face when working with AI assistants: manually preparing context from their projects. Whether you're debugging with ChatGPT, explaining your codebase to Claude, or preparing documentation for any LLM, codebrief provides the essential tools to create rich, contextual project summaries in seconds, not minutes.

Core Problem Solved

Developers waste 5-10 minutes manually copying files, explaining project structure, and gathering context every time they need AI assistance. codebrief reduces this to a single command that takes seconds.

Essential Features

Smart Directory Trees

• Hierarchical project structure visualization
• Rich console output with intelligent formatting
• Advanced 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
• Optimized 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
pip install codebrief

# Or install with Poetry
poetry add codebrief

Basic Usage

# Generate a directory tree
codebrief tree

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

# Copy tree to clipboard
codebrief tree --to-clipboard

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

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

# Analyze dependencies
codebrief deps

# Get Git context
codebrief git-info

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

# Copy bundle to clipboard
codebrief 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.codebrief]
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/CodeBrief.git
cd CodeBrief

# 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/codebrief --cov-report=html

Code Quality

We maintain high code quality standards:

• Linting: Ruff for fast Python linting
• Formatting: Ruff formatter for consistent code style
• Security: Bandit for security vulnerability scanning
• Testing: Pytest with 77%+ coverage
• Commits: Conventional Commits for clear history

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.

Acknowledgments

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

Project Status

codebrief 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.2: Production-ready with critical fixes resolved

---

Documentation • Issues • Discussions

Made for the developer community