Viterbo

A tool for collecting and documenting code files for LLM context.

Overview

Viterbo helps collect source code files from various languages and compile them into a readable format for inclusion in LLM prompts. It scans directories and individual files, extracts structured information like docstrings and comments, and generates comprehensive documentation in text or markdown format.

Features

• Multiple input sources: Process directories and specific files in a single command
• Multi-language support: Python, C/C++, R, JavaScript, TypeScript, and many other languages
• Directory tree visualization: Shows the structure of your codebase
• Documentation extraction: Extracts docstrings, comments, and code structure
• Output formats: Generate documentation in plain text or markdown
• README inclusion: Optionally include README.md files in the documentation
• Line numbering: Add line numbers to code for easy reference
• Organized output: Collects code with clear section headers showing file paths
• Clipboard support: Copy output directly to clipboard for easy pasting

Installation

# Install with Poetry
poetry install

# Or using pip
pip install viterbo

For clipboard functionality, make sure to install the required dependency:

# Using Poetry
poetry add pyperclip

# Or with pip
pip install pyperclip

Usage

Command Line

# Basic usage - copy Python files to clipboard
viterbo source_directory

# Process specific files and copy to clipboard
viterbo file1.py file2.py file3.py

# Process mixed directories and files
viterbo src/ utils.py config/ main.py

# Save to output file with -o/--output-file flag
viterbo source_directory -o output.txt

# Multiple sources with output file
viterbo src/ lib/ main.py --output-file doc.txt

# Enhanced usage with multi-language support
viterbo /path/to/source -o output.txt --extensions .py .cpp .h .R

# Include README.md files
viterbo /path/to/source --include-readme -o output.txt

# Extract and include docstrings/comments
viterbo /path/to/source --include-docstrings -o output.txt

# Add line numbers to code
viterbo /path/to/source --add-line-numbers -o output.txt

# Generate markdown output
viterbo /path/to/source main.py -o output.md --format md

Python API

from viterbo import document_files

# Document Python and C++ files in markdown format
document_files(
    source_paths=["/path/to/source", "main.py", "/another/dir"],
    output_file="output.md",
    file_extensions=[".py", ".cpp", ".h"],
    include_readme=True,
    include_docstrings=True,
    add_line_numbers=True,
    output_format="md"
)

# Copy to clipboard instead of writing to a file
document_files(
    source_paths=["src/", "main.py", "config.py"],
    output_file=None,  # None means copy to clipboard
    file_extensions=[".py", ".js"],
    include_docstrings=True
)

# For backward compatibility, the original function is still available
from viterbo import document_python_files

document_python_files(
    source_paths="/path/to/source",  # Either a string or list of paths
    output_file="output.txt",  # or None for clipboard
    include_docstrings=True,
    add_line_numbers=True
)

Output Examples

Text Output

# Code Documentation
# Generated on: 2025-05-01 10:21:33
# Sources: 3 directories/files
#   1. /path/to/source
#   2. main.py
#   3. /another/dir

# Directory Structure:
/path/to/source/
├── README.md
├── src/
│   ├── main.py
│   └── utils.py
└── tests/
    └── test_main.py

main.py

/another/dir/
├── config.py
└── helpers.py
...

Markdown Output

The markdown output includes syntax highlighting and better formatting for documentation.

Clipboard Support

When no output file is specified, Viterbo will copy the documentation to your system clipboard:

# Copy documentation to clipboard
viterbo ./my_project --include-docstrings

This is especially useful when:

• Quickly retrieving code for pasting into an LLM interface
• Sharing code snippets in messaging apps
• Documenting code without creating temporary files

Development

# Clone the repository
git clone https://github.com/pboerr/viterbo.git
cd viterbo

# Install development dependencies
poetry install

# Running tests
poetry run pytest

# Building the package
poetry build

License

MIT