Quickstart

Get from zero to a configured repo and your first substrate check in about a minute.

1. Install

/plugin marketplace add CodeWithJuber/forgekit
/plugin install forgekit

npm install -g @codewithjuber/forgekit

npm install -g github:CodeWithJuber/forgekit

The plugin path is recommended for Claude Code and Codex — the guards auto-wire and there is nothing to merge. See Installation for the full matrix, including the symlink dev setup.

2. Configure a repo

Emit every tool's config

cd ~/your-project
forge init

This emits AGENTS.md, CLAUDE.md, .gemini/settings.json, .aider.conf.yml, and the rest — plus the .gitattributes union-merge rule the ledger needs. Claude Code, Codex, Cursor, Gemini, Aider, Copilot, Windsurf, Zed, Continue, and OpenClaw now read the same rules, each from its own native file. On OpenClaw the MCP server is one extra command: openclaw mcp add forge-cortex --command forge --arg cortex-mcp.

Health-check the setup

forge doctor

A pass/fail check of installed tools, guards, MCP auth, and config drift.

Change a rule later

Edit source/rules.json (or drop a per-repo .forge/rules.json), then recompile:

forge sync

sync is idempotent — it only rewrites what changed.

3. Run the pre-action gate

The substrate is the layer that runs before the model edits code. One command runs the whole gate:

forge substrate "Change verifyToken in src/auth.js to require length > 20; update tests"
#   → assumption verdict · cheapest capable model · predicted blast radius
#     (including files you didn't name) · scope clusters · verification checklist

On Claude Code the substrate runs on every prompt automatically via a UserPromptSubmit hook — advisory only, silent on clean tasks. Every other tool gets a native config rule plus 21 MCP tools it can call itself.

If forge substrate says ASK FIRST, ask the returned questions before editing. Read the predicted impacted files — the blast radius — before any mutating change.

forge substrate "<task>" --json   # machine-readable verdict
forge impact <symbol-or-file>     # the blast radius on its own

4. Explore the extras

forge atlas build          # index this repo's symbols → .forge/atlas.json
forge atlas query useAuth  # where is it defined? (cheaper than grep-and-read)
forge atlas has useAuth    # does it exist? "not found" = likely hallucinated
forge recall add "db port" "Postgres is on 5433 here, not 5432"
forge catalog              # the Start-Here index of everything

5. Day two: the ledger is learning

Everything the substrate learned on day one landed as claims in .forge/ledger/. This is proof-carrying memory — now it starts paying off:

forge ledger stats                              # what the repo knows, by kind and trust
forge ledger blame <id-prefix>                  # who minted a claim, every oracle outcome
forge reuse query "<what you're about to build>"  # verified code you already have

Keep going

Read how the pre-action gate composes its stages into one verdict.

Get started

Core concepts

1. Install

2. Configure a repo

3. Run the pre-action gate

4. Explore the extras

5. Day two: the ledger is learning

Keep going

​1. Install

​2. Configure a repo

​3. Run the pre-action gate

​4. Explore the extras

​5. Day two: the ledger is learning

Keep going

1. Install

2. Configure a repo

3. Run the pre-action gate

4. Explore the extras

5. Day two: the ledger is learning