llm-cartographer

A plugin for Simon Willison's LLM tool that automatically maps and describes a codebase or project structure in a way which is token-efficient and ready to be consumed by an LLM.

Installation

pip install llm-cartographer

Or directly from the repository:

pip install git+https://github.com/yourusername/llm-cartographer.git

Usage

Basic usage:

llm cartographer /path/to/your/project

This will analyze the project directory and generate a comprehensive description of the codebase structure, which is then processed by an LLM to provide insights.

Options

Options:
  -e, --exclude TEXT             Patterns to exclude (gitignore format)
  --max-files INTEGER            Maximum number of files to analyze (default: 100)
  --max-file-size INTEGER        Maximum file size in bytes (default: 102400)
  -o, --output PATH              Output file path or directory
  -m, --model TEXT               LLM model to use
  --follow-symlinks              Follow symbolic links
  --json                         Output as JSON
  -f, --filter-extension TEXT    Only include files with these extensions
  --cache-dir TEXT               Cache directory path
  --mode [overview|components|architecture|flows]
                                 Analysis mode (default: overview)
  --focus TEXT                   Focus analysis on a specific subdirectory
  --reasoning INTEGER RANGE      Reasoning depth (0-9, where 0=minimal and 9=maximum) (default: 5)
  --visual                       Generate visual diagram of codebase architecture
  --diagram-format [graphviz|mermaid|plantuml]
                                 Format for diagram generation (default: graphviz)
  --llm-nav                      Enable LLM-based codebase navigation
  --help                         Show this message and exit.

Codebase Architecture Diagram

graph LR
    A[CLI] --> B[Core Module]
    B --> C[Directory Scanner]
    B --> D[Map Generator]
    D --Visual Diagram--> E[Visualization Module]
    B --> F[LLM Integration]
    B --> G[Output Formatter]
    G --> H[File Output]

    classDef module fill:#bbf,stroke:#333,stroke-width:1px;
    classDef cli fill:#f96,stroke:#333,stroke-width:1px;
    classDef output fill:#9f6,stroke:#333,stroke-width:1px;

    class A,G,H cli;
    class B,C,D,E,F module;
    class G,H output;

Examples

Analyze current directory with default settings:

llm cartographer .

Analyze a specific project and save results:

llm cartographer /path/to/project --output analysis.md

Analyze only Python files:

llm cartographer . --filter-extension py

Use a specific LLM model:

llm cartographer . --model gpt-4o

Focus on a specific subdirectory:

llm cartographer . --focus src/core

Use component-focused analysis mode:

llm cartographer . --mode components

Increase reasoning depth for more detailed analysis:

llm cartographer . --reasoning 8

Generate a visual diagram of the codebase architecture:

llm cartographer . --visual

Generate a Mermaid diagram (Markdown-compatible):

llm cartographer . --visual --diagram-format mermaid

Generate a PlantUML diagram:

llm cartographer . --visual --diagram-format plantuml

Save output to a directory (creates analysis.md and diagram file):

llm cartographer . --visual --output ./results

Features

• 🔍 Comprehensive Analysis: Scans directory structure, important files, language statistics
• 📊 Token Efficiency: Creates a compact representation optimized for LLM consumption
• 🧩 Component Identification: Identifies key components and their relationships
• 💡 Insights: Provides architectural patterns and code organization insights
• 📝 Caching: Caches results to avoid unnecessary re-processing
• 🎯 Analysis Modes: Different modes for varying analysis approaches (overview, components, architecture, flows)
• 🔎 Subdirectory Focus: Ability to analyze specific subdirectories
• 🧠 Reasoning Depth: Control over the level of detail in analysis explanations
• 📈 Visual Diagrams: Generate visual representations of codebase architecture using various formats
• 🎨 Rich Formatting: Enhanced output using rich library with improved readability
• 📁 Output Directory: Support for saving multiple output files to a specified directory
• 📊 Markdown Diagrams: Support for Mermaid and PlantUML diagrams that display directly in Markdown
• 🧭 Codebase Navigation: Navigate through the codebase using LLM for better understanding and insights

Analysis Modes

• overview: General analysis of the entire codebase structure and functionality
• components: Focus on identifying and explaining the main components and modules
• architecture: Analysis of architectural patterns and system organization
• flows: Identification of key data and control flows through the system

Diagram Formats

The --visual flag generates architecture diagrams in the format specified by --diagram-format:

• graphviz: Standard DOT format diagrams (requires Graphviz installation for PNG rendering)
• mermaid: Markdown-compatible diagrams that render in GitHub, VS Code, and other Markdown viewers
• plantuml: UML diagrams that can be rendered with PlantUML tools

Mermaid Diagrams

When using the Mermaid format, the diagram is embedded directly in the Markdown output and will render automatically on platforms that support Mermaid syntax, such as GitHub, GitLab, and VS Code with the right extensions.

Example of a Mermaid diagram in Markdown:

```mermaid
graph TD
    A[Core Module] --> B[Utils]
    A --> C[Database]
    B --> D[External APIs]
    C --> D
```

PlantUML Diagrams

PlantUML diagrams provide more advanced UML capabilities and are saved as Markdown files with PlantUML code blocks:

```plantuml
@startuml
package "Core" {
  [Component A] as A
  [Component B] as B
}
A --> B
@enduml
```

How It Works

1. Scanning: The plugin scans the directory structure and collects information about files, directories, and languages.
2. Mapping: It creates a token-efficient representation of the codebase.
3. Analysis: The map is sent to an LLM for analysis of architecture, components, and workflows.
4. Visualization: If requested, a diagram of the codebase architecture is generated in the specified format.
5. Output: Results are formatted and returned, optionally saved to a file or directory.

License

Apache License 2.0