AI Context Manager 🤖

A lightweight, zero-dependency CLI tool that automatically analyzes your codebase and generates a comprehensive project-context.md file. Paste this markdown file at the start of any conversation with AI assistants (Cursor, Copilot, Claude, ChatGPT, Windsurf) to instantly give them full structural, architectural, and technical understanding of your project.

🚀 Why Use This?

AI assistants lose context in large or multi-layered codebases. Instead of repeatedly explaining:

• “What is our tech stack?”
• “Where are the API routes defined?”
• “What coding conventions or file naming patterns do we follow?”
• “How do our database models look?”

You simply run:

npx @gueddari/ai-context-manager generate

And copy/paste: "Read project-context.md first" to your AI assistant.

🛠️ Features

• 📁 Project Structure: Scans directory structure while automatically respecting .gitignore rules. Summarizes large directories to keep the context clean.
• 🏗️ Architecture Detector: Infers the architectural pattern (Next.js App Router, MVC, Feature-Based, Layered, Monorepo, API Service, or Custom/Flat) and documents key directories.
• 🛠️ Tech Stack Scanner: Detects languages, runtimes, frameworks, libraries, database ORMs, styling configurations, bundlers, and testing tools from package.json and config files.
• 📡 API Router Finder: Automatically scans files (ignoring comments) to map REST & GraphQL endpoints for Express, Fastify, Hono, NestJS, FastAPI, and Next.js App Router.
• 🗃️ Database Schema Parser: Parses and extracts models/schemas for Prisma, Mongoose, TypeORM, and Drizzle.
• 📏 Convention Inspector: Analyzes file naming (kebab-case, camelCase, PascalCase, snake_case), export styles (default vs. named), semicolons, quotes, indentation, import styles, and TypeScript configurations.
• 📌 Important Files: Highlights entry points, config files, environments, CI/CD pipelines, Docker configurations, and documentation.

📦 Installation & Usage

No installation is required to use the CLI:

npx @gueddari/ai-context-manager generate

Options

Options:
  -V, --version            output the version number
  -o, --output <filename>  Output filename (default: "project-context.md")
  -d, --dir <directory>    Project root directory to analyze (default: ".")
  --no-banner              Suppress the banner
  -h, --help               display help for command

For example, to analyze a subdirectory and output to a custom file:

npx @gueddari/ai-context-manager generate --dir ./packages/backend --output backend-context.md

💻 Programmatic API

You can also import and use the analyzer in your Node/TypeScript scripts:

import { analyzeProject } from '@gueddari/ai-context-manager';

const result = analyzeProject('./path/to/project');
console.log('Project Name:', result.projectName);
console.log('Detected Tech Stack:', result.techStack.items);

🤝 Development & Contribution

Setup

1. Clone the repository and install dependencies:

   npm install

2. Build the TypeScript package:

   npm run build

3. Link the package globally for local testing:

   npm link

4. Run the CLI locally:

   ai-context generate

📄 License

MIT © Wassim Gueddari