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

Related MCP server: pvc-mcp-server

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

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