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

npm install -g ctx-gen
# or with yarn
yarn global add ctx-gen
# or with pnpm
pnpm add -g ctx-gen

Project-Specific Installation

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

ctx-gen full [options]

Update Existing Documentation

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 <path> | Output directory for documentation | docs | | --cache-file <path> | Path to the cache file | .doc_cache.json | | --exclude <paths> | Comma-separated list of paths to exclude | .git,node_modules,dist | | --languages <langs> | Comma-separated list of languages to analyze | typescript,javascript | | --diagrams <types> | 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 <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 <number> | Maximum number of concurrent AI analyses | 3 |

Examples

# 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 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 page.