skeletonpy 1.0.0

No project description provided

SkeletonPy

SkeletonPy is a Python utility for code analysis and summarization. It parses Python source code to generate a compact overview, which is particularly useful for reducing the context size when working with Large Language Models (LLMs). By providing a summarized version of the code, it helps improve the performance of AI-assisted coding and reduces token usage.

Motivation

SkeletonPy is designed as a fast, pure code-driven alternative to complex local indexers (like those used in Continue or Cursor) for developers who want a lightweight, zero-overhead solution. It serves as an companion for Agentic Frameworks (by providing them with a highly accurate map of your Python repository.

Why use SkeletonPy over full-context stuffing or maintaining local indexes?

• Zero Overhead Code Mapping: Code changes frequently during development. Instead of maintaining complex embeddings, local vector databases, or dealing with expensive re-indexing processes, SkeletonPy runs instantly and entirely locally without LLMs.
• Focused Context: Pumping entire repositories into the prompt window often leads to the "lost in the middle" phenomenon, where models overlook pieces of the context. A concise skeleton limits irrelevant information, which helps smaller local models and large models alike focus on what actually matters.
• Cost and Speed: Passing a compact skeleton instead of full source files means significantly fewer input tokens. This directly translates to lower API costs and faster responses.
• Perfect for Agentic Workflows: The generated summary contains original file names and precise line numbers down to class-level resolution.

Quick Start

From your project's root directory, run skeletonpy with the path to your source code (src):

uvx skeletonpy src

This will scan all Python files in the src directory and create a skeleton.txt file inside it. You can then append the content of this file to your LLM prompt.

Installation

You can install skeletonpy from PyPI using your favorite package manager like pip or uv.

pip install skeletonpy

uv pip install skeletonpy

Alternatively, you can run it directly without a permanent installation:

pipx run skeletonpy -- --help

uvx skeletonpy --help

Once installed, you can invoke the script:

skeletonpy --help

Usage

Run skeletonpy with the path to your source directory/directories. You can use include and exclude patterns to filter the files. The patterns are regular expressions.

For example, to process the src directory, including all Python files but excluding test files, and save the output to skeleton.txt:

skeletonpy src --exclude "_test\.py" -o main_src.txt

This will generate a main_src.txt file. If you provide an absolute or relative path as output, it will be respected. See the examples folder for more.