CtxGen

AI-Enhanced Documentation Generator for Code Understanding

[![Node.js](https://img.shields.io/badge/Built%20with-Node.js-339933.svg)](https://nodejs.org/) [![OpenAI](https://img.shields.io/badge/Powered%20by-OpenAI-412991.svg)](https://openai.com/) [![TypeScript](https://img.shields.io/badge/Language-TypeScript-3178C6.svg)](https://www.typescriptlang.org/) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT) [![NPM Version](https://img.shields.io/npm/v/ctx-gen.svg)](https://www.npmjs.com/package/ctx-gen)

Features • Installation • Usage • CLI Options • Output • Using with LLMs • Contributing

## Overview **Context-Gen** is a command-line tool that generates AI-enhanced documentation specifically designed to provide Large Language Models (LLMs) with comprehensive context about your codebase. Unlike traditional documentation tools, Ctx-Gen focuses on creating machine-optimized outputs that help AI models understand code structure, logic, and relationships. This enables more effective AI-driven workflows such as code review, generation, debugging, and refactoring. The generated documentation is auto-ignored by Git, ensuring it remains a development-only resource. By leveraging AI-powered analysis, Ctx-Gen extracts deep insights from your code and presents them in formats that are easily consumable by LLMs, such as markdown, JSON, and visual diagrams. > **Note**: Ctx-Gen is intended for development purposes only, to assist AI models in understanding codebases. It is not designed for producing polished, user-facing documentation.
## Features Ctx-Gen provides a robust set of features to maximize codebase comprehension for AI systems: 🔹 **AI-Powered Analysis**: Parses code structure, logic flows, and component relationships with AI-driven insights powered by GPT-4o-mini 🔹 **Intent Inference**: Infers and documents the purpose behind functions, classes, and modules 🔹 **Detailed Summaries**: Generates concise, context-rich descriptions for files, functions, classes, and modules 🔹 **Function Insights**: Documents inputs, outputs, side effects, and usage examples 🔹 **Framework Detection**: Automatically identifies frameworks and libraries used in your project 🔹 **Architecture Pattern Recognition**: Detects common architectural patterns like MVC, DDD, Clean Architecture 🔹 **Enhanced Language Support**: Supports 40+ programming languages with specialized analysis 🔹 **Advanced Visual Diagrams**: Creates call graphs, data flow diagrams, sequence diagrams, class diagrams, and dependency maps 🔹 **Multi-Language Support**: Works with TypeScript, JavaScript, Python, Java, and many more languages 🔹 **Machine-Readable Outputs**: Produces JSON and XML files alongside markdown for direct AI consumption 🔹 **Codebase Metadata**: Includes information on languages, frameworks, and architectural patterns 🔹 **Concurrent Processing**: Processes multiple files in parallel for improved performance 🔹 **Gitignore Integration**: Automatically respects .gitignore patterns when analyzing files 🔹 **Code Quality Integration**: Leverages linters and static analysis tools for additional insights 🔹 **Auto Git-Ignored**: Automatically excludes generated documentation from version control
## Installation ### Global Installation ```bash npm install -g ctx-gen # or with yarn yarn global add ctx-gen # or with pnpm pnpm add -g ctx-gen ``` ### Project-Specific Installation ```bash npm install ctx-gen --save-dev # or with yarn yarn add -D ctx-gen # or with pnpm pnpm add -D ctx-gen ``` > **Requirements**: Node.js (version 14 or higher)
## Usage Ctx-Gen provides two primary commands, with all configuration passed via command-line arguments: ### Generate Full Documentation ```bash ctx-gen full [options] ``` ### Update Existing Documentation ```bash ctx-gen update [options] ``` ### CLI Options All configuration is handled via command-line options. Below is a list of available options: | Option | Description | Default | |--------|-------------|---------| | `--docs-dir ` | Output directory for documentation | `docs` | | `--cache-file ` | Path to the cache file | `.doc_cache.json` | | `--exclude ` | Comma-separated list of paths to exclude | `.git,node_modules,dist` | | `--languages ` | Comma-separated list of languages to analyze | `typescript,javascript` | | `--diagrams ` | Comma-separated list of diagram types to generate | `call-graph,data-flow,module-deps,class-diagram` | | `--machine-formats` | Generate JSON/XML outputs for AI consumption | `false` | | `--include-examples` | Include usage examples in documentation | `false` | | `--no-ai` | Disable AI-powered features | - | | `--openai-key ` | OpenAI API key for AI features | - | | `--auto-ignore` | Auto-add `docsDir` to `.gitignore` | `true` | | `--respect-gitignore` | Respect patterns in .gitignore when analyzing files | `true` | | `--concurrent-ai ` | Maximum number of concurrent AI analyses | `3` | ### Examples ```bash # Generate full documentation with default options ctx-gen full # Update documentation with custom output directory and languages ctx-gen update --docs-dir custom_docs --languages typescript,python # Generate documentation with machine-readable formats and examples ctx-gen full --machine-formats --include-examples # Generate documentation focusing on specific diagram types ctx-gen full --diagrams class-diagram,module-deps # Generate documentation with higher concurrency for large projects ctx-gen full --concurrent-ai 8 # Disable AI features and specify excluded paths ctx-gen full --no-ai --exclude .git,node_modules,build # Ignore .gitignore patterns when analyzing files ctx-gen full --no-respect-gitignore ``` > **Note**: To enable AI features, set the `OPENAI_API_KEY` environment variable or use the `--openai-key` option.
## Output Ctx-Gen generates a structured set of documentation files in the specified `docsDir` (default: `docs/`), which is automatically excluded from Git: ``` docs/ ├── index.md # Project overview with navigation links ├── modules/ # Module and file documentation │ ├── module1.md # Details for each module │ └── module2.md ├── diagrams/ # Visual representations │ ├── call_graph.mmd # Function call relationships │ ├── data_flow.mmd # Data movement diagrams │ ├── class_diagram.mmd # Class relationships and structure │ ├── sequence.mmd # Sequence diagrams for key interactions │ └── module_deps.mmd # Module dependency graphs ├── metadata.json # Codebase metadata (languages, frameworks, etc.) ├── analysis.json # Code quality and analysis insights └── search.json # Searchable index for AI consumption ``` ### Metadata The `metadata.json` and `metadata.md` files contain rich information about your project: - Language distribution with percentage breakdown - Detected frameworks and their versions - Identified architecture patterns - Dependencies and dev dependencies ### Class Diagrams The `class_diagram.mmd` file visualizes: - Classes with their properties and methods - Inheritance relationships - Implementation relationships - Component associations
## Using with LLMs Ctx-Gen is specifically designed to provide LLMs with the context they need to understand and interact with your codebase effectively. The generated documentation serves as a rich, structured input that LLMs can use to perform a variety of tasks, including: - **Code Review**: LLMs can analyze the documentation to identify potential issues, suggest improvements, or ensure adherence to best practices. - **Code Generation**: By understanding the existing structure and logic, LLMs can generate new code that integrates seamlessly with your project. - **Debugging**: The detailed insights into function behaviors, data flows, and dependencies help LLMs pinpoint errors or suggest fixes. - **Refactoring**: LLMs can use the documentation to propose refactoring strategies that improve code quality without breaking functionality. ### How It Works 1. **Generate Documentation**: Run `ctx-gen full` to create a comprehensive set of documentation files, including markdown, JSON, and diagrams. 2. **Feed to LLM**: Provide the generated files (e.g., `metadata.json`, `search.json`, or specific module documentation) as input to your LLM of choice. 3. **Query the LLM**: Ask the LLM to perform tasks like reviewing a specific function, suggesting improvements, or generating new code based on the provided context. ### Example Use Case Suppose you want an LLM to review the `processData` function for potential optimizations: 1. Run `ctx-gen full --include-examples` to generate documentation with examples. 2. Provide the LLM with the `modules/utils/data.md` file, which contains the detailed documentation for `processData`. 3. Ask the LLM: "Review the `processData` function and suggest any optimizations or improvements." The LLM can then analyze the function's intent, inputs, outputs, and usage examples to provide meaningful feedback.
## Contributing Contributions are welcome! Please see our [Contribution Guidelines](CONTRIBUTING.md) for more details. ### Development Setup 1. Clone the repository 2. Install dependencies with `pnpm install` 3. Build the project with `pnpm build` 4. Run tests with `pnpm test` ### Report Issues Please report bugs and suggest features via the [GitHub Issues](https://github.com/maxmcneal/ctx-gen/issues) page.

© 2025 Max McNeal • Built for AI-assisted development