Skip to main content
ContextForge

How ContextForge Works

A static public registry. A thin CLI. Instructions installed straight into your repo.

The flow

1.ContextForge fetches the registry index and finds the requested pack.
2.It fetches the pack's manifest (pack.json) from the registry.
3.It downloads the relevant pack files for each AI tool you selected.
4.Writes tool-specific instructions under .contextforge/agents/.
5.Updates config.json (desired state) and lock.json (resolved state).
6.Creates tiny root pointer files — AGENTS.md and/or CLAUDE.md.

Registry resolution

The CLI fetches the registry index, finds the pack by name, and resolves its file paths relative to the registry base URL. No hardcoded pack data lives in the CLI itself — everything comes from the live registry at install time.

js
// Simplified resolution
const index = await fetch("https://registry.contextforge.org/index.json");
const packMeta = index.packs["nextjs-best-practices"];
// → { path: "packs/nextjs-best-practices/pack.json", ... }

const manifest = await fetch(registryBase + packMeta.path);
// Downloads: agents.md, claude.md, skill.md, cursor.mdc, copilot.md

Why root files stay tiny

AI tools like Codex read AGENTS.md and Claude Code reads CLAUDE.md at the project root. These files could bloat quickly if every pack wrote its full content there.

ContextForge keeps them as tiny pointers. The real instruction content lives inside .contextforge/. Agents that follow the pointer get the full instructions; agents that ignore it still get a clean root.

AGENTS.md
# AGENTS.md (tiny pointer — not the real instructions)

<!-- contextforge:start -->
ContextForge is installed for this repo.
Before working, read: .contextforge/agents/codex/
Follow packs listed in .contextforge/config.json.
<!-- contextforge:end -->

Registry is versioned independently

The registry is a separate GitHub repository. New packs and pack updates can be published without releasing a new CLI version. The CLI always pulls the current state of the registry.

Registry source: github.com/Alone-Y154/ContextForge-registry

Next: Project Structure