CodeSummary

A cross-platform CLI tool that scans your project's source code and generates repository documentation optimized for both human review and Large Language Models (LLMs).

• LLM Markdown — Token-optimized single file designed for direct consumption by any chat-based AI.
• PDF Documentation — Clean, professional A4 reports for code reviews, audits, and archival.
• Structured Context — Emits .llmsummary.json for downstream agentic workflows.

🚀 Key Features

• LLM-First Output: Optimized Markdown with lossless compression (whitespace stripping, JSON compaction) to maximize context window efficiency.
• Deep Dependency Analysis: Internal file-level graph engine with centrality metrics and hub/node identification.
• Semantic Clustering: Heuristic-based capability grouping (CLI, logic, utilities, etc.) to help AI understand project structure.
• Language-Aware Extraction: Specialized adapters for JavaScript/TypeScript and Python, with a universal fallback for 50+ other languages.
• Professional PDF Reports: High-quality snapshots including file trees, AI-assisted executive briefs, and syntax-highlighted source code.
• Intelligent Scanning: Recursive traversal with configurable filters and robust .csignore support (gitignore-style syntax).
• Versioned Output: Automatic -v1, -v2 suffixes prevent overwriting previous reports.
• CI/CD Ready: --no-interactive mode for automated documentation pipelines.

📦 Installation

npm install -g codesummary

Requirements: Node.js ≥ 18.0.0

🎯 Output Modes

💬 LLM — Direct Chat Context

Generate a single, token-optimized Markdown file to paste into ChatGPT, Claude, or any other LLM:

codesummary --format llm
# Output: PROJECT_llm.md

The file includes a project overview, a suggested reading order, dependency graphs, and full file contents with language hints. Lossless optimizations (normalizing line endings, stripping trailing whitespace, compacting JSON) are applied automatically.

📄 PDF — Audits & Handovers

Generate a professional A4 PDF for human consumption:

codesummary --format pdf
# Output: PROJECT_code.pdf

Best for: code reviews, client handovers, compliance audits, and physical archiving.

📖 Usage

Quick Start

# First run: Interactive setup wizard
codesummary

# Generate LLM Markdown for the current project
codesummary --format llm

# Generate both formats in one run
codesummary --format both

# Generate a task-focused context pack (prioritizes relevant files)
codesummary --format llm --focus "authentication flow" --max-tokens 12000

Interactive Workflow

1. First-Run Setup: Detects missing configuration and launches a wizard to set your default output paths.
2. Extension Selection: Choose which file types to include (e.g., .ts, .py, .md).
3. Generation: Files are scanned, analyzed, and rendered to your chosen format.

Optional AI Enrichment

Enhance your reports with AI-generated architecture insights:

# Using local Ollama
codesummary --format llm --ai-semantic --provider ollama --model llama3.1

# Using an OpenAI-compatible endpoint
codesummary --format llm --ai-semantic --provider openai-compatible --api-key YOUR_KEY

Note: AI enrichment is optional. If the provider is unavailable, CodeSummary falls back to heuristic analysis.

⚙️ Configuration

Configuration is stored globally at:

• Windows: %APPDATA%\CodeSummary\config.json
• Linux/macOS: ~/.codesummary/config.json

Existing settings are preserved during upgrades; new defaults are merged automatically.

.csignore Support

Use a .csignore file in your project root to exclude sensitive paths (keys, tokens, private data) using standard .gitignore syntax.

🛠️ Project Structure

• bin/codesummary.js: CLI Entry point.
• src/cli.js: Argument parsing and flow orchestration.
• src/scanner.js: Recursive file system traversal and filtering.
• src/graph/: Dependency graph engine and language adapters.
• src/llmGenerator.js: Token-optimized Markdown generation.
• src/pdfGenerator.js: High-fidelity PDF generation (PDFKit).
• src/configManager.js: Global configuration and migration logic.

🤝 Contributing

1. Fork the repository.
2. Clone: git clone https://github.com/skamoll/CodeSummary.git
3. Install: npm install
4. Submit a pull request.

📄 License

Distributed under the GNU General Public License v3.0. See LICENSE for details.

📊 Roadmap

• [x] LLM-optimized Markdown output.
• [x] Versioned output filenames.
• [x] Deep dependency graph analysis.
• [x] VS Code Extension (MVP).
• [ ] Automated regression test suite.

See ROADMAP.md for detailed product direction.