Cram

A Python CLI tool that converts any local folder, GitHub repository, or file into a single structured markdown file containing the entire codebase.

Installation

pip install -e .

Or with pip from source:

git clone https://github.com/osfv/cram.git
cd cram
pip install -e .

Usage

Basic Usage

# Local directory
cram /path/to/project

# Single file
cram /path/to/file.py

# GitHub repository
cram https://github.com/user/repo

Options

# Filter by file extensions
cram ./my-project --ext .py --ext .js

# Exclude patterns
cram ./my-project --exclude tests --exclude docs

# Copy to clipboard instead of file
cram ./my-project --clip

# Specify output file
cram ./my-project -o output.md

# Combine options
cram ./my-project --ext .py --exclude tests -o python_only.md

Features

• Smart filtering: Automatically skips binary files, node_modules, and files over 500KB
• Gitignore support: Respects .gitignore patterns in the repository
• GitHub integration: Clone and process repositories directly from GitHub URLs
• Token estimation: Provides rough token count for LLM context planning
• Clean output: Generates well-structured markdown with table of contents
• Clipboard support: Option to copy output directly to clipboard
• Rich terminal UI: Progress indicators and colored output

Output Format

Cram generates markdown with:

1. Summary header with metadata
2. Table of contents with file links
3. Code blocks with syntax highlighting
4. All files sorted alphabetically

Example:

# Codebase Summary

**Source:** `/path/to/project`
**Generated:** 2026-03-18 10:30:00
**Files:** 42

## Table of Contents

- [src/main.py](#srcmainpy)
- [src/utils.py](#srcutilspy)
...

---

## src/main.py

\`\`\`python
def main():
    print("Hello, world!")
\`\`\`

...

Automatic Exclusions

Cram automatically skips:

• Binary files (images, videos, fonts, executables)
• Common dependency directories (node_modules, venv, .git)
• Cache directories (__pycache__, .pytest_cache)
• Files larger than 500KB
• Files matching .gitignore patterns

Error Handling

Cram provides clear error messages for:

• Non-existent paths
• Private or unavailable GitHub repositories
• Permission issues
• Clipboard failures

Requirements

• Python 3.10+
• Dependencies: click, pathspec, pyperclip, rich, gitpython

License

MIT