ContextForge

Persistent AI memory for your repository. Install once with npm install — ContextForge scans your codebase in the background and keeps .contextforge/context.md (and a Cursor rule) up to date for ChatGPT, Claude, and Cursor.

Install (npm — works like local)

In any Node.js 18+ project:

npm install -D contextforge-cli-ai-prompt-pirates

That is the only required step. On install, ContextForge automatically:

1. Creates .env from .env.example (if you do not have one)
2. Creates .contextforge/ and generates context.md
3. Writes .cursor/rules/contextforge.mdc for Cursor
4. Starts a background watcher (watch --daemon) for file saves + optional timer

You should see:

[contextforge] npm install → auto setup starting in background

Verify after ~10–30 seconds:

npx contextforge-cli-ai-prompt-pirates doctor
# or
npx cfpirates doctor

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

Optional: AI enrichment

Edit .env in your project (created on first install):

OPENAI_API_KEY=sk-...
GROQ_API_KEY=gsk_...
CONTEXTFORGE_AI_PROVIDER=openai
CONTEXTFORGE_AI_ENABLED=true
CONTEXTFORGE_REFRESH_INTERVAL_MINUTES=15

Regenerate with AI: npx cfpirates generate

Disable auto-start on install

CONTEXTFORGE_AUTO_START=false

Or:

"contextforge": { "postinstall": false }

Or: CONTEXTFORGE_SKIP_POSTINSTALL=1

Important: npm install flags

| Command | Auto-setup | |---------|------------| | npm install | Yes | | npm install --ignore-scripts | No (npm skips postinstall) | | npm ci | Yes (unless ignore-scripts) |

Local development (this repo)

git clone <your-repo>
cd contextforge-cli-ai-prompt-pirates   # your repo folder name may differ
npm install
npm test
npx cfpirates doctor

Uses the same postinstall hook as published users.

Manual commands (optional)

npx cfpirates init          # full setup + tips
npx cfpirates generate      # regenerate on demand
npx cfpirates watch         # foreground watcher
npx cfpirates changes       # change history
npx cfpirates prompt        # export context for AI chat

Output layout

.contextforge/
├── config.json
├── context.md          ← full project memory for AI
├── CHANGES.md
├── context.json
├── architecture.json
├── git-insights.json
├── bugs-report.json
├── cache/
└── logs/
.cursor/rules/
└── contextforge.mdc    ← Cursor auto-rule (synced on generate)

CLI commands

| Command | Description | |---------|-------------| | init | Create .contextforge/, config, first context | | generate | Scan repo and regenerate artifacts | | watch | Watch files + optional timer refresh | | changes | Show change history between runs | | stop | Stop background watcher (watch --daemon) | | doctor | Health check | | summary | Short stdout summary | | prompt | Export context block for AI prompts |

npx cfpirates generate --cwd /path/to/project
npx cfpirates watch --verbose
npx cfpirates watch --interval 15
npx cfpirates generate --ai
npx cfpirates generate --no-ai

Environment variables (.env)

| Variable | Default | Purpose | |----------|---------|---------| | CONTEXTFORGE_AUTO_START | true | Auto setup on npm install | | CONTEXTFORGE_POSTINSTALL_GENERATE | true | Create context.md on install | | CONTEXTFORGE_POSTINSTALL_WATCH | true | Start background watch on install | | CONTEXTFORGE_SKIP_POSTINSTALL | — | Set 1 to disable all install automation | | CONTEXTFORGE_AI_ENABLED | — | true / false overrides config | | CONTEXTFORGE_AI_PROVIDER | openai | openai or groq | | CONTEXTFORGE_REFRESH_INTERVAL_MINUTES | 0 | Timer while watch runs (0 = file saves only) | | OPENAI_API_KEY / GROQ_API_KEY | — | AI enrichment |

Copy from .env.example in your project after install.

Cursor integration

ContextForge syncs one rule file: .cursor/rules/contextforge.mdc (includes stack summary + link to full context.md).

Or add manually:

Read .contextforge/context.md before coding in this repository.

Configuration

.contextforge/config.json (created automatically):

{
  "watch": true,
  "autoGenerate": true,
  "installCursorRules": true,
  "postinstallGenerate": true,
  "postinstallWatch": true,
  "refreshIntervalMinutes": 0,
  "ai": {
    "enabled": false,
    "provider": "openai",
    "background": true
  }
}

.env overrides timer, debounce, and AI provider. Run npx cfpirates init --force to merge new config fields.

Programmatic API

import { runPipeline, loadConfig } from 'contextforge-cli-ai-prompt-pirates';

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

Security

• Static scan runs locally
• AI sends aggregated metadata only (not .env or full source)
• API keys stay in your .env (never published with the package)

Publish to npm

Before publish (maintainers):

npm test
npm run verify:pack
npm publish --access public

Full guide: PUBLISHING.md

After publish, users only need:

npm install -D contextforge-cli-ai-prompt-pirates-cli-ai-prompt-pirates

No file: link or local path required.

Troubleshooting

| Problem | Fix | |---------|-----| | No .contextforge after install | Do not use --ignore-scripts; check CONTEXTFORGE_AUTO_START | | Works locally, not from npm | Publish [email protected]; run npm run verify:pack | | Old name contextforge blocked on npm | Use contextforge-cli-ai-prompt-pirates (name context-forge was taken) | | Watch keeps running | npx cfpirates stop | | No Git history in context | Install Git and add to PATH |

License

MIT