🐾 Codecat

The ultimate code aggregator for LLMs, code reviews, and project archiving

Transform your entire codebase into a single, beautifully formatted Markdown document

🚀 Quick Start • 📖 Usage • 💡 Examples • 🛠️ Development

---

🌟 What is Codecat?

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

✨ Key Features

🚀 Performance First

• Multi-threaded scanning processes files in parallel
• Smart binary detection skips non-text files automatically
• Optimized for large codebases with thousands of files

🎨 Beautiful Interface

• 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

🧠 Intelligent Processing

• Automatic language detection for proper syntax highlighting
• Dynamic fence handling for code blocks containing backticks
• Glob pattern support for flexible file inclusion/exclusion

🌐 Interactive Web UI

• Visual Dashboard provides a browser-based interface to manage everything
• Fully Offline operation with bundled assets—no internet required
• Seamless Integration perfectly reflects all CLI capabilities

⚙️ Highly Configurable

• JSON configuration with sensible defaults
• Command-line overrides for any setting
• Project-specific rules via .codecat_config.json

🚀 Quick Start

Installation

Choose your preferred installation method:

📦 Pre-built Executables (Recommended)

Download the latest executable for your platform from our Releases Page:

Windows

# Download codecat-windows.exe and rename to codecat.exe
# Add to PATH for global access
codecat --help

Linux

# 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 .

First Run

# Generate a config file (optional but recommended)
codecat generate-config

# Scan your current project
codecat run .

# View project statistics without creating output
codecat stats .

📖 Usage

Core Commands

Command	Description	Example
codecat run <path>	Scan directory and create Markdown output	codecat run ./my-project
codecat web	Launch the interactive Web UI	codecat web
codecat stats <path>	Show project statistics without output	codecat stats .
codecat generate-config	Create configuration template	codecat generate-config

Command-Line Options

# 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

💡 Examples

Basic Usage

# Simple scan of current directory
codecat run .

# Launch the interactive web interface
codecat web

# Scan specific directory with custom output
codecat run ./my-project --output-file "project-complete.md"

# Get project insights without generating output
codecat stats ./large-codebase

Advanced Filtering

Use 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"

Configuration-Based Workflow

# 1. Generate config template
codecat generate-config

# 2. Edit .codecat_config.json to your needs
# 3. Run with your custom configuration
codecat run .

🛠️ Development

Setting Up Development Environment

# 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]

Development Workflow

# 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

Building Executables

# Windows
python generate_version_file.py
pyinstaller codecat.spec

# Linux
pyinstaller --noconfirm --onefile --console --name codecat src/codecat/__main__.py

Contributing Guidelines

We welcome contributions! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Follow our coding standards (Black formatting, type hints)
4. Add tests for new functionality
5. Update documentation if needed
6. Submit a pull request

See CONTRIBUTING.md for detailed guidelines.

🤔 FAQ

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.

📄 License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.

🙋‍♂️ Support

• 🐛 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