Skip to main content
Glama
counterfactual-forge

counterfactual-forge

by SanjoyDat1

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

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

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • -
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables AI agents to branch, score, prune, and merge conversation strands with provenance and timeline export. Provides MCP tools and resources for managing parallel exploratory strands.
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      A Git-like version control system for AI agent decision tracking, enabling plan commits, diffs, branches, and history.
      Apache 2.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to be governed by formal Gentzen sequent calculus proof trees, with human-in-the-loop approval gates and cryptographic audit trails for consequential actions.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables agents to route every action through a pre-execution gate that returns allow, escalate-to-human, or deny verdicts, backed by deterministic hard-rule blocks plus probabilistic gray-zone scoring, and to run a resumable orchestration loop covering routing, quality gates, stop-loss, acceptance, and escalation. Every decision, arbitration between conflicting agents, and human approval is written to an append-only hash-chained, Ed25519-signed ledger that can be postmortemed, calibrated, alert-scanned, and exported as offline verification bundles or OTel spans.
      1
      MIT