AI Context Generator CLI

A CLI tool that generates comprehensive context files for AI coding assistants by analyzing project structure, dependencies, and coding patterns. Outputs structured JSON/YAML context files optimized for different AI tools.

Features

• Automatic Project Detection: Detects project type (Node.js, Python, Go, Rust, Java, etc.) and frameworks (React, Django, FastAPI, etc.)
• Dependency Analysis: Extracts dependencies from package.json, requirements.txt, go.mod, Cargo.toml, and more
• Convention Extraction: Analyzes coding patterns, naming conventions, import styles, and testing frameworks
• Multi-format Output: Generates context files in JSON or YAML format
• AI-specific Templates: Predefined templates for Cursor, Copilot, and generic AI assistants
• Configurable: Customize analysis scope and output via .ai-context-config.json
• Ignore Pattern Support: Respects .gitignore and custom ignore rules

Installation

Prerequisites

• Node.js 16+
• npm or yarn

Install from Source

git clone https://github.com/yourusername/ai-context-generator-cli.git
cd ai-context-generator-cli
npm install
npm run build
npm link

Install Globally

npm install -g ai-context-generator-cli

Usage

Basic Usage

# Analyze current directory and generate context
ai-context

# Analyze specific directory
ai-context --dir /path/to/project

# Save to specific output file
ai-context --output my-context

# Generate YAML instead of JSON
ai-context --format yaml

Command Options

Option	Short	Description	Default
--dir	-d	Project directory to analyze	Current directory
--output	-o	Output file path	ai-context
--format	-f	Output format: json or yaml	json
--template	-t	Template: default, cursor, copilot, generic	default
--config	-c	Config file path	Auto-detected
--verbose	-v	Enable verbose output	false
--no-conventions		Skip convention analysis	false
--include-dev		Include dev dependencies	false
--no-gitignore		Do not respect .gitignore	false

Examples

# Generate context with all analysis
ai-context --dir ./my-project --verbose

# Generate YAML output for documentation
ai-context --format yaml --output project-context

# Use Cursor-optimized template
ai-context --template cursor --output cursor-context

# Quick analysis without conventions
ai-context --no-conventions

# Include development dependencies
ai-context --include-dev

Configuration

Create a .ai-context-config.json file in your project root:

{
  "includes": [
    "**/*.ts",
    "**/*.js",
    "**/*.py",
    "**/*.go",
    "**/*.rs"
  ],
  "excludes": [
    "node_modules/**",
    "dist/**",
    ".git/**"
  ],
  "outputFormat": "json",
  "template": "default",
  "outputFile": "ai-context.json",
  "analyzeConventions": true,
  "includeDevDependencies": false,
  "respectGitignore": true
}

Configuration Options

Option	Type	Description	Default
includes	string[]	File patterns to include	All common source files
excludes	string[]	File patterns to exclude	Common ignore patterns
outputFormat	`json	yaml`	Output format
template	string	Template name	default
outputFile	string	Output filename	ai-context.json
analyzeConventions	boolean	Extract coding conventions	true
includeDevDependencies	boolean	Include dev dependencies	false
respectGitignore	boolean	Respect .gitignore	true

Templates

Default Template

Generates structured JSON/YAML with full project analysis.

Cursor Template

Optimized for Cursor AI, focusing on:

• Key dependencies
• Coding conventions
• File structure overview

Copilot Template

Tailored for GitHub Copilot, featuring:

• Concise project summary
• Dependency overview
• Style guidelines

Generic Template

Simple format suitable for any AI assistant:

• Project information
• Dependency list
• Conventions summary

Output Structure

JSON Output

{
  "projectInfo": {
    "projectType": {
      "primaryLanguage": "TypeScript",
      "languages": ["TypeScript", "JavaScript"],
      "frameworks": ["React", "Next.js"],
      "buildTools": ["npm"]
    },
    "dependencies": {
      "direct": [...],
      "dev": [...],
      "total": 50
    },
    "conventions": {
      "namingConvention": {
        "files": "kebab-case",
        "variables": "camelCase",
        "functions": "camelCase",
        "classes": "PascalCase"
      },
      "importStyle": {
        "style": "ESM",
        "aliasPrefix": "@/"
      },
      "testingFramework": "Jest",
      "codeStyle": {
        "indentSize": 2,
        "indentType": "spaces",
        "lineEndings": "LF",
        "quoteStyle": "single"
      }
    },
    "fileCount": 150,
    "analysisDate": "2024-01-15T10:30:00.000Z"
  },
  "files": [...],
  "config": {...},
  "generatedAt": "2024-01-15T10:30:00.000Z"
}

Supported Languages

Language	Detected By	Dependency Files
TypeScript	.ts, .tsx, tsconfig.json	package.json
JavaScript	.js, .jsx, package.json	package.json
Python	.py, requirements.txt	requirements.txt, pyproject.toml, Pipfile
Go	.go, go.mod	go.mod
Rust	.rs, Cargo.toml	Cargo.toml
Java	.java, pom.xml	pom.xml, build.gradle
C/C++	.c, .cpp, CMakeLists.txt	CMakeLists.txt
Ruby	.rb, Gemfile	Gemfile
PHP	.php, composer.json	composer.json

Supported Frameworks

• Frontend: React, Vue, Next.js, NestJS
• Backend: Express, Django, FastAPI, Flask, Gin, Echo
• Testing: Jest, Mocha, Pytest, Go testing, JUnit

Programmatic Usage

import { ContextGenerator } from 'ai-context-generator-cli';

const generator = new ContextGenerator();

// Generate context
const projectInfo = await generator.generate('/path/to/project');

// Generate JSON output
const jsonOutput = await generator.generateJson('/path/to/project');

// Generate YAML output
const yamlOutput = await generator.generateYaml('/path/to/project');

// Save to file
await generator.saveContext('/path/to/project', 'output', 'json');

Error Handling

Common Errors

Error	Solution
No package.json found	Check if running in project root or use --dir flag
Invalid config file format	Validate JSON syntax and required fields
Permission denied on output file	Check write permissions in target directory
Directory not found	Verify the directory path exists

Development

# Install dependencies
npm install

# Run tests
npm test

# Build
npm run build

# Run locally
npm run dev -- --dir ./my-project

# Lint
npm run lint

# Lint with fix
npm run lint:fix

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT License - see LICENSE for details.