AST blueprint generator for better AI understanding

I Built Crespo: Turning Repositories into AI-Ready Codebase Blueprints

Over the last few months, I've been using AI coding assistants extensively for learning, debugging, and understanding unfamiliar codebases.

One problem kept showing up:

Before an AI can help effectively, it needs context about the project.

For small projects, this isn't a big issue. But for larger repositories, I often found myself spending multiple prompts explaining project structure, key modules, dependencies, and architecture.

So I started building Crespo.

What is Crespo?

Crespo is a Python CLI that analyzes a repository and generates a compact XML blueprint containing:

• Project structure


• Files and folders


• Classes


• Functions


• Imports and dependencies


• Optional AI-generated summaries

The goal is to provide AI tools with a high-level understanding of a codebase without requiring the entire repository to be pasted into the context window.

Installation

pip install crespo

Usage

crespo .

This generates a structured representation of the repository.

Example:

<file path="src/auth.py">

  <class name="AuthService">

    <function name="login"/>

    <function name="logout"/>

  </class>

</file>

Why Build This?

While experimenting with ChatGPT, Claude, Gemini, and other coding assistants, I noticed that much of the conversation was spent describing the repository itself.

I wanted a reusable blueprint that could act as a map of the project.

Instead of saying:

Here are 50 files. Please understand this codebase.

I wanted something closer to:

Here is the structure, architecture, and relationships. Now let's discuss implementation.

Technical Details

Crespo uses Tree-sitter to analyze source code and extract structural information from repositories.

The project currently supports generating repository maps and structured XML outputs that can be shared with AI assistants.

Lessons Learned

Building Crespo taught me a lot about:

• Python packaging


• PyPI publishing


• Tree-sitter integration


• CLI development


• Open-source maintenance

As a student developer, one of the most rewarding experiences has been seeing people I don't know install and use something I built.

Feedback Welcome

I'm still actively improving Crespo and would love feedback from developers who work with AI-assisted coding workflows.

What information would you want included in an AI-ready codebase blueprint?

GitHub: