ContextForge CLI 🛠️

Stop re-explaining your project context to AI.

ContextForge is a background agent and command-line utility for Node.js developers. It automatically tracks your codebase file structure, active Git history (branch, status, commits, and diffs), technological stack constraints, and Architectural Decision Records (ADRs) to compile a live "Context Twin" of your project in a single Markdown file (.contextforge/context_twin.md).

When you open ChatGPT, Claude, or Cursor, you can inject your complete, up-to-date project context with a single command—no manual copy-pasting, no briefing exercises.

🚀 Key Features

• 🔍 Zero-Config Tech Stack Scan: Automatically detects libraries (React, Next.js, Vite, Express, TypeScript, Tailwind, Mongoose, PostgreSQL, etc.) by inspecting package.json and config files.
• 🌿 Live Git Context Tracker: Captures active branch name, recent 5 commit messages, dirty files status, and a summarized code diff of active unstaged work.
• 📐 Interactive ADR Generator: Standardizes architectural decisions (ADR-001, ADR-002, etc.) via a user-friendly CLI prompt and logs them in .contextforge/adr/.
• 📂 Lightweight ASCII File Tree: Generates clean codebase visual mappings while respecting .gitignore and custom folder/file exclusions.
• 📋 Zero-Dependency Native Clipboard copy: Instantly copies the compiled context to your system clipboard using native binaries (Set-Clipboard on Windows, pbcopy on macOS, xclip/xsel on Linux), avoiding heavy native compiler dependencies.

🛠️ CLI Command Reference

Once installed, use the following commands inside any project:

1. Initialize ContextForge

contextforge init

Walks through a brief interactive setup to configure your project name, description, custom tech stack overrides, AI coding rules, and files to ignore. Saves configuration to .contextforge/config.json.

2. Build Context Twin

contextforge build

Scans your directory structure, active git state, and ADR folder to generate .contextforge/context_twin.md. Copies the entire content to your clipboard automatically.

3. Add Architectural Decision Record (ADR)

contextforge add-adr

Interactive prompt to create a new Architectural Decision Record under .contextforge/adr/ADR-XXX-title.md (e.g. tracking why a specific database, state-management framework, or deployment route was chosen). Rebuilds the context twin automatically.

4. Check Status

contextforge status

Outputs a quick status overview detailing initialization directories, active git branch, ADR count, twin size, and last update time.

📦 Step-by-Step Publishing & Testing Guide

This guide describes how to link and run ContextForge locally or publish it to the global npm registry.

A. Local Testing & Verification (Using npm link)

npm link allows you to install your local package globally on your machine without publishing it to NPM yet.

1. Open terminal in the package directory (d:\D Drive\ayush\NPM\NODE_PACKAGE\).
2. Link the package:

   npm link

   (Note: On Windows, you might need to run terminal as Administrator. This creates a global symlink pointing to your local directory).
3. Navigate to another test Node.js project:

   cd C:\path\to\your\test-project

4. Link the command into the test project:

   npm link contextforge-cli

5. Run the CLI:
   • contextforge init (creates config and folders)
   • contextforge add-adr (adds a new decision)
   • contextforge build (compiles and copies to clipboard)
   • Check the clipboard by pasting (Ctrl+V) into your text editor!

B. Publishing to NPM Registry

To make the package installable by anyone (npm install -g contextforge-cli), publish it to the NPM registry:

1. Register an NPM Account: If you don't have one, sign up at npmjs.com.

2. Login from CLI: Run the login command in your terminal:

   npm login

   This will prompt you for your username, password, email, and one-time password (OTP).

3. Check Package Name Uniqueness: NPM requires unique package names. In package.json, change "name": "contextforge-cli" to a unique name if you find that contextforge-cli is already taken (e.g. @yourusername/contextforge-cli or contextforge-ayush).

4. Publish Package: Run the publish command:

   npm publish

   (For scoped packages like @yourusername/contextforge-cli, use npm publish --access public to allow free public downloads).

5. Verify & Install Externally: Go to any computer/directory and run:

   npm install -g contextforge-cli

   Test it anywhere:

   contextforge status

🤖 Context Twin Markdown Schema

The compiled .contextforge/context_twin.md has the following schema structure, making it ideal for LLM ingestion:

• Header Info: Generator timestamp & project name.
• Rules & Overviews: Custom development rules and full technology stack.
• Directory Tree: ASCII tree representation.
• Git Context: Active branch, last 5 commit summaries, changed files, and code changes diff.
• Architectural Log: Beautiful Markdown table summarizing ADRs.

Now, whenever you open ChatGPT/Claude/Cursor, just run contextforge build and press Ctrl+V. Your AI assistant is instantly briefed!