ContextForge

Stop re-explaining your project every AI session.

ContextForge builds a live Context Twin (.contextforge/context.md) from your codebase, git history, and captured decisions—then keeps it updated automatically.

Quick Start

npm install contextforge-cli

On install (automatic):

1. Creates .contextforge/context.md (first time)
2. Starts background watcher — no need to run watch manually
3. Installs git post-commit hook for commit sync

Optional:

npx contextforge sync
npx contextforge watch status

Cursor: ContextForge creates .cursor/rules/ if missing and writes contextforge-context.mdc (alwaysApply: true) on every sync.

Reload Cursor after first install → new chat uses full project context.

Customize team standards: edit .contextforge/team-context.md (created on first init).

Commands

| Command | Description | |---------|-------------| | contextforge init | First-time setup | | contextforge sync | Refresh context.md (+ Cursor rule if .cursor/rules/ exists) | | contextforge watch | Auto-update on file changes | | contextforge watch status | Show running watcher(s) | | contextforge watch stop | Stop all watchers for this project | | contextforge capture "..." | Log important prompt / decision | | contextforge capture --decision "..." | Record architectural decision | | contextforge inject | Copy context to clipboard (optional) |

What updates automatically

| Trigger | Updates | |---------|---------| | File/folder change (watcher) | context.md + Cursor rule (if rules dir exists) | | Git commit (post-commit hook) | Same via sync -q | | contextforge sync | Manual refresh |

Config (.contextforge/config.json)

{
  "watch": { "mode": "all", "debounceMs": 20000, "autoWatch": true },
  "gitHook": { "enabled": true }
}

Skip postinstall: CONTEXTFORGE_SKIP_POSTINSTALL=1
Disable auto watcher on install: CONTEXTFORGE_AUTO_WATCH=0 npm install contextforge-cli

Publish (maintainers)

npm login
npm publish --access public

Project layout

your-project/
├── .contextforge/
│   ├── context.md          ← generated locally (gitignored)
│   ├── config.json
│   └── prompts.jsonl
└── .cursor/rules/              ← you or Cursor create this
    └── contextforge-context.mdc ← auto-synced when folder exists

License

MIT