{"id":29463707,"url":"https://github.com/exonymos/codecat","last_synced_at":"2026-03-08T01:25:43.785Z","repository":{"id":301899024,"uuid":"1009791772","full_name":"Exonymos/codecat","owner":"Exonymos","description":"🐾 Codecat: A lightning-fast CLI tool that bundles your entire codebase into a single, clean Markdown file. Perfect for feeding context to LLMs, streamlining code reviews, and creating portable project archives.","archived":false,"fork":false,"pushed_at":"2025-07-12T18:39:55.000Z","size":903,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-12T20:42:11.427Z","etag":null,"topics":["archiving","automation","cli","code-aggregator","code-review","command-line-tool","developer-tools","llm","llm-tools","markdown","productivity","python","python-cli","rich","typer"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Exonymos.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-27T18:07:02.000Z","updated_at":"2025-07-12T18:35:21.000Z","dependencies_parsed_at":"2025-06-29T14:19:25.384Z","dependency_job_id":"ef9cfed5-8b93-40b2-b9e1-c67cbb8f37ac","html_url":"https://github.com/Exonymos/codecat","commit_stats":null,"previous_names":["exonymos/codecat"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/Exonymos/codecat","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Exonymos%2Fcodecat","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Exonymos%2Fcodecat/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Exonymos%2Fcodecat/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Exonymos%2Fcodecat/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Exonymos","download_url":"https://codeload.github.com/Exonymos/codecat/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Exonymos%2Fcodecat/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265246229,"owners_count":23734111,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["archiving","automation","cli","code-aggregator","code-review","command-line-tool","developer-tools","llm","llm-tools","markdown","productivity","python","python-cli","rich","typer"],"created_at":"2025-07-14T05:38:33.721Z","updated_at":"2026-03-08T01:25:43.770Z","avatar_url":"https://github.com/Exonymos.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🐾 Codecat\n\n\u003cdiv align=\"center\"\u003e\n\n**The ultimate code aggregator for LLMs, code reviews, and project archiving**\n\n_Transform your entire codebase into a single, beautifully formatted Markdown document_\n\n[![CI/CD Status](https://github.com/Exonymos/codecat/actions/workflows/ci.yml/badge.svg)](https://github.com/Exonymos/codecat/actions/workflows/ci.yml)\n[![Latest Release](https://img.shields.io/github/v/release/Exonymos/codecat?display_name=tag\u0026logo=github\u0026color=brightgreen)](https://github.com/Exonymos/codecat/releases/latest)\n[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-yellow.svg)](https://opensource.org/license/gpl-3-0)\n[![Downloads](https://img.shields.io/github/downloads/Exonymos/codecat/total?color=blue\u0026logo=github)](https://github.com/Exonymos/codecat/releases)\n[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)\n\n[**🚀 Quick Start**](#-quick-start) • [**📖 Usage**](#-usage) • [**💡 Examples**](#-examples) • [**🛠️ Development**](#%EF%B8%8F-development)\n\n\u003c/div\u003e\n\n---\n\n## 🌟 What is Codecat?\n\nCodecat is a lightning-fast, Python-powered CLI tool that **aggregates your entire project into a single, perfectly formatted Markdown file**. Built with [Typer](https://github.com/fastapi/typer) and [Rich](https://github.com/Textualize/rich), it features multi-threaded processing and an elegant terminal interface.\n\n**Perfect for:**\n\n- 🤖 **AI Development** - Feed complete project context to LLMs like GPT-4, Claude, or Copilot\n- 👥 **Code Reviews** - Share comprehensive project snapshots with your team\n- 📚 **Documentation** - Create portable archives of your codebase\n- 🔍 **Analysis** - Get insights into your project structure and statistics\n\n## ✨ Key Features\n\n### 🚀 **Performance First**\n\n- **Multi-threaded scanning** processes files in parallel\n- **Smart binary detection** skips non-text files automatically\n- **Optimized for large codebases** with thousands of files\n\n### 🎨 **Beautiful Interface**\n\n- **Rich CLI** with progress bars and color-coded output\n- **Real-time statistics** showing files processed and lines counted\n- **Intuitive commands** that just work out of the box\n\n### 🧠 **Intelligent Processing**\n\n- **Automatic language detection** for proper syntax highlighting\n- **Dynamic fence handling** for code blocks containing backticks\n- **Glob pattern support** for flexible file inclusion/exclusion\n\n### 🌐 **Interactive Web UI**\n\n- **Visual Dashboard** provides a browser-based interface to manage everything\n- **Fully Offline** operation with bundled assets—no internet required\n- **Seamless Integration** perfectly reflects all CLI capabilities\n\n### ⚙️ **Highly Configurable**\n\n- **JSON configuration** with sensible defaults\n- **Command-line overrides** for any setting\n- **Project-specific rules** via `.codecat_config.json`\n\n## 🚀 Quick Start\n\n### Installation\n\nChoose your preferred installation method:\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e📦 Pre-built Executables (Recommended)\u003c/b\u003e\u003c/summary\u003e\n\nDownload the latest executable for your platform from our [**Releases Page**](https://github.com/Exonymos/codecat/releases/latest):\n\n#### Windows\n\n```cmd\n# Download codecat-windows.exe and rename to codecat.exe\n# Add to PATH for global access\ncodecat --help\n```\n\n#### Linux\n\n```bash\n# Download codecat-linux\nchmod +x codecat-linux\nsudo mv codecat-linux /usr/local/bin/codecat\ncodecat --help\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e🐍 Install from Source\u003c/b\u003e\u003c/summary\u003e\n\n```bash\n# Clone the repository\ngit clone https://github.com/Exonymos/codecat.git\ncd codecat\n\n# Create virtual environment\npython -m venv .venv\n.venv\\Scripts\\activate  # On Linux: source .venv/bin/activate\n\n# Install in development mode\npip install -e .\n```\n\n\u003c/details\u003e\n\n### First Run\n\n```bash\n# Generate a config file (optional but recommended)\ncodecat generate-config\n\n# Scan your current project\ncodecat run .\n\n# View project statistics without creating output\ncodecat stats .\n```\n\n## 📖 Usage\n\n### Core Commands\n\n| Command                   | Description                               | Example                    |\n| ------------------------- | ----------------------------------------- | -------------------------- |\n| `codecat run \u003cpath\u003e`      | Scan directory and create Markdown output | `codecat run ./my-project` |\n| `codecat web`             | Launch the interactive Web UI             | `codecat web`              |\n| `codecat stats \u003cpath\u003e`    | Show project statistics without output    | `codecat stats .`          |\n| `codecat generate-config` | Create configuration template             | `codecat generate-config`  |\n\n### Command-Line Options\n\n```bash\n# Example: run with several common options\ncodecat run .\n  --output-file \"project-snapshot.md\"\n  --include \"*.py\"\n  --include \"*.md\"\n  --exclude \"tests/*\"\n  --verbose\n  --dry-run\n```\n\n| Option          | Description                   | Default             |\n| --------------- | ----------------------------- | ------------------- |\n| `--output-file` | Output filename               | `codecat_output.md` |\n| `--include`     | File patterns to include      | `*`                 |\n| `--exclude`     | File patterns to exclude      | See config          |\n| `--verbose`     | Detailed output               | `False`             |\n| `--dry-run`     | Preview without creating file | `False`             |\n\n## 💡 Examples\n\n### Basic Usage\n\n```bash\n# Simple scan of current directory\ncodecat run .\n\n# Launch the interactive web interface\ncodecat web\n\n# Scan specific directory with custom output\ncodecat run ./my-project --output-file \"project-complete.md\"\n\n# Get project insights without generating output\ncodecat stats ./large-codebase\n```\n\n### Advanced Filtering\n\nUse flags multiple times for multiple patterns.\n\n```bash\n# Include only Python, TypeScript, and JavaScript files\ncodecat run . --include \"*.py\" --include \"*.js\" --include \"*.ts\" --output-file \"backend-code.md\"\n\n# Exclude test directories, config files, and node_modules\ncodecat run . --exclude \"test*\" --exclude \"*config*\" --exclude \"node_modules\"\n```\n\n### Configuration-Based Workflow\n\n```bash\n# 1. Generate config template\ncodecat generate-config\n\n# 2. Edit .codecat_config.json to your needs\n# 3. Run with your custom configuration\ncodecat run .\n```\n\n## 🛠️ Development\n\n### Setting Up Development Environment\n\n```bash\n# Fork and clone\ngit clone https://github.com/YOUR-USERNAME/codecat.git\ncd codecat\n\n# Setup virtual environment\npython -m venv .venv\n.venv\\Scripts\\activate  # On Linux: source .venv/bin/activate\n\n# Install with development dependencies\npip install -e .[dev]\n```\n\n### Development Workflow\n\n```bash\n# Format code\nblack .\n\n# Lint code\nflake8 .\n\n# Type checking\npyright .\n\n# Run tests with coverage\npytest --cov=src/codecat --cov-report=html\n\n# Run specific test\npytest tests/test_config.py -v\n```\n\n### Building Executables\n\n```bash\n# Windows\npython generate_version_file.py\npyinstaller codecat.spec\n\n# Linux\npyinstaller --noconfirm --onefile --console --name codecat src/codecat/__main__.py\n```\n\n### Contributing Guidelines\n\nWe welcome contributions! Please:\n\n1. **Fork** the repository\n2. **Create** a feature branch (`git checkout -b feature/amazing-feature`)\n3. **Follow** our coding standards (Black formatting, type hints)\n4. **Add tests** for new functionality\n5. **Update documentation** if needed\n6. **Submit** a pull request\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md) for detailed guidelines.\n\n## 🤔 FAQ\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eWhy use Codecat instead of manual copy-paste?\u003c/b\u003e\u003c/summary\u003e\n\nCodecat automatically handles:\n\n- File discovery and filtering\n- Binary file detection\n- Proper Markdown formatting\n- Code block escaping\n- Project statistics\n- Large codebase processing\n\nManual approaches are error-prone and time-consuming for anything beyond trivial projects.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eHow does Codecat handle large projects?\u003c/b\u003e\u003c/summary\u003e\n\nCodecat uses multi-threading to process files in parallel and includes safeguards:\n\n- Configurable file size limits\n- Binary file detection and skipping\n- Memory-efficient streaming for large files\n- Progress indication for long-running operations\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eWhat file types does Codecat support?\u003c/b\u003e\u003c/summary\u003e\n\nCodecat processes any text-based file and automatically detects:\n\n- Programming languages (Python, JavaScript, Java, C++, etc.)\n- Markup languages (HTML, XML, Markdown)\n- Configuration files (JSON, YAML, TOML, INI)\n- Documentation files (TXT, RST, etc.)\n\nBinary files are automatically skipped to prevent corruption.\n\n\u003c/details\u003e\n\n## 📄 License\n\nThis project is licensed under the **GNU General Public License v3.0** - see the [LICENSE](./LICENSE) file for details.\n\n## 🙋‍♂️ Support\n\n- **🐛 Bug Reports**: [Open an issue](https://github.com/Exonymos/codecat/issues/new?template=bug_report.md)\n- **💡 Feature Requests**: [Request a feature](https://github.com/Exonymos/codecat/issues/new?template=feature_request.md)\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**⭐ If Codecat helps you, please consider giving it a star on GitHub! ⭐**\n\n_Made with ❤️ by developers, for developers_\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fexonymos%2Fcodecat","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fexonymos%2Fcodecat","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fexonymos%2Fcodecat/lists"}