Welcome to CodeBrief¶

Quick Start

Ready to streamline your LLM workflows? Jump to Quick Start or Installation.

The Missing Link Between Your Codebase and AI Assistants¶

CodeBrief is a production-ready Command Line Interface (CLI) toolkit designed to solve 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.

Stop Copying Files. Start Solving Problems.¶

Developers waste 10+ minutes per day copying and pasting project files, directory structures, and configuration details to provide context every time they need AI assistance. CodeBrief reduces this to a single command that takes seconds.

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¶

Directory Tree Generation¶

Generate hierarchical representations of your project structure with intelligent filtering and customization options.

Code Flattening¶

Concatenate code from multiple files into a single, well-organized document with clear file markers and intelligent content handling.

Dependency Analysis¶

Extract and analyze project dependencies across multiple languages and package managers (Python, Node.js, and more).

Git Context Extraction¶

Comprehensive Git repository information including branch status, commit history, and change diffs for enhanced development context.

Context Bundling¶

Powerful aggregation tool that combines directory trees, Git context, dependencies, and flattened code into structured, comprehensive bundles.

Intelligent Ignore System¶

Sophisticated .llmignore file support with .gitignore-style syntax for precise control over what gets included.

Advanced Configuration¶

Flexible configuration system via pyproject.toml with support for default outputs, global patterns, and project-specific settings.

Clipboard Integration¶

Copy output directly to clipboard with --to-clipboard or -c flag on all commands. Cross-platform support with graceful error handling and user feedback.

Quick Start¶

Get started with CodeBrief in minutes:

pippoetryBasic tree generationCopy tree to clipboardFlatten Python files to a single outputFlatten Python files to clipboardExtract dependenciesGit context extractionBundle everythingBundle to clipboardComplex bundle with specific pathsBundle selective sections

pip install codebrief

poetry add codebrief

codebrief tree

codebrief tree --to-clipboard

codebrief flatten . --include "*.py" --output context.md

codebrief flatten . --include "*.py" -c

codebrief deps --output deps.md

codebrief git-info --output git-context.md

codebrief bundle --output project-bundle.md

codebrief bundle -c

codebrief bundle \
    --output comprehensive-context.md \
    --flatten src/ --flatten tests/ \
    --git-log-count 10 --git-full-diff

codebrief bundle \
    --exclude-deps --exclude-git \
    --flatten src/core/ \
    --output focused-context.md

Advanced Workflow¶

# Create comprehensive project context with bundle
codebrief bundle \
    --output complete-context.md \
    --git-log-count 15 \
    --flatten src/ tests/

# Focused code review bundle
codebrief bundle \
    --exclude-deps \
    --git-full-diff \
    --flatten src/ tests/ \
    --output review-bundle.md

# Use .llmignore for fine-grained control
echo "*.log\n__pycache__/\n.venv/" > .llmignore

Primary Use Cases¶

AI-Assisted Debugging
Generate focused context that helps LLMs understand your project structure and identify issues quickly.
Code Reviews
Create comprehensive review bundles with Git context, code changes, and project structure for thorough reviews.
Legacy Codebase Explanation
Quickly share your project structure, dependencies, and relevant code with team members or AI tools for faster understanding.
Development Documentation
Create comprehensive project overviews for onboarding, code reviews, and technical documentation.
Workflow Automation
Streamline your development workflow with automated context generation for various scenarios and CI/CD integration.
Git-Based Context
Integrate with Git workflows for branch-specific context, commit analysis, and development progress tracking.

Architecture¶

CodeBrief is built with modern Python best practices:

CLI Framework: Typer for intuitive command-line interfaces
Rich Output: Rich for clean terminal output
Modular Design: Clean separation between tools, utilities, and CLI commands
Comprehensive Testing: 175+ tests with 77%+ coverage
Security Compliant: Bandit security scanning with proper subprocess handling
Code Quality: Ruff, pre-commit hooks, and conventional commits for maintainable code
Professional Infrastructure: Complete documentation, security policies, and contributor guidelines

Documentation Sections¶

Getting Started
Installation, quick start guide, and basic configuration
Get Started
User Guide
Comprehensive guides for all CLI commands and features
User Guide
Tutorials
Step-by-step tutorials for common workflows and use cases
Tutorials
API Reference
Complete API documentation for all modules and functions
API Reference
Examples
Real-world examples for Git workflows, bundle patterns, and automation
Examples
Contributing
Developer guides, contribution guidelines, and community standards
Contributing

What's New in v1.0.2¶

Critical Fixes & Compatibility Improvements¶

Installation Issues Resolved:

Fixed ModuleNotFoundError: No module named 'src' when installing via Poetry
Improved Python version compatibility (>=3.9,<4.0)
Resolved help system compatibility with Click/Typer versions
Enhanced test suite reliability across environments

Production Quality:

175 comprehensive tests with 77% coverage
Cross-platform compatibility verified
Professional documentation and distribution
Complete CLI integration with help documentation

Core Commands¶

Command	Purpose	Key Features
`tree`	Directory structure visualization	Rich console output, file filtering
`flatten`	Code file aggregation	Multi-file concatenation, binary handling
`deps`	Dependency analysis	Python & Node.js support, extensible
`git-info`	Git context extraction	Branch info, commits, diffs, status
`bundle`	Multi-tool context aggregation	Configurable, structured output

Community & Support¶

Issues & Bug Reports
Found a bug or have a feature request? Open an issue with our detailed templates.
Report Issues
Discussions
Join the community discussion for questions, ideas, and collaboration.
Join Discussion
Security
Report security vulnerabilities through our responsible disclosure process.
Security Policy
Contributing
Help improve CodeBrief! Read our comprehensive contribution guidelines.
Contribute

Quick Links¶

Installation Guide - Get up and running in minutes
CLI Commands Reference - Complete command documentation
Configuration Guide - Advanced setup and customization
Bundle Workflows - Real-world usage examples
Contributing Guidelines - Join the development community
Security Policy - Report vulnerabilities responsibly

Ready to transform your development workflow?

Get Started Now