The ultimate code aggregator for LLMs, code reviews, and project archiving
Transform your entire codebase into a single, beautifully formatted Markdown document
Codecat is a lightning-fast, Python-powered CLI tool that aggregates your entire project into a single, perfectly formatted Markdown file. Built with Typer and Rich, it features multi-threaded processing and an elegant terminal interface.
Perfect for:
- 🤖 AI Development - Feed complete project context to LLMs like GPT-4, Claude, or Copilot
- 👥 Code Reviews - Share comprehensive project snapshots with your team
- 📚 Documentation - Create portable archives of your codebase
- 🔍 Analysis - Get insights into your project structure and statistics
- Multi-threaded scanning processes files in parallel
- Smart binary detection skips non-text files automatically
- Optimized for large codebases with thousands of files
- Rich CLI with progress bars and color-coded output
- Real-time statistics showing files processed and lines counted
- Intuitive commands that just work out of the box
- Automatic language detection for proper syntax highlighting
- Dynamic fence handling for code blocks containing backticks
- Glob pattern support for flexible file inclusion/exclusion
- JSON configuration with sensible defaults
- Command-line overrides for any setting
- Project-specific rules via
.codecat_config.json
Choose your preferred installation method:
📦 Pre-built Executables (Recommended)
Download the latest executable for your platform from our Releases Page:
# Download codecat-windows.exe and rename to codecat.exe
# Add to PATH for global access
codecat --help# Download codecat-linux
chmod +x codecat-linux
sudo mv codecat-linux /usr/local/bin/codecat
codecat --help🐍 Install from Source
# Clone the repository
git clone https://github.com/Exonymos/codecat.git
cd codecat
# Create virtual environment
python -m venv .venv
.venv\Scripts\activate # On Linux: source .venv/bin/activate
# Install in development mode
pip install -e .# Generate a config file (optional but recommended)
codecat generate-config
# Scan your current project
codecat run .
# View project statistics without creating output
codecat stats .| Command | Description | Example |
|---|---|---|
codecat run <path> |
Scan directory and create Markdown output | codecat run ./my-project |
codecat stats <path> |
Show project statistics without output | codecat stats . |
codecat generate-config |
Create configuration template | codecat generate-config |
# Example: run with several common options
codecat run .
--output-file "project-snapshot.md"
--include "*.py"
--include "*.md"
--exclude "tests/*"
--verbose
--dry-run| Option | Description | Default |
|---|---|---|
--output-file |
Output filename | codecat_output.md |
--include |
File patterns to include | * |
--exclude |
File patterns to exclude | See config |
--verbose |
Detailed output | False |
--dry-run |
Preview without creating file | False |
# Simple scan of current directory
codecat run .
# Scan specific directory with custom output
codecat run ./my-project --output-file "project-complete.md"
# Get project insights without generating output
codecat stats ./large-codebaseUse flags multiple times for multiple patterns.
# Include only Python, TypeScript, and JavaScript files
codecat run . --include "*.py" --include "*.js" --include "*.ts" --output-file "backend-code.md"
# Exclude test directories, config files, and node_modules
codecat run . --exclude "test*" --exclude "*config*" --exclude "node_modules"# 1. Generate config template
codecat generate-config
# 2. Edit .codecat_config.json to your needs
# 3. Run with your custom configuration
codecat run .# Fork and clone
git clone https://github.com/YOUR-USERNAME/codecat.git
cd codecat
# Setup virtual environment
python -m venv .venv
.venv\Scripts\activate # On Linux: source .venv/bin/activate
# Install with development dependencies
pip install -e .[dev]# Format code
black .
# Lint code
flake8 .
# Type checking
pyright .
# Run tests with coverage
pytest --cov=src/codecat --cov-report=html
# Run specific test
pytest tests/test_config.py -v# Windows
python generate_version_file.py
pyinstaller codecat.spec
# Linux
pyinstaller --noconfirm --onefile --console --name codecat src/codecat/__main__.pyWe welcome contributions! Please:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Follow our coding standards (Black formatting, type hints)
- Add tests for new functionality
- Update documentation if needed
- Submit a pull request
See CONTRIBUTING.md for detailed guidelines.
Why use Codecat instead of manual copy-paste?
Codecat automatically handles:
- File discovery and filtering
- Binary file detection
- Proper Markdown formatting
- Code block escaping
- Project statistics
- Large codebase processing
Manual approaches are error-prone and time-consuming for anything beyond trivial projects.
How does Codecat handle large projects?
Codecat uses multi-threading to process files in parallel and includes safeguards:
- Configurable file size limits
- Binary file detection and skipping
- Memory-efficient streaming for large files
- Progress indication for long-running operations
What file types does Codecat support?
Codecat processes any text-based file and automatically detects:
- Programming languages (Python, JavaScript, Java, C++, etc.)
- Markup languages (HTML, XML, Markdown)
- Configuration files (JSON, YAML, TOML, INI)
- Documentation files (TXT, RST, etc.)
Binary files are automatically skipped to prevent corruption.
This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.
- 🐛 Bug Reports: Open an issue
- 💡 Feature Requests: Request a feature
⭐ If Codecat helps you, please consider giving it a star on GitHub! ⭐
Made with ❤️ by developers, for developers