AI-ContextGen

AI-ContextGen is a Node.js CLI utility that generates comprehensive Markdown snapshots of your entire project structure, perfect for providing complete context to AI assistants (ChatGPT, Claude, etc.) while respecting .gitignore and .ai-ignore rules and filtering out binary files.

The tool is published on npm. Install it globally or run via npx to quickly generate project snapshots.

✨ Features

• 📁 Complete Project Snapshot - Captures all text files in a structured markdown format
• 🚫 Smart Filtering - Automatically respects .gitignore and .ai-ignore and skips binary/oversized files
• 📝 AI-Ready Format - Generates clean markdown with syntax highlighting for each file
• ⚡ Git Integration - Works seamlessly with Git repositories
• 🔧 Configurable - Command-line options for input/output customization
• 📦 Restore Snapshot - Recreate files from a generated markdown

🚀 Quick Start

Using npx (Recommended)

npx @xblaster/ai-contextgen

With Custom Options

npx @xblaster/ai-contextgen --input ./my-project --output project-context.md

Restore From Snapshot

npx @xblaster/ai-contextgen restore project-context.md --output ./restored

💻 Installation & Usage

Global Installation

npm install -g @xblaster/ai-contextgen
ai-contextgen --input . --output snapshot.md

Local Development

git clone <your-repo-url>
cd ai-contextgen
npm install
node ai-contextgen.js --input . --output snapshot.md

📋 Command Line Options

ai-contextgen snapshot [options]
ai-contextgen restore <markdown> [--output <folder>]

Options:

• --input, -i : Source directory to scan (default: current directory)
• --output, -o : Output file or target directory (default: __aicontextgen.md)
• --help, -h : Show help information

📄 Generated Output Format

The tool creates a structured markdown file like this:

# AI-ContextGen Snapshot

> Generated by AI-ContextGen. Below is the full project context.

---

## `package.json`

```json
{
  "name": "my-project",
  "version": "1.0.0"
}

Each snapshot ends with a Global checksum: line containing a SHA-256 hash computed from all included files. The restore process verifies this checksum to ensure every file was recreated correctly.

What Gets Included

• ✅ All text-based source files
• ✅ Configuration files (package.json, .env.example, etc.)
• ✅ Documentation files
• ✅ Scripts and configuration

What Gets Excluded

• ❌ Binary files (images, executables, etc.)
• ❌ Files listed in .gitignore or .ai-ignore
• ❌ Large files (configurable threshold)
• ❌ Git internal files (unless explicitly needed)

🎯 Use Cases

Perfect for AI Assistance:

• Get complete project context for code reviews
• Share entire codebase with AI for debugging
• Generate documentation with full project understanding
• Onboard new team members with complete project snapshots

Development Workflows:

• Create project backups in readable format
• Generate documentation snapshots
• Share project structure for code analysis
• Create context for remote code reviews

🔧 Technical Details

• Language: Node.js / JavaScript
• File Detection: Automatic binary file detection
• Git Integration: Respects .gitignore and .ai-ignore patterns
• Output Format: Clean markdown with syntax highlighting
• Performance: Efficient file processing with progress indicators

🧪 Running Tests

1. Install dependencies if not already done:

   npm install

2. Run the test suite with:

   npm test

Unit tests are executed automatically via GitHub Actions using the included .github/workflows/ci.yml workflow.

📝 License

MIT License - see LICENSE file for details