⚡ ContextForge

Automatic AI memory generation for repositories.

Run one command → automatically generate reusable AI-ready project context.

What It Does

ContextForge scans your repository, analyzes its architecture and stack, and generates a context.md file that you can paste into any AI assistant (ChatGPT, Claude, Gemini, Cursor, etc.) to give it deep, accurate knowledge of your codebase — instantly.

No backend. No cloud. No magic. Just fast, local analysis.

Installation

npm install -g contextforge

Usage

1. Add your OpenAI API key

Create a .env file in your project root (the repo you want to analyze):

OPENAI_API_KEY=sk-your-api-key-here

2. Run ContextForge

contextforge init

That's it. ContextForge will:

1. 🔍 Scan your repository (using fast-glob + .gitignore rules)
2. 🧠 Analyze your architecture, stack, patterns, and auth
3. 📁 Identify important files with heuristic scoring
4. ✨ Generate AI-ready context using GPT-4o-mini
5. 📝 Write context.md to your project root

CLI Options

contextforge init [options]

Options:
  -o, --output <path>   Output file path (default: "context.md")
  --model <model>       OpenAI model to use (default: "gpt-4o-mini")
  --no-ai               Skip OpenAI, generate structural context only
  -v, --version         Output the current version
  -h, --help            Display help

Examples

# Standard usage
contextforge init

# Use a more powerful model
contextforge init --model gpt-4o

# Offline / no API key — structural context only
contextforge init --no-ai

# Custom output path
contextforge init --output docs/ai-context.md

Output Format

# Project Context

> Express.js REST API with Prisma ORM and JWT authentication.

## Stack
- Express.js
- Node.js
- Prisma ORM
- JWT (jsonwebtoken)
- Zod

## Architecture
- Route-based API structure
- MVC / Controller pattern
- Service layer pattern
- Middleware-based request handling

## Important Modules
### `src/`
- `src/app.js`
- `src/routes/`
- `src/controllers/`
- `src/services/`
- `src/middleware/auth.js`

## Coding Patterns
- async/await pattern
- ES Modules (import/export)
- try/catch error handling
- Schema validation (Zod)

## AI Instructions
- This is a JavaScript project using ES Modules
- Backend: Express.js — follow route/controller/service layering
- Database: Prisma ORM — use existing query patterns
- Auth: JWT — never bypass the auth middleware
- Validate all inputs with Zod schemas
- Use async/await for all async operations

How File Importance Is Scored

ContextForge uses lightweight heuristic scoring — no embeddings, no vectors:

| Signal | Score | |---|---| | Filename matches known important files | +10 | | Directory matches (auth, routes, services, etc.) | +7 | | Filename contains keywords (auth, route, controller...) | +5 | | Content patterns (router.get, prisma., jwt.sign...) | +2 each | | File extension (JS/TS > JSON/YAML > MD) | +1–3 |

Architecture Detection

ContextForge detects:

• Frameworks: Express, Fastify, NestJS, Next.js, React, Vue, Svelte, Astro, Remix...
• Databases: Prisma, Mongoose, TypeORM, Drizzle, Sequelize, PostgreSQL, MySQL, Redis...
• Auth: JWT, Passport.js, NextAuth, Clerk, Supabase, Firebase, bcrypt...
• State: Zustand, Jotai, Redux Toolkit, TanStack Query, SWR...
• Validation: Zod, Joi, Yup, class-validator...
• Testing: Jest, Vitest, Playwright, Cypress...
• Patterns: Service layer, Repository, MVC, Middleware, RBAC, File-system routing...

Privacy

Everything runs locally on your machine. Your code is only sent to OpenAI when AI generation is enabled (the default). Use --no-ai to keep everything fully local.

Requirements

• Node.js ≥ 18
• OpenAI API key (optional with --no-ai)

License

MIT