Skip to content

README.md

Latest commit

 

History

History
318 lines (217 loc) · 8.96 KB

README.md

File metadata and controls

318 lines (217 loc) · 8.96 KB

🐾 Codecat

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

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

CI/CD Status Latest Release License: GPL v3 Downloads Python Version

🚀 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

⭐ If Codecat helps you, please consider giving it a star on GitHub! ⭐

Made with ❤️ by developers, for developers