📦 Code Collector for LLMs

🇷🇺 Читать на русском (Read in Russian)

---

Code Collector is a powerful yet highly user-friendly Python script designed to flatten and merge an entire project's codebase into a single, beautifully formatted Markdown (.md) file.

💡 Why? The Main Idea

Modern LLMs (ChatGPT, Claude, Gemini, Grok, etc.) thrive on extensive context. However, uploading dozens of nested source files or pasting code snippet by code snippet can be tedious and error-prone.

This script solves that problem by transforming your complex multi-directory repository into one cohesive text document containing:

1. An interactive ASCII project tree showing your exact repository layout.
2. A distinct section for each file with its relative name, absolute path, and fully syntax-highlighted code block.

Just run the script, take the output .md file, and feed it directly into your favorite AI assistant!

---

✨ Features

• Interactive Wizard Mode: Run the script without any arguments, and it will politely ask you for configurations step-by-step in your terminal.
• Smart Defaults: Out-of-the-box support for logical default paths (places the output and looks for .projignore right in the scanned project root).
• Binary & Non-Text Protection: Automatically detects and skips binary files (images, PDFs, compiled binaries) so your output file stays pristine and text-only.
• Nested Backtick Escape: If your source code already contains Markdown code blocks (```), the script elegantly wraps them in four backticks (````) so formatting never breaks.
• Extensive Language Syntax Mapping: Pre-configured with over 40 standard file extensions to ensure correct Markdown syntax highlighting (python, typescript, go, rust, cpp, etc.).

---

🚀 Usage

1. Interactive Mode (No arguments)

The easiest way to use the script is to simply run it:

python collect_code.py

The script will launch an interactive wizard and guide you through the process:

==================================================
 📦 Code Collector for LLMs — Interactive Mode 
==================================================

1. Enter project root directory to scan [default: .]: 
2. Enter output Markdown file path [default: /path/to/project/project_code.md]: 
3. Enter ignore file path [default: /path/to/project/.projignore]: 
4. Enter document title [default: Project Codebase]: 

Just press Enter on any prompt to accept the sensible default!

---

2. Command Line Interface (CLI)

Perfect for automation, CI/CD pipelines, or power users.

python collect_code.py -d /path/to/my_app -o /path/to/my_app/complete_code.md --title "My App Frontend"

Argument	Short	Default	Description
--dir	-d	. (Current dir)	Project root directory to traverse and scan.
--output	-o	<project_root>/project_code.md	Path where the combined Markdown file will be saved.
--ignore	-i	<project_root>/.projignore	Path to your custom ignore patterns file.
--title		"Project Codebase"	The top-level heading used in the output Markdown document.

---

📂 Default Paths & Logic

1. Target Output File: By default, the script places project_code.md directly inside the target directory you are scanning (<project_root>/project_code.md).
2. Self-Ignore Logic: The script intelligently detects the final output file path and excludes it from the scan so it doesn't accidentally ingest earlier exports.
3. Ignore Rules File: Looks for a .projignore file located inside the target directory (<project_root>/.projignore).

---

🚫 Ignoring Files (.projignore)

The script behaves very similarly to Git. You can create a .projignore file in your project root using standard glob patterns.

Default Ignored Patterns (Active even without a .projignore file):

• Version control: .git, .svn, .hg
• IDE configs: .idea, .vscode
• Python caches: __pycache__, *.pyc, *.pyo, *.pyd
• System files: .DS_Store

Example .projignore:

# Ignore node packages and environment folders
node_modules/
venv/
.env

# Ignore builds and logs
build/
dist/
*.log

---

🗺️ Extension to Language Mapping

The script automatically detects file extensions and applies the correct Markdown syntax identifier. Here is the default mapping built into the tool:

Extensions	Language Tag	Extensions	Language Tag
.py	python	.c, .h	c
.js	javascript	.cpp, .hpp	cpp
.ts	typescript	.cs	csharp
.html	html	.go	go
.css	css	.rs	rust
.scss	scss	.rb	ruby
.json	json	.php	php
.xml	xml	.sql	sql
.yaml, .yml	yaml	.dockerfile	dockerfile
.md	markdown	.graphql	graphql
.txt	text	.vue	vue
.sh	bash	.jsx	jsx
.bat	batch	.tsx	tsx
.java	java	.swift	swift
.kt	kotlin	.scala	scala
.pl	perl	.lua	lua
.dart	dart	.r	r

---

🛠️ Contributing & Modifications

This script is completely self-contained with zero external dependencies (uses only standard Python libraries). Feel free to fork, modify, or drop it into any existing toolkit!

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.