mindforge-cc

MindForge

A governance and orchestration layer for Claude Code.

Claude Code alone runs one agent in one context. MindForge adds the parts that don't fit in a single context window: skills that auto-load by trigger, personas you can call by name, a wave-based executor that fans work out to fresh-context subagents and commits per task, a tamper-evident audit chain, and cost-aware routing across providers. Install it once and get /mindforge:plan-phase → /mindforge:execute-phase → /mindforge:verify-phase → /mindforge:ship as your actual working loop, not a slogan.

Jump to: Latest release · What you get · What is actually enforced · Install · Quick start · Documentation · Core workflow · Dynamic workflows

What you get

	Capability	Detail
🧩	221 slash commands	/mindforge:plan-phase, /mindforge:execute-phase, /mindforge:ship, and 218 more — full reference
🛠️	355 skills	232 auto-triggered by keyword match (engine tier) + 123 explicit, invoked by name (extended tier)
🎭	216 personas	In-session role overlays via /mindforge:agent <name> — same context, different behavioral spec
🤖	164 subagents	Genuine isolated-context Claude-Code-native subagent definitions — a separate mechanism from personas, see docs/PERSONAS.md
🔀	35 dynamic workflows	Multi-agent fan-out scripts across 5 tiers (Research, Dev, Ops, Intelligence, Beast) — workflow atlas
🔒	Tamper-evident audit chain	SHA-256 hash-linked .planning/AUDIT.jsonl; verify independently with node bin/verify-audit.js
💸	Cost-aware model routing	Anthropic / OpenAI / Gemini / Bedrock / Ollama, routed by task difficulty tier
🧠	Local-first knowledge graph	Zero-native-dependency SQLite (sql.js / WASM) — no native build step
📊	Live dashboard	Express + SSE at localhost:7339

Ships three ways: an npm package (npx mindforge-cc@latest), a Claude Code plugin marketplace entry, and an MCP server.

Install

Pick whichever matches how you work — all of these are real, live channels.

npx (recommended)

Writes .mindforge/ governance, memory, and planning into your project:

npx mindforge-cc@latest --claude --local      # Claude Code, this project only
npx mindforge-cc@latest --antigravity --local # Antigravity, this project only
npx mindforge-cc@latest                       # interactive wizard, pre-selects a detected runtime

The bare form only detects anything inside an interactive TTY wizard session, where it pre-selects — you still confirm — whichever runtime it finds. Run it non-interactively (CI, piped, scripted, or anywhere stdin isn't a TTY) and it skips the wizard entirely and installs --claude by default, regardless of what's actually on the machine.

Global (system-wide, for your primary AI coding runtime):

npx mindforge-cc@latest --claude --global

(npm install -g mindforge-cc@latest only puts the mindforge-cc/mindforge binaries on your PATH — it doesn't select a runtime or write anything. Run the command above, or the equivalent mindforge-cc --claude --global once installed, to actually scaffold a global setup.)

Other runtimes — same flag pattern, swap --global/--local:

Runtime	Flag
Claude Code	--claude
Antigravity	--antigravity
Cursor	--cursor
GitHub Copilot	--copilot
Gemini CLI	--gemini

Advanced: --runtime claude,cursor (combined runtimes) · --with-utils (installs local bin/ utilities) · --minimal (essential scaffolding only, no persona library) · --force (rewrite an existing .mindforge/MINDFORGE-SCHEMA.json with the current, stricter schema)

Claude Code plugin marketplace

No project files written — the plugin's hooks fire, see What is actually enforced for what that does and does not cover.

/plugin marketplace add sairam0424/MindForge
/plugin install mindforge@mindforge

Prefer just a slice (e.g. Python agents)? mindforge-lang@mindforge and 9 other focused packs exist — see docs/plugin-installation.md for all 10, token-budget guidance, and team setup.

Standalone MCP server

claude mcp add mindforge -- npx -y mindforge-mcp-server

Exposes 8 tools over stdio (6 read-only, 1 guarded write, 1 guarded browse proxy). Also listed on the MCP Registry as io.github.sairam0424/mindforge — that entry is republished manually and can lag; check what it actually serves before relying on it, or install mindforge-mcp-server from npm directly to pin a version.

Homebrew

brew install sairam0424/tap/mindforge

SDK

Build on MindForge programmatically:

npm i mindforge-sdk

Upgrading from 11.9.x? The installer does not overwrite an existing .mindforge/MINDFORGE-SCHEMA.json, so 11.9.2's armed config validator keeps the older permissive schema on a plain upgrade — run with --force for the stricter gate. The daily cost cap declared as [COST_HARD_LIMIT_USD] in MINDFORGE.md was not enforced in 11.9.2 (11.9.3 arms it), and an upgrade never rewrites an existing MINDFORGE.md — add [COST_HARD_LIMIT_USD] = 25.00 yourself if yours predates the key.

Full install matrix, plugin packs, and team-setup guidance: docs/getting-started.md.

Verify

These /mindforge:* commands require the Claude Code plugin or an npx/Homebrew framework install — the standalone MCP server exposes MCP tools instead, and mindforge-sdk exposes a programmatic API; neither installs these slash commands.

/mindforge:health              # framework + installation health check
/mindforge:health --repair     # documented in the command spec, but NOT wired into the CLI
                                # backing path — silently ignored, output is byte-identical to plain health
/mindforge:status              # project status snapshot
/mindforge:next                # auto-discover your first task

Full verification walkthrough: docs/quick-verify.md.

Quick start (new project)

/mindforge:init-project
/mindforge:plan-phase 1
/mindforge:execute-phase 1
/mindforge:verify-phase 1
/mindforge:ship 1

Quick start (existing codebase)

/mindforge:map-codebase
/mindforge:do I want to plan the next phase
/mindforge:plan-phase 1

Latest release

v11.9.8 (2026-09-21) — What the README claims, verified line by line. v11.9.7's README rewrite got a literal, end-to-end audit: every command it documents actually run — real npx installs, a real Homebrew install/uninstall cycle, a real npm i mindforge-sdk, live registry checks — instead of re-read for plausibility. 113 claims checked, 98 held up, 14 didn't, 1 couldn't be verified either way. Two of the 14 were real bugs: --runtime claude,cursor crashed the installer outright, and --minimal claimed "no persona library" but shipped all 216 anyway. Both fixed. The other twelve were documentation catching up to what the code actually does — a removed [--ads] hint that was never real, the auto-detect claim, --repair, --profile, the CLI spawn stub, the License holder, the skill-tier split, the bin/ line count, three Documentation-table rows that overstated their linked docs, and the mindforge-plugin-* namespace's empty catalog. See RELEASENOTES.md or CHANGELOG.md.

The previous release, v11.9.7, fixed a version self-contradiction and a false "Enabled" claim in the install banner, a dead docs.mindforge.cc link, and a persona-count doc regression (218 → back to the correct 216) introduced by v11.9.6's own honesty pass. v11.9.6 was the release-readiness pass before pointing real, external users at the project for the first time: fixed a crash in /mindforge:learn, a token-leak in the browser daemon, three dashboard panels that silently rendered nothing, a stale Homebrew formula, and docs describing PQAS/ZTAI/"Pillar"-numbered subsystems as live guarantees when the code already self-labels them simulated. v11.9.5 fixed a release pipeline that could strand itself mid-publish and shipped mindforge-sdk for the first time since 11.8.0, with provenance. v11.9.4, before that, is where the hook gates started actually registering: 11.9.3 shipped the code and then declined to run it on essentially every project. Measured against the published tarballs — 11.9.3: 11 hook scripts installed, 0 registered; 11.9.4: 8 registered, 3 deny-class verified blocking. That behaviour change under a patch bump still applies — the installer writes .claude/settings.json where it previously declined, merging append-only and backing up first. See the BREAKING section in CHANGELOG.md.

What is actually enforced

Read this before you rely on anything below blocking a bad command. MindForge ships a large corpus of agent instructions — commands, skills, personas, protocols — and those are advisory: they work by being in the model's context, and a model can decline them. The parts that would block an action are hooks. Through 11.9.2 no channel registered them. 11.9.3 added the registration code but it declined to run on almost every project, so in practice nothing was enforced there either. As of 11.9.4 both channels register and execute them on Claude Code, and nowhere else.

Capability	Plugin channel	npx channel
Slash commands	Yes	Yes
Skills / personas / protocol docs	Yes	Yes
Subagents	Yes	Yes
Audit hash-chain (bin/verify-audit.js)	Yes	Yes
Hooks enforced (can block a tool call)	Claude Code only	Claude Code + --local only

What that means, measured rather than asserted:

• The npx channel generates the config it never used to ship. files[] has 49 entries and none of them contains settings, so no settings file is published — instead bin/installer/hook-registration.js writes one at install time, merging append-only into any file you already have. Measured on a confined install: 8 hooks registered into .claude/settings.json, of which the installer's own preflight executed 7 and verified all 3 deny-class hooks returning exit 2 before keeping the file. A preflight failure rolls the registration back rather than leaving a config whose commands do not run.
• The plugin channel's dispatcher runs. It previously crashed on every fire — run-with-flags.js requires ./lib/hook-flags and plugins/mindforge/scripts/lib/ was not copied in. That directory now exists, all 14 path tokens in plugins/mindforge/hooks/hooks.json resolve under the plugin root, and driving the dispatcher by hand returns exit 2 for mindforge-block-no-verify and mindforge-config-protection.

Still not enforced, deliberately and with a printed reason for each: any runtime other than Claude Code (Cursor, Copilot, Gemini/Antigravity, OpenCode), --global scope, a self-install inside a MindForge checkout, and Windows. Writing a Claude-schema config into .cursor/ without an execution-verified hook contract would be decorative. Every outcome, including "not registered", is printed by the installer and written to .mindforge/hook-registration.json.

Three things gate whether a registered hook is live, none of them in MindForge's control: the harness must be restarted (hooks are snapshotted at session start), the project must be trusted in the harness, and CLAUDE_PROJECT_DIR must be set with node on the hook PATH — if it is not, the commands exit 1 and the gate is simply absent, which is a deliberate trade against a fail-closed tail that was measured denying benign commands on a fresh clone. See Hooks are installed but nothing is blocked in docs/troubleshooting.md.

So: on Claude Code, treat MindForge as a policy enforcement point for the 8 registered hooks plus a tamper-evident audit log; on every other harness, as governance-by-convention plus that same audit log. Installing it also expands your repository's trust boundary by a large volume of agent instructions — review what you install. The audit chain is verifiable today (node bin/verify-audit.js).

How it fits together

                     /mindforge:plan-phase N
                              |
                              v
   Skill Loader (trigger-match, tier: Project > Org > Core)
                              |
                              v
        Context Injector (<=60K tokens)  --> Cost Router
                              |             (Haiku / Sonnet / Opus / Gemini,
                              v              by task difficulty)
      Fresh-context Subagent (implement -> self-verify -> commit)
                              |
                              v
   Verification (build / typecheck / lint / test / security / diff)
                              |
                              v
        Handoff (.planning/HANDOFF.json + AUDIT.jsonl)

Four layers underlie this, top to bottom: Interface (.claude/, .agent/ — the 221 slash commands and hooks), Engine specs (.mindforge/ — 232 of the 355 skills plus 216 personas and config.json runtime knobs; the other 123 skills are extended-tier, under .agent/skills/), Execution (bin/, ~32K raw / ~25K stripped-of-comments LOC — the wave executor, governance, memory, and dashboard code that actually runs), and Persistence (.planning/ — STATE.md, the audit chain, resumable HANDOFF.json). Edit behavior in layer 2 where possible; layer 3 is the only place with real enforcement, per What is actually enforced above.

Documentation

Six categories, read in this order the first time:

Category	Doc	Read this when
Start here	Getting started	Installing for the first time
Start here	Quick verify	Right after install — confirm it actually works
Start here	User guide	Learning the day-to-day command loop
Start here	Full tutorial	Want a guided walkthrough instead of reference docs
Reference	Commands (full) / Commands (quick)	Looking up a specific /mindforge:* command
Reference	Config reference	Editing MINDFORGE.md — this doc doesn't cover .mindforge/config.json
Reference	SDK API / Skills API	Building on mindforge-sdk or authoring a new skill
Reference	Audit events	Parsing .planning/AUDIT.jsonl
Reference	Workflow atlas	Choosing one of the 35 dynamic workflows
Reference	Requirements	Checking supported Node/OS versions before install
When something's wrong	Troubleshooting	A command or hook isn't behaving as documented
When something's wrong	FAQ	Common questions before filing an issue
When something's wrong	Upgrade guide	Moving between major/minor versions
Security	SECURITY.md	Reporting a vulnerability; credentials are read from env vars and never committed
Security	Threat model	Historical only — scoped to the v1.0.0 predecessor, not re-reviewed against v11.x; see SECURITY.md for what's actually enforced today
Contributing	Architecture	Understanding the codebase before sending a PR
Contributing	Contributing guide	Sending a PR
Contributing	CI quickstart	Understanding what CI checks before you push
Contributing	Release checklist	Cutting a release
Reference	USPs and features	The same "measured, not asserted" honesty pass applied to what's actually shipped — no competitor comparison
Release notes	RELEASENOTES.md	What changed, in prose, per version

Core workflow

Command	What it does
/mindforge:init-project	Requirements interview → creates PROJECT.md, REQUIREMENTS.md, STATE.md
/mindforge:plan-phase 1	Discuss scope, research the domain in parallel, create atomic XML task plans
/mindforge:execute-phase 1	Wave-based parallel execution, one commit per task, automated verification
/mindforge:verify-phase 1	Human acceptance testing, debug agent on failures, UAT sign-off
/mindforge:ship 1	Changelog generation, final quality gates, PR creation
/mindforge:auto --phase 1	Walk-away autonomous execution with stuck detection and steering

Full command list: docs/commands-reference.md.

Dynamic Workflow Library

35 pre-built multi-agent workflow scripts that run via Claude Code's Workflow tool. Each fans out concurrent agents, synthesizes results, and returns structured output across 5 tiers (Research, Dev, Ops, Intelligence, Beast).

Discover: /mindforge:wf-catalog or node bin/mindforge-cli.js workflow list

Full, verified 35-workflow table by tier: docs/workflow-atlas.md.

Execution modes

MindForge supports multiple interaction models to fit your engineering workflow:

• In-IDE Orchestration: Use /mindforge:agent <persona> for real-time delegation.
• Enterprise Workflows: Specialized commands like /mindforge:wf-tdd-sprint and /mindforge:plan-phase.
• CLI Automation: node bin/mindforge-cli.js spawn <persona> exists but is a v1.0 stub — it prints "NOT IMPLEMENTED in v1.0" and exits 1, redirecting you to /mindforge:auto or /mindforge:next instead.

Updates and migrations

Run /mindforge:update (add --apply to install) — see docs/upgrade.md for the full upgrade guide and fallback steps.

Plugin system (v1.0.0)

Plugins extend MindForge via the mindforge-plugin-* namespace. No packages are currently published under it — this is the mechanism, not a catalog.

/mindforge:plugins list
/mindforge:plugins install mindforge-plugin-<name>
/mindforge:plugins validate

Token usage profiling

/mindforge:tokens --optimise

(--profile doesn't exist; real flags are --phase N, --session ID, --window short|medium|long, and --optimise.) See .mindforge/production/token-optimiser.md.

License

MIT © 2026 Sairam Ugge (GitHub: Sairam0000)