SourceSage

～Transforming code for AI～

[🌐 Website] • [🐱 GitHub] [🐦 Twitter] • [🍀 Official Blog]

日本語 | English

SourceSage is a tool that comprehensively analyzes repository structure and content to generate AI-friendly documentation. It primarily provides Repository_summary.md generation and RELEASE_REPORT creation features.

[!IMPORTANT] Nearly 90% of the release notes, README, and commit messages in this repository are generated using AIRA, SourceSage, Gaiah, and HarmonAI_II with claude.ai and ChatGPT4.

🌟 Related Projects

SourceSage MCP Server

SourceSage MCP Server is a derived version of SourceSage that integrates with the Model Context Protocol (MCP). It enables AI assistants like Claude Desktop to directly access repository analysis capabilities.

Release Notes

For the latest updates, please visit our GitHub releases page.

https://github.com/Sunwood-ai-labs/SourceSage/releases

🎯 Key Features

SourceSage is a simple and lightweight repository analysis tool that provides two main features:

1. 📋 Repository Summary Generation

Comprehensively analyzes repository structure, commit information, and file statistics to generate AI-friendly markdown documentation.

Output File: .SourceSageAssets/Repository_summary.md

Included Information:

• 🌳 Project tree structure
• 📋 Git repository information
• 📈 File size and line count statistics
• 📝 Detailed file contents

2. 📄 Release Report Generation (Optional Feature - Deprecated)

⚠️ Deprecated Feature: This feature will be removed in a future release. With improvements in LLM command execution capabilities, automatic diff report generation is becoming unnecessary.

Analyzes differences between Git tags to automatically generate release reports (enabled with --diff flag).

Output File: .SourceSageAssets/RELEASE_REPORT/Report_{latest_tag}.md

Included Information:

• 🏷️ Version comparison
• 🔄 Detailed change differences
• 📋 Commit history
  • 📂 Repository basic information (remote URL, branch, latest commit, etc.)
  • 📖 README content (optional)

🚀 Quick Start

📦 Installation (Fastest)

git clone https://github.com/Sunwood-ai-labs/SourceSage.git
cd SourceSage
uv sync
uv run sage

Note: When using as a package, run pip install sourcesage then execute sage (or sourcesage).

🗺️ Basic Usage (Minimum Required)

# Generate repository summary (default: uses .gitignore)
uv run sage

# Use/generate .SourceSageignore file
uv run sage --use-ignore

# Generate release report (optional - deprecated)
uv run sage --diff

Output locations:

• Repository Summary: .SourceSageAssets/Repository_summary.md
• Release Report: .SourceSageAssets/RELEASE_REPORT/Report_{latest_tag}.md (only with --diff)

Frequently used options (excerpt):

uv run sage -o ./out                     # Change output destination
uv run sage --ignore-file .gitignore     # Specify ignore rules (default)
uv run sage --use-ignore                 # Use/generate .SourceSageignore
uv run sage --diff                       # Generate diff report (deprecated)

Notes:

• From v7.2.0, .gitignore is used by default. Use --use-ignore if you need a custom ignore file.
• When --language-map is omitted, the included defaults (sourcesage/config/) are automatically used.
• Release Report is generated when there are 2 or more tags (only with --diff).

🔄 Upgrade

# If installed via PyPI
pip install --upgrade sourcesage

# If installed via git clone
git pull origin main

# If using uv with local clone
uv sync

🔍 Troubleshooting

uvx cache issues

If uvx sourcesage is using an outdated version, clear the cache:

# Force refresh (recommended)
uvx --refresh sourcesage --repo tmp

# Clear all uv cache
uv cache clean

# Clear specific package cache
uv cache clean sourcesage

# Run without cache
uvx --no-cache sourcesage --repo tmp

Cache management

# Check cache size
uv cache size

# Show cache directory
uv cache dir

# Prune unused cache
uv cache prune

📊 Example Generated Content

Repository Summary

    # Project: SourceSage

    ```plaintext
    OS: posix
    Directory: /path/to/project

    ├── .SourceSageignore
    ├── pyproject.toml
    ├── sourcesage/
    │   ├── __init__.py
    │   ├── cli.py
    │   └── modules/
    │       ├── DocuSum/
    │       └── DiffReport/
    │           ├── __init__.py
    │           ├── git_diff.py
    │           └── markdown_report.py
    └── README.md
    ```

    ## 📊 Project Statistics

    - 📅 Created: 2025-02-02 16:22:31
    - 📁 Total directories: 5
    - 📄 Total files: 15
    - 📏 Max depth: 3

    ### 📊 File Size and Line Count

    | File | Size | Lines | Language |
    |------|------|-------|----------|
    | pyproject.toml | 1.2 KB | 30 | TOML |
    | **Total** |  | **1234** |  |

    ### 📈 Language Statistics

    | Language | Files | Total Lines | Total Size |
    |----------|-------|-------------|-----------|
    | Python | 15 | 1234 | 45.6 KB |
    | Markdown | 3 | 150 | 5.2 KB |

🛠️ Development Environment

SourceSage supports modern Python development environments:

• Python: 3.8 or later
• Package Management: uv / pip
• Build System: hatchling
• Configuration File: pyproject.toml

Development Setup

# Development environment setup using uv
git clone https://github.com/Sunwood-ai-labs/SourceSage.git
cd SourceSage
uv sync

# Run tests
uv run pytest

# Code formatting
uv run black sourcesage/
uv run isort sourcesage/

# Build package
uv build

💡 Usage Examples

# 1) Output repository summary (default: uses .gitignore)
uv run sage

# 2) Output summary using .SourceSageignore
uv run sage --use-ignore

# 3) Generate diff report (deprecated feature)
uv run sage --diff

# 4) Change output destination
uv run sage -o ./analysis

Contributing

Help us improve SourceSage! If you have bug reports or feature suggestions, please open an issue or submit a pull request at our GitHub repository.

License

This project is released under the MIT License.

Official Links & Verification (SSAGE)

• Orynth project: https://www.orynth.dev/projects/sourcesage
• GitHub repo: https://github.com/Sunwood-ai-labs/SourceSage

SSAGE (Solana mint): 1QaAfN81sYjenLGeiPa9NW1s6FND4A36R3ASKKxVory

Primary pool (SSAGE/USDC, Meteora): https://www.geckoterminal.com/solana/pools/A4oHVtJxGRRYvqfRuUGPwfxFVdBmPJnYZtcqew5Y8HoH

Dexscreener: https://dexscreener.com/solana/a4ohvtjxgrryvqfruugpwfxfvdbmpjnyztcqew5y8hoh

Note: SSAGE is a community market token/identifier for the SourceSage project on Orynth. It is not equity, ownership, or a claim on the project. No investment advice.