Skip to content

Quick Start Guide

This guide will help you get up and running with ProjectLens quickly. We'll cover basic usage patterns for both the command-line interface and Python API.

Basic CLI Usage

The simplest way to use ProjectLens is through its command-line interface:

projectlens <folder_path> -x <extensions>

Where: - <folder_path> is the path to your project directory - -x <extensions> specifies which file extensions to include (required)

Example: Basic Scanning

Scan a project for Python, Markdown, and TOML files:

projectlens ~/myproject -x py md toml

This will: 1. Scan all files with .py, .md, and .toml extensions 2. Generate a tree structure of your project 3. Create an output file named myproject_YYYYMMDD_HHMM.txt

Example: Including Specific Files

Include additional files regardless of their extension:

projectlens ~/myproject -x py -i Dockerfile Makefile .env.example

Example: Excluding Patterns

Exclude specific directories or file patterns:

projectlens ~/myproject -x py md -e tests docs "*cache*"

Example: Custom Output File

Specify your own output filename:

projectlens ~/myproject -x py -o project_for_llm_review.txt

Example: Verbose Mode

Get detailed information about what's being processed:

projectlens ~/myproject -x py --verbose

Basic Python API Usage

You can also use ProjectLens programmatically in your Python scripts:

from projectlens import ProjectLens

# Initialize the scanner
lens = ProjectLens(
    extensions=["py", "md", "yml"],
    include=["Dockerfile", ".gitignore"],
    exclude=["tests", "build", "*cache*"],
    max_file_size=500  # in KB
)

# Scan and export project
lens.export_project(
    folder_path="/path/to/project",
    output="project_snapshot.txt"  # Optional
)

# Access metadata about the scan
print(f"Files scanned: {len(lens.metadata.scanned_files)}")
print(f"Directories skipped: {len(lens.metadata.skipped_dirs)}")

Understanding the Output

ProjectLens generates a single text file containing:

  1. Header information:
  2. Generation timestamp
  3. Source directory
  4. Included file extensions

  5. Exclude patterns

  6. Project tree structure:

  7. Visual representation of your project's directory hierarchy

  8. File contents:

  9. Each file's content with clear separation and formatting
  10. Consistent headers and separators for easy parsing

Using Output with LLMs

The output is specifically formatted to be easily parsed by Large Language Models (LLMs). To use it:

  1. Upload the generated file into your LLM chat (ChatGPT, ClaudeAI, etc.)
  2. Ask questions about your project structure, code patterns, or request improvements

For example, you might prompt the LLM with: - "Analyze this project's structure and suggest improvements" - "How can I improve the modularization of this project adopting best practices?" - "How can I optimize file/function X?" - "Write numpy-style docstring for all functions from Y" - "Help me understand the flow of data in this application" - "Generate comprehensive documentation for this project"

Next Steps