The hierarchical-context-compressor is a Command-Line Interface (CLI) tool designed to generate AI-optimized hierarchical context maps for any codebase. This project can be executed locally or integrated into CI workflows using GitHub Actions. It efficiently processes the structure of a codebase to create operational manuals that facilitate better understanding and usage of the code.

Key Features

• Comprehensive Documentation: Generates a root agents.md file, which acts as a table of contents, supplemented by per-directory AGENTS.md operational manuals. For web applications, additional file llms.txt is created at the root level.
• Three-Phase Generation Flow: The tool operates in three phases:
  1. An AI model selects directories for the creation of AGENTS.md.
  2. A discovery step identifies which files to analyze within those directories.
  3. The generation phase produces the concise content for the AGENTS.md files, providing overviews and operational guidance.

Usage

To utilize hcc on any repository:

1. Install the tool from Git:

   uv tool install git+https://github.com/reyavir/hierarchical-context-compressor.git
   

2. Set the OPENAI_API_KEY in your environment.
3. Execute the tool on a specified codebase:

   hcc --root /path/to/your/repo
   

   This command generates the required documentation.
4. Optionally, preview changes without writing output files:

   hcc --root /path/to/your/repo --dry-run
   

Customization

Support for custom prompts per folder type allows adjusting templates for different contexts, enhancing the specificity of generated content.

CLI Options

The tool includes several configurable options to customize the analysis and generation process, such as specifying the repository root and selecting different AI models for discovery and generation.

Integration with GitHub Actions

hierarchical-context-compressor can be seamlessly integrated into a CI pipeline. A configuration file can be created within .github/workflows/ to automate the process of running the tool and committing changes to documentation as the codebase evolves. The required environment secret, OPENAI_API_KEY, must be added to the repository settings.

Development

For those interested in contributing to the hierarchical-context-compressor codebase, the source code can be cloned and developed locally. The CLI can be executed directly from the local copy, enabling testing and modification of its functionality.