Counterfactual Forge

What-if branching for AI agents. Fork a plan into counterfactual worlds, score them with rubrics + simulated outcomes (confidence intervals), detect contradictions, measure regret, and merge a winner — with a full audit trail.

Expose the whole loop as an MCP server so Cursor / Claude / any MCP client can fork → score → merge from tools.

Packages

Package	Role
@counterfactual-forge/core	Deterministic domain model + fork/score/compare/merge/export
@counterfactual-forge/mcp-server	Stdio MCP tools (cf_*)
@counterfactual-forge/cli	cff / counterfactual-forge CLI
@counterfactual-forge/studio	Vite studio to inspect world trees & scores

Quick start

git clone https://github.com/SanjoyDat1/counterfactual-forge.git
cd counterfactual-forge
npm install
npm run build
npm test
npm run cff -- demo --out /tmp/cff-report.md

Studio UI:

npm run studio
# → http://localhost:5173

MCP (Cursor)

Add to your MCP config (e.g. Cursor mcp.json):

{
  "mcpServers": {
    "counterfactual-forge": {
      "command": "node",
      "args": [
        "/ABSOLUTE/PATH/TO/counterfactual-forge/packages/mcp-server/dist/index.js"
      ]
    }
  }
}

Or after publishing / linking:

{
  "mcpServers": {
    "counterfactual-forge": {
      "command": "npx",
      "args": ["-y", "counterfactual-forge-mcp"]
    }
  }
}

Tools

Tool	Description
cf_create_session	Create session + baseline world from goal + steps
cf_fork_worlds	Fork N strategies (aggressive, conservative, parallel, minimal, custom)
cf_score_world	Rubric scores + seeded simulation + confidence interval
cf_compare	Ranking, regret, contradiction detection
cf_merge_winner	Select winner via merge policy
cf_get_audit_trail	Append-only audit events
cf_export_report	Export json / markdown / mermaid

Example agent flow

1. cf_create_session with goal + plan steps
2. cf_fork_worlds with aggressive + conservative (+ optional others)
3. cf_score_world for each forked world
4. cf_compare → inspect regret & contradictions
5. cf_merge_winner
6. cf_export_report (markdown) for the decision record

CLI

npx cff demo
npx cff create --goal "Ship X" --steps examples/fixtures/auth-redesign-steps.json
npx cff fork --session <id> --strategies aggressive,conservative,minimal
npx cff score --session <id> --world <id>
npx cff compare --session <id>
npx cff merge --session <id> --mode min_regret
npx cff export --session <id> --format mermaid

Sessions are in-memory per process — export / import to persist.

Creative metrics

• Confidence intervals on overall scores (from outcome simulation percentiles)
• Regret — how many points worse than the best alternative
• Contradiction detection across assumptions / risks / strategy tags
• Mermaid world-tree export embedded in Markdown reports

Architecture

See docs/ARCHITECTURE.md and docs/PLAN.md.

Development

npm run typecheck
npm run test:coverage   # core ≥80%
npm run build

Logging uses stderr only (CFF_LOG_LEVEL=debug|info|warn|error|silent) — safe for MCP stdio.

License

MIT