Summ - Folder Summarization Tool

A powerful, AI-powered documentation generator that analyzes your entire project folder and creates comprehensive markdown documentation with parallel processing and smart guardrails.

Features

🔍 Universal File Analysis - Supports code, data, images, archives, and more
🎨 AI-Powered Descriptions - Uses LLM to generate intelligent summaries
⚡ Parallel Processing - Up to 25 concurrent threads for fast processing
🛡️ Smart Guardrails - Prevents accidental generation of massive files
📄 llms.txt Compatible - Creates documentation perfect for AI consumption
🖼️ Image Processing - Automatically resizes images for efficient analysis
📦 Archive Inspection - Analyzes compressed files without extraction

Installation

Simply download the summ script and make it executable:

chmod +x summ
# Optional: Move to your PATH
mv summ /usr/local/bin/

Usage

Basic Usage

# Generate documentation for current folder
summ

# Specify custom output file
summ my-project-docs.md

# Use custom thread count
summ -t 10 docs.md

Command Line Options

Usage: summ [options] [output-file]

Options:
  -h, --help           Show this help message
  -t, --threads NUM    Number of parallel threads (default: 25)

Examples:
  summ                    # Default: ../FolderName.md
  summ report.md          # Custom filename
  summ -t 5 docs.md      # Use 5 threads

Supported File Types

Code & Configuration

• Programming Languages: .py, .js, .ts, .jsx, .tsx, .go, .rs, .java, .c, .cpp, .php, .rb, .swift, .kt, .scala, .sh
• Web Technologies: .html, .css, .scss
• Configuration: .json, .xml, .yaml, .yml, .toml, .ini, .cfg, .conf
• Documentation: .md, .txt
• Database: .sql

Data Files

• Spreadsheets: .csv, .xls, .xlsx (automatically converted to CSV)
• Logs: .log

Media & Archives

• Images: .png, .jpg, .jpeg, .gif, .bmp, .svg, .webp
• Archives: .zip, .tar.gz, .tar, .7z, .rar

Smart Guardrails

Summ includes intelligent protection against resource-intensive operations:

File Count Limit (1000 files)

🚨 Large operation detected:
   📊 Files to process: 1,247
   ⚠️  File count exceeds 1000 files

Size Limit (10MB estimated output)

🚨 Large operation detected:
   💾 Estimated output size: 15MB
   ⚠️  Estimated output size exceeds 10MB

When limits are exceeded, you'll be prompted:

Do you want to continue? (y/N):

Parallel Processing

Summ processes files concurrently for maximum performance:

• Default: 25 parallel threads
• Configurable: Use -t to specify thread count
• Intelligent: Automatically manages job queuing and completion
• Safe: Combines results in proper order

Performance Example

# Sequential processing: ~5 minutes for 100 files
# Parallel processing: ~30 seconds for 100 files (25 threads)

Output Format

Generates structured markdown documentation with:

Project Overview

# ProjectName Documentation

## Project Structure

test_features/ ├── code/app.py ├── data/sample.csv ├── images/logo.png └── README.md

### File Analysis
Each file gets detailed analysis:

```markdown
## Code/Text: app.py

**Purpose:** This Python script implements a simple calculator application with basic arithmetic operations including addition and subtraction, designed as a command-line utility for demonstration purposes.

**File:** `code/app.py`
**Type:** py file
**Usage:** Code/configuration/documentation file

<details>
<summary>Full Content</summary>

```python
#!/usr/bin/env python3
# ... full file contents

```

Dependencies

Required

• LLM Tool: Uses uvx llm for AI analysis
• Shell: zsh or bash

Optional (for enhanced functionality)

• Excel Processing: xlsx2csv, pandas, or macOS Numbers
• Image Processing: sips (macOS) or ImageMagick
• Archive Tools: unzip, tar, 7z, unrar

Examples

Basic Project Documentation

cd my-project
summ
# Creates: ../my-project.md

Custom Configuration

# Fast processing for small projects
summ -t 5 quick-docs.md

# High throughput for large codebases
summ -t 50 comprehensive-docs.md

Integration with AI Tools

# Generate docs and analyze with Claude
summ project-analysis.md
cat project-analysis.md | llm "Analyze this codebase structure"

Advanced Usage

Performance Tuning

• Small projects (<50 files): -t 5
• Medium projects (50-200 files): -t 15 (default works well)
• Large projects (200+ files): -t 50 (if system resources allow)

Workflow Integration

#!/bin/bash
# Auto-generate docs on git commit
cd project-root
summ docs/auto-generated.md
git add docs/auto-generated.md

Troubleshooting

Common Issues

"uvx command not found"

# Install uvx
curl -LsSf https://astral.sh/uv/install.sh | sh
# Then install llm
uvx install llm

Excel conversion fails

# Install pandas support
uvx --from pandas python -c "import pandas; print('OK')"

Image processing errors

# macOS: sips should be available by default
# Linux: Install ImageMagick
sudo apt install imagemagick  # Ubuntu/Debian

Archive reading fails

# Install missing tools
brew install p7zip unrar  # macOS
sudo apt install p7zip unrar  # Ubuntu/Debian

License

MIT License - feel free to use and modify as needed.

Contributing

Contributions welcome! Areas for improvement:

• Additional file type support
• Performance optimizations
• Enhanced AI prompts
• Better error handling

---

Generated with Summ - Your AI-powered documentation companion