ContextForge

Persistent AI memory for your repository. ContextForge runs in the background, scans your codebase, and generates a live context.md so every AI session starts fully informed—no re-explaining your stack, architecture, or constraints.

Works with ChatGPT, Claude, Cursor, and GitHub Copilot.

How to run locally

See HOW_TO_RUN.md for every command, expected output, and a full copy-paste test script.

Install

npm install -D contextforge

After npm install, everything runs automatically — users do not run init, generate, or watch manually:

1. Creates .env from .env.example (if missing)
2. Creates .contextforge/ + context.md + Cursor rule
3. Starts background watch --daemon (updates on save + timer)

npm install -D contextforge   # that is all

Logs: .contextforge/logs/postinstall.log · Stop watcher: npx contextforge stop

Disable auto-run:

"contextforge": { "postinstall": false }

Or in .contextforge/config.json: "postinstallWatch": false, "postinstallGenerate": false
Or env: CONTEXTFORGE_SKIP_POSTINSTALL=1

Quick start

Manual commands (optional if you used npm install):

npx contextforge init          # full setup + tips
npx contextforge generate      # regenerate on demand
npx contextforge watch         # foreground watcher

Output is written to .contextforge/:

.contextforge/
├── config.json
├── context.md          ← paste into AI tools / Cursor rules
├── CHANGES.md          ← what changed between runs
├── context.json
├── architecture.json
├── git-insights.json
├── bugs-report.json
├── cache/
└── logs/

CLI commands

| Command | Description | |---------|-------------| | init | Create .contextforge/, config, and initial context | | generate | Scan repo and regenerate all artifacts | | watch | Watch files + optional timer; updates on code changes | | changes | Show file/code change history between runs | | stop | Stop daemon watcher (watch --daemon) | | doctor | Health check (Node, keys, timer, context.md) | | summary | Short stdout summary | | prompt | Export full or partial context for AI prompts |

Options

npx contextforge generate --cwd /path/to/project
npx contextforge watch --verbose
npx contextforge watch --interval 15   # override .env timer (minutes)
npx contextforge prompt --sections stack,arch,git
npx contextforge watch --daemon   # for use with stop
npx contextforge changes --limit 20

Detailed context.md (strong AI memory)

Each run builds a long, structured markdown file with:

| Section | What you get | |---------|----------------| | At a Glance | One-table summary for ChatGPT/Cursor | | Tech Stack (Detailed) | Category table + detection signals | | Project Statistics | Routes, services, components, AST counts | | npm Scripts | All package.json scripts | | Entry Points | main, bin, server/index.js, etc. | | Environment Variables | Names from .env.example (never values) | | API Flow | Up to 30 routes with method/path/file | | Middleware / UI Components | When detected | | AI-Enhanced Analysis | Optional OpenAI/Groq narrative (init --ai) |

Regenerate after stack changes: npx contextforge generate --ai

Auto-update on file/code changes

ContextForge hashes every scanned file. When you edit and save code, watch or generate detects it and updates context.md:

• New, modified, and removed files are tracked
• Terminal: File/code changes detected — context updated (~N modified)
• History: npx contextforge changes or .contextforge/CHANGES.md

Timer in .env (recommended)

# Regenerate every 15 minutes while watch is running (0 = file saves only)
CONTEXTFORGE_REFRESH_INTERVAL_MINUTES=15

npx contextforge watch

On each timer tick, ContextForge only regenerates if files actually changed (no wasted runs).

Other env vars: CONTEXTFORGE_REFRESH_INTERVAL_SECONDS, CONTEXTFORGE_DEBOUNCE_MS

Cursor integration

Add a project rule:

Read .contextforge/context.md at the start of each session before answering questions about this codebase.

Or run npx contextforge prompt and paste the output into your chat.

AI enrichment (OpenAI + Groq)

Use OpenAI or Groq to generate a detailed AI-Enhanced Analysis section in context.md.

Setup

# Windows
copy .env.example .env

# macOS / Linux
cp .env.example .env

Edit .env and set your keys:

OPENAI_API_KEY=sk-...
GROQ_API_KEY=gsk_...
CONTEXTFORGE_AI_PROVIDER=openai

Then:

npx contextforge init --ai

Config (ai in .contextforge/config.json)

See .contextforge/config.ai.example.json for a full template:

| Field | Description | |-------|-------------| | ai.enabled | Turn AI on/off | | ai.provider | openai or groq | | ai.fallbackProvider | Backup if primary fails | | ai.background | true = fast scan first, AI updates context.md when ready | | ai.openai.model | gpt-4o-mini, gpt-4o, etc. | | ai.groq.model | llama-3.3-70b-versatile, mixtral-8x7b-32768 | | ai.promptsDir | Folder for editable prompts (default .contextforge/prompts) |

Customize AI prompts

Edit files in .contextforge/prompts/ after init — see prompts/README.md in the package.

npx contextforge generate --ai
npx contextforge generate --no-ai

Configuration

.contextforge/config.json:

Copy .contextforge/config.example.json or see:

{
  "ignore": ["node_modules", "dist", ".next"],
  "watch": true,
  "autoGenerate": true,
  "includeGitHistory": true,
  "detectBugs": true,
  "debounceMs": 2000,
  "refreshIntervalMinutes": 0,
  "trackChanges": true,
  "ai": {
    "enabled": false,
    "provider": "openai",
    "fallbackProvider": "groq",
    "background": true
  }
}

Priority: .env overrides config.json for timer, debounce, and AI provider. Run npx contextforge init --force to merge new fields into an existing project.

Programmatic API

import { runPipeline, loadConfig } from 'contextforge';

await runPipeline('/path/to/project', { verbose: true });

Security

• Static scan runs 100% locally
• AI calls send only aggregated scan metadata (never .env or source file contents)
• API keys stay in your .env (gitignored)
• Respects ignore patterns in config

Development

npm install
npm test
node bin/contextforge.js init --cwd .

Publish to npm

See PUBLISHING.md for the full guide:

1. npm login
2. npm test
3. npm pack (inspect tarball)
4. npm publish --access public

Quick publish:

npm test
npm publish --access public

License

MIT